Skip to content
Docs menu

Air-gapped install

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.

View .md

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

On a connected build machine with a venom checkout:

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:

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

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 saves 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

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.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 loads 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 has the manual check.

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

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

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

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:

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.

Updating

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.