Air-gapped operation

Orbtrace is built to run with no internet at all. Nothing about the core product phones home — not licensing, not telemetry, not the UI. This page is the end-to-end runbook for a sealed environment.

What never needs the internet

• Licensing is an offline signed token verified against a key baked into the product. No license server, no activation call. See Licensing.
• Telemetry flows from your apps → your Collector → Doris, all inside your network.
• The UI and all queries are served from the single Orbtrace binary.

The one thing that can reach out — and how to stop it

The only outbound traffic Orbtrace ever makes is the AI provider call, and only if you enable RCA, Replay, or Astra with a SaaS LLM (Anthropic / OpenAI / Azure). For a true air-gap, use a local Ollama instead, so no prompt ever leaves:

ORBTRACE_AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://ollama:11434

Run Ollama on the same network (a container on the stack's network, or a host reachable from it) with a model pulled in advance (Llama 3.3, Mistral, or Qwen are the tested options). The AI features then work fully offline, with somewhat weaker grounding than the frontier SaaS models.

Already running an inside-network model server that speaks the OpenAI protocol (vLLM, Text Generation Inference, LocalAI, LM Studio)? Point Orbtrace at it instead with the openai-compatible provider — set the base URL (and an optional API key) in Admin → AI. If that endpoint is fronted by a self-signed or private-CA certificate, the same screen lets you upload the CA (PEM) or, as a last resort on a sealed network, skip TLS verification — so a private HTTPS endpoint still works without touching the system trust store.

Installing offline

You stage everything on a connected machine, carry it across, and install with no registry access.

1. 1

   Get the air-gap bundle from Nivorbit

   The air-gap bundle isn't a public download — a single tarball with every image baked in is too large for a registry or a release asset, so Nivorbit builds it on demand for you and hands it over out-of-band (transfer link or media). It contains the Compose files, the reference Collector config, and a docker save archive of every image under images/ (Orbtrace + Doris + Postgres + Valkey). Because the images travel inside the tarball, an air-gapped install needs no pull token — that's the connected-registry path only.

2. 2

   Carry it across

   Copy the tarball to the air-gapped host by whatever path your environment allows (removable media, one-way transfer, internal mirror).

3. 3

   Load the images

   tar xzf orbtrace-<version>-airgapped.tar.gz
   cd orbtrace-<version>-airgapped
   bash images/LOAD.sh

   LOAD.sh docker loads every saved image under images/. Now everything is local — no docker pull and no registry login needed.

4. 4

   Configure and start

   The deploy files are in the bundle's compose/ directory. Create your .env and set secrets, the bootstrap admin, and ORBTRACE_AI_PROVIDER=ollama:

   cd compose
   cp .env.example .env
   $EDITOR .env
   docker compose up -d

   Same as a connected install from here — open http://<host>:8080.

5. 5

   Bring your own Collector image too

   Orbtrace doesn't bundle a Collector, so in an air-gap you also need the otel/opentelemetry-collector-contrib image loaded locally (docker save/docker load it the same way). Then stand it up per Integration patterns.

On Kubernetes, mirror the GHCR images (and the OCI Helm chart) into your internal registry and point global.imageRegistry at it. On bare metal, the Ansible role already supports loading saved image tars.

Offline licensing flow

The fingerprint-and-token loop is designed for exactly this:

1. Read your install fingerprint locally (Admin → License, or GET /api/admin/license/fingerprint).
2. Send it to Nivorbit out-of-band (the same channel you use for any sealed-network correspondence).
3. Receive the .orblic token, carry it in, and drop it in (ORBTRACE_LICENSE_KEY, a mounted file, or Admin → License upload).

Renewal is the same loop. Nothing in it touches the internet from the air-gapped side.

What you give up

• Frontier-model AI quality — Ollama models are weaker at grounded citation than Claude/GPT; RCA and Replay still work, just with lower confidence on complex incidents.
• One-command image pulls — you stage images yourself (the tradeoff of any air-gap).

Everything else — full search, dashboards, alerting, SLOs, stitching, sampling — runs identically offline.