# Air-Gapped Install

*A full production install of Aura with no outbound internet access. Offline bundles, pre-built tree-sitter grammars, and verified supply chain.*

## Overview

A meaningful share of Aura's enterprise users — defense contractors, regulated financial institutions, hospital systems, classified research facilities — operate build environments with no outbound internet at all. The engine was designed for this case from the first release, not retrofitted.

Every artifact required to run Aura in production is available as a single signed bundle. No step of a first-time install reaches out to the public internet. The bundle includes the CLI, the Mothership server, every supported tree-sitter grammar pre-compiled for the target architecture, all Rust runtime dependencies, container images as OCI tarballs, and a complete checksum manifest signed with Naridon's release key.

This page walks through three things: what is in the bundle, how to verify it, and how to install from it into a disconnected environment.

## The offline bundle

The bundle is distributed as a single tarball. Customers on a commercial agreement receive download links through the support portal; open-source users can download public bundles from the signed GitHub release page.

Bundle contents:

```text
aura-offline-0.14.1-linux-amd64.tar.zst
├── MANIFEST.json            # every file, its sha256, and its role
├── MANIFEST.json.sig        # detached signature, cosign-compatible
├── bin/
│   ├── aura                 # CLI, statically linked
│   └── aura-mothership      # server, statically linked
├── images/
│   ├── aura-mothership.oci.tar
│   └── postgres-15.oci.tar  # optional, for sealed installs
├── grammars/
│   ├── rust.so
│   ├── python.so
│   ├── typescript.so
│   ├── go.so
│   └── ...                   # all supported languages
├── schema/
│   └── migrations/           # Postgres schema
├── docs/
│   └── runbook-airgapped.pdf
└── tools/
    ├── verify.sh             # checksum + signature verifier
    └── install.sh            # idempotent installer
```

The bundle is around 380 MB compressed for the Linux amd64 build. Other architectures (linux-arm64, darwin-arm64, windows-amd64) ship as separate bundles with identical layout.

## Verifying the bundle

Verification uses `cosign` in keyless-free mode. The public signing key is published at `naridon.com/signing-key.pub` and also pinned in the [Enterprise Support](/enterprise-support) onboarding pack, so you can copy it across your air gap without trusting any network path.

```bash
# On a machine inside the air gap, after transferring the bundle:
cosign verify-blob \
  --key naridon-signing-key.pub \
  --signature aura-offline-0.14.1-linux-amd64.tar.zst.sig \
  aura-offline-0.14.1-linux-amd64.tar.zst

# Extract and verify file-level checksums:
tar --zstd -xf aura-offline-0.14.1-linux-amd64.tar.zst
cd aura-offline-0.14.1
./tools/verify.sh
```

Expected output:

```text
verifying MANIFEST.json signature... OK
verifying 142 files against manifest... OK
all checksums match. bundle is intact.
```

The `verify.sh` script exits non-zero on any mismatch. Make it a gate in your provisioning automation.

## Installing from the bundle

The included `install.sh` is idempotent and performs the following:

1. Copies `bin/aura` and `bin/aura-mothership` into `/usr/local/bin`.
2. Installs pre-compiled tree-sitter grammars into `/var/lib/aura/grammars`.
3. Loads the OCI image tarballs into the local container runtime if one is present.
4. Writes a default `/etc/aura/config.toml` with sensible air-gapped defaults (no telemetry, no update checks).

```bash
sudo ./tools/install.sh --prefix /usr/local --data-dir /var/lib/aura
```

For teams who prefer to drive installs through configuration management, every action the script performs is documented in the runbook and can be expressed directly in Ansible, Chef, Puppet, or SaltStack.

## Pre-built tree-sitter grammars

Normally, Aura compiles tree-sitter grammars on demand when it first encounters a new language. That default requires a working C toolchain and, in some builds, network access to fetch grammar repositories. Neither is acceptable in an air-gapped environment.

The offline bundle ships **pre-compiled grammars** as shared objects (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows) built against the same Aura release. Each grammar is reproducibly built from a pinned commit of the upstream grammar repository, and the pin is recorded in `MANIFEST.json`:

```json
{
  "grammars": [
    {
      "language": "rust",
      "upstream": "tree-sitter/tree-sitter-rust",
      "commit": "1f63b33efee17e833e0ea29266dd3d713e27e321",
      "sha256": "…",
      "file": "grammars/rust.so"
    }
  ]
}
```

Aura detects the pre-built grammars at startup by reading `/var/lib/aura/grammars` and refuses to fall back to online fetching when the `offline` flag is set.

## Configuration for air-gapped operation

Set two flags in `config.toml` to make the air-gapped posture explicit:

```toml
[runtime]
offline = true
telemetry = "off"

[update]
check_enabled = false

[grammar]
loader = "prebuilt"
directory = "/var/lib/aura/grammars"
```

With `runtime.offline = true`, Aura refuses to make any outbound connection for any reason. A code path that attempts to reach the public internet — for example, the optional anonymous usage telemetry — returns a hard error instead of degrading silently.

## Applying updates across an air gap

Naridon publishes release bundles on a predictable cadence. Enterprise customers additionally receive security bundles, which contain only the changed binaries plus a patch manifest. A security bundle is installed with:

```bash
sudo ./tools/install.sh --patch aura-security-0.14.2.tar.zst
```

The installer verifies the patch manifest against the currently installed `MANIFEST.json` and refuses to apply a patch built against a different base version.

For customers with strict change-control windows, every bundle ships with a deterministic rollback script:

```bash
sudo ./tools/rollback.sh --to 0.14.1
```

Rollback reverts binaries and grammars. It does **not** revert Postgres schema migrations; those are forward-only and documented in the release notes.

## Supply chain evidence

Every bundle is accompanied by a CycloneDX SBOM and an in-toto attestation chain that proves:

- The source commit that produced the binaries.
- The CI build environment (image digest, builder identity).
- The reproducibility hashes of the grammar compilation steps.

Auditors and security teams can verify the attestation chain offline with `cosign verify-attestation` using the pinned public key. A machine-readable summary is included as `MANIFEST.provenance.json`.

> For customers subject to Executive Order 14028 (US) or the Cyber Resilience Act (EU), these artifacts are the evidence your program office will ask for. We ship them by default.

## Container images without a registry

In fully disconnected environments where even a local registry is unavailable, the OCI tarballs under `images/` can be loaded directly:

```bash
# Docker
docker load -i images/aura-mothership.oci.tar

# containerd
ctr -n k8s.io images import images/aura-mothership.oci.tar

# Podman
podman load -i images/aura-mothership.oci.tar
```

Each image tarball is also signed; `verify.sh` checks the image manifest digest against the signed release record.

## Postgres in a sealed environment

Aura does not require a specific Postgres build. Customers frequently use their standard internal Postgres image. The bundle includes a reference `postgres-15.oci.tar` for convenience, but there is no dependency on that specific image.

Schema migrations are shipped as plain SQL files under `schema/migrations/` and can be applied with `psql` directly, or via the included migrator:

```bash
aura-mothership migrate --db postgres://aura@db.internal/aura
```

Forward-only migrations, each wrapped in a transaction. Every migration file starts with a version number and a human-readable name, so change-control reviews can be performed without running any code.

## Operating Mothership in an air gap

Once installed, the air-gapped Mothership behaves identically to an online one, with two differences:

1. It will never attempt to fetch new grammars, even when a previously-unseen language appears in a pushed commit. Instead, it emits a metric (`aura_grammar_missing_total`) and records the unparsed file as a byte-level diff, preserving correctness at the cost of AST-level granularity for that specific file until you ship a bundle update.
2. The CLI's `aura update` command is compiled out. Update bundles must be applied through configuration management or by hand.

All peer-to-peer sync, intent logging, Sentinel messaging, and zone enforcement work without modification.

## Disconnected agent fleets

Sentinel (AI-agent messaging) works fully offline. Agents running inside the air gap exchange messages through the local Mothership with no outside dependency. This is the recommended posture for classified research facilities running large autonomous agent populations.

## Telemetry and phone-home behavior

Aura has no mandatory phone-home. The open-source build includes optional anonymous usage telemetry that is **off by default** and cannot be silently re-enabled. The air-gapped install scripts explicitly compile out the telemetry code path, producing a binary that has no code for external network calls except to the customer-configured Mothership endpoint. A network-level monitor sitting in front of an air-gapped Aura deployment should see traffic only to the addresses explicitly configured in `config.toml` — no CDN, no usage pixel, no update check, no crash reporter.

This is verifiable. The `aura` CLI ships with a `--network-audit` flag that logs every outbound connection attempt to stderr:

```bash
aura --network-audit status
```

```text
[network-audit] connect aura.internal.example.com:3001 (configured mothership)
[network-audit] total outbound attempts in this invocation: 1
```

Customers with strict change-control regimes use this as a smoke test in their onboarding automation.

## Change control for air-gapped deployments

Air-gapped customers tend to have formal change-control processes, and the bundle layout was designed to fit inside them. Each bundle ships with:

- A plain-English **change summary** in `CHANGES.md` at the bundle root.
- A **machine-readable diff** against the previous release (`CHANGES.json`) listing binary sizes, new files, removed files, and grammar version bumps.
- A **rollback bundle** pinned to the previous release, so that a change-advisory board can approve both the forward and backward paths in a single review.

We have customers who approve Aura updates through a weekly change-board meeting using only these artifacts, without any access to a GitHub page or external website.

## Known air-gapped limitations

Worth stating plainly:

- **No public signatures for release artifacts.** Signature verification uses a pinned public key transferred across the gap once, at onboarding. If your threat model assumes that the pinning step itself was compromised, no downstream verification helps; Naridon ships the pinned key through the support portal and through commercial-tier onboarding letters to reduce this risk.
- **No automatic CVE notification.** Customers on the commercial tier receive security bundles plus a paper-based advisory. Open-source air-gapped users should subscribe to the security mailing list and handle transfer manually.
- **No crash reporting.** A crash in an air-gapped Mothership has to be investigated locally, from logs and from core dumps if your operating environment produces them. The mothership's verbose-trace endpoint is the main tool for reproducing issues without leaving the gap.

## See Also

- [Self-Hosted Deployment](/self-hosted-deployment)
- [Compliance & Audit](/compliance-and-audit)
- [Backup & Recovery](/backup-and-recovery)
- [Enterprise Support](/enterprise-support)