---
title: Air-gapped install
description: Build one verified archive of venom on a connected machine with make airgap, carry it to a machine with no network, install it with checksum and signature checks, and bring your own model.
section: deploy
order: 70
audience: [operator]
sources: [docs/airgap.md, scripts/release/airgap.sh, docs/docs-site.md, scripts/docs-site]
features: [deploy.airgap]
---

venom runs with the network unplugged: the orchestrator fronts a model server on the same machine or network, the CLI talks to the orchestrator, and neither calls out unless you turn on mesh mode or the daemon's auto-update. What an air-gapped site lacks is a way to get venom and a model onto the machine. This page is that: one archive you build once, carry on any medium, verify and install with no network.

## Quick start {#quick-start}

On a connected build machine with a venom checkout:

```bash
make release VERSION=0.1.0                              # see Releases and signatures
make airgap VERSION=0.1.0 AIRGAP_TARGETS="linux/x64"
# → dist/airgap/0.1.0/venom-airgap-0.1.0-linux-x64.tar.gz  (+ SHA256SUMS, and SHA256SUMS.minisig when signed)
```

Carry the archive and the `SHA256SUMS` beside it to the target, then:

```bash
sha256sum -c SHA256SUMS                                  # the archive against the list you carried
tar -xzf venom-airgap-0.1.0-linux-x64.tar.gz && cd venom-airgap-0.1.0-linux-x64
./install.sh --verify                                    # check every file inside, install nothing
./install.sh                                             # → ~/.local
```

## Building the bundle {#build}

`make airgap VERSION=x.y.z` downloads nothing and builds nothing itself: it repackages the files `make release` produced in `dist/release/<v>/`. When that directory is missing it builds the release first without Docker images, so the only network use is the release build's own (the npm registry for production installs, and nodejs.org for the pinned Node.js, checked against pinned hashes). Each file is checked against the release's `SHA256SUMS` on the way in, and the CLI archive goes through the release's secret-and-private-content check again.

| Variable | Default | What it does |
|---|---|---|
| `AIRGAP_TARGETS` | this machine's | Space-separated `os/arch`: `darwin/arm64`, `darwin/x64`, `linux/x64`, `linux/arm64`. One bundle each. Windows is not offered (the installer needs a POSIX shell). |
| `AIRGAP_DAEMON` | `1` | Include the desktop daemon archive; `0` leaves it out. |
| `AIRGAP_IMAGES` | `0` | `1` also `docker save`s the orchestrator and console images. The release must have been built with `RELEASE_IMAGES=1`, and Docker must run. |
| `AIRGAP_MODELS` | none | A directory of model files you name (GGUF files, an Ollama `models` tree), copied into `models/` and listed in the bundle's checksums. |
| `VENOM_RELEASE_MINISIGN_KEY` | unset | Signs `dist/airgap/<v>/SHA256SUMS`, like a release's. |

Model weights are never built into the bundle by default. `AIRGAP_MODELS` only copies a directory you point at.

## What is in it {#contents}

```text
venom-airgap-<v>-<os>-<arch>/
  README.txt  install.sh  VERSION  SHA256SUMS
  release/   venom-<v>-<os>-<arch>.tar.gz          the CLI with the pinned Node.js inside
             venom-cli-<v>.tar.gz                  the CLI package
             venom-orchestrator-<v>-<os>-<amd64|arm64>
             venom-daemon-<v>-<os>-<arch>.tar.gz   launcher, orchestrator, console, Node.js (AIRGAP_DAEMON=1)
             orchestrator.yaml  prices.yaml  install.sh  venom-<v>.cdx.json
             venom-harness-<v>.tgz  venom-harness-server-<v>.tgz  venom_client-*
             SHA256SUMS  [SHA256SUMS.minisig]
  docs/airgap.md  models/README.md  [models/…]  [images/venom-images-<v>.tar]
```

The bundle's own `SHA256SUMS` lists every file in it. The airgap bundle is not a published release asset: it is large, and each site builds it for its own platform.

## Installing {#install}

`./install.sh` is POSIX `sh` using only `tar`, `sha256sum` or `shasum` and the files beside it: no Node.js, no root, no network. In order, it:

1. checks every file against the bundle's `SHA256SUMS`; a damaged or edited copy stops here;
2. runs the release's own `install.sh --from release --runtime-from <the self-contained archive>`, which checks `release/SHA256SUMS` against its minisign signature (when there is one and `minisign` is installed), checks every file against it, then installs `lib/venom/<v>/`, `bin/venom`, `bin/venom-orchestrator`, `share/venom/{orchestrator.yaml,prices.yaml,client-key}` and the Node.js runtime, so the machine needs no Node;
3. with `--daemon`, unpacks the daemon into `lib/venom-daemon/<release>/` and links `bin/venom-daemon`; with `--load-images`, `docker load`s `images/*.tar`.

| Option | What it does |
|---|---|
| `--verify` | Check every file; install nothing. |
| `--prefix DIR` | Install under `DIR` instead of `~/.local`. |
| `--daemon` | Also install the desktop daemon. |
| `--load-images` | Also load the Docker images. |

Nothing is installed if a check fails. The orchestrator's client key is generated on the machine (`share/venom/client-key`, mode 600) and never printed.

**The signature.** A signed release carries `release/SHA256SUMS.minisig`, and the public key is written into the release's `install.sh`. With `minisign` on the target the installer verifies it and prints `verified SHA256SUMS signature`. Without `minisign` it says so and trusts the checksums, which catch a damaged copy but not someone who changed both a file and the list. To close that gap, carry `minisign` (or check the signature on a connected machine) and set `VENOM_REQUIRE_SIGNATURE=1` so a missing check is fatal. [Releases and signatures](/docs/deploy/releases.md#verify) has the manual check.

## Models {#models}

The bundle has none unless you added `AIRGAP_MODELS`. Pick a model on a connected machine, record its `sha256sum`, carry it, compare. Then:

- **Ollama** (the shipped config): copy the `models` tree of a machine that ran `ollama pull`, or `ollama create <name> -f Modelfile` from a GGUF file (`FROM ./file.gguf`). The config uses `VENOM_OLLAMA_MODEL` (default `qwen3:8b`) and `VENOM_OLLAMA_FAST_MODEL` (default `qwen3:4b`).
- **llama.cpp**: `llama-server -m model.gguf`, and an upstream of `kind: llamacpp` in `orchestrator.yaml`.
- **vLLM**: carry the Hugging Face model directory, run `HF_HUB_OFFLINE=1 vllm serve /models/<dir>`, and set `VLLM_MODEL=/models/<dir>`.

Ollama, llama.cpp and vLLM are installed the way you install any software on that site; they are not in the bundle. `venom doctor` says which upstream is unreachable and which model is missing.

## Running {#run}

```bash
venom-orchestrator >> ~/.local/share/venom/orchestrator.log 2>&1 &
export VENOM_API_KEY="$(cat ~/.local/share/venom/client-key)"
venom doctor
venom --offline
```

The orchestrator listens on `127.0.0.1:8787`. To serve others on the LAN, set `VENOM_LISTEN=0.0.0.0:8787`; it then insists on a client key, which the install made. With `--daemon`, `venom-daemon start --no-open` runs the orchestrator and the dashboard on loopback; don't press "Connect to Venom Cloud".

## What does not work offline {#limits}

Start venom with `venom --offline` (or `VENOM_OFFLINE=1`) so the web search and fetch tools are not offered to the model at all, rather than offered and failing. Also unavailable: remote MCP servers, cloud providers (their upstreams stay disabled without keys and are never probed), Venom Cloud and mesh mode, plugins from npm or git (copy a plugin directory in and `venom plugin add <path>`), and the daemon's auto-update (leave its switch off). venom checks for no updates and sends no telemetry at any time.

To prove it on your site: `venom egress` lists the hosts each session contacted, and a firewall rule that drops outbound traffic plus `venom doctor` shows nothing depends on the network.

## Docs on an offline network {#docs-site}

These public docs need the internet. For a network without it, a venom checkout builds a static API and SDK docs site from its own contracts:

```bash
make docs-site          # → dist/docs-site/index.html
make docs-site-check    # every operation and endpoint present, nothing loaded from elsewhere
```

It needs only `python3` 3.9 or newer, and the output has no scripts, web fonts or CDN links, so it opens from disk or any static file server. Carry `dist/docs-site/` with the bundle. Details are in [The offline API and SDK docs site](/docs/reference/docs-site.md).

## Updating {#update}

Build the next release's bundle, carry it, run its `install.sh`. `bin/venom` switches to the new version; the old one stays in `lib/venom/<v>/` until you delete it. The orchestrator's data (`share/venom/data`: the SQLite request log and keys) and `client-key` are kept.

## Related

- [Releases and signatures](/docs/deploy/releases.md): what `make release` builds and how to verify it.
- [The desktop daemon](/docs/deploy/desktop-daemon.md)
- [Local or cloud models](/docs/getting-started/local-or-cloud.md)
