Air-gapped install

Ongrid is designed to install fully offline. Every release tarball ships:

• The ongrid manager docker image,
• The ongrid-web (frontend + nginx) docker image,
• The singchia/frontier broker docker image,
• The four edge plugin binaries (promtail, otelcol-contrib, node_exporter, process_exporter) for linux/amd64 and linux/arm64,
• Per-arch ongrid-edge binaries,
• The optional offline embedding model (fast-bge-small-zh-v1.5) for the knowledge base if you ran make fetch-embedding-model before make package.

Nothing pulls from Docker Hub, GitHub, or any vendor API at install time. The only external dependencies at runtime are the LLM API endpoints you've configured — for a fully air-gapped setup point those at an on-prem vLLM / Ollama / OpenRouter relay.

This page covers the workflow for environments that can't reach the public internet.

Download the tarball on a connected host

On a workstation that has internet:

VER=v0.7.159

gh release download "$VER" \
    --repo ongridio/ongrid \
    -p 'ongrid-*-linux-amd64.tar.xz*'

You'll get two files:

ongrid-v0.7.159-linux-amd64.tar.xz          # ~380 MB (xz compressed)
ongrid-v0.7.159-linux-amd64.tar.xz.sha256   # the sidecar

GitHub uploads over Clash

Large release assets get reset half-way over Clash proxies. If you're downloading and the tarball ends short, try with NO_PROXY=objects.githubusercontent.com direct. Always verify the sha256 (see next step).

Verify the sha256

Before doing anything else:

sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256
# → ongrid-v0.7.159-linux-amd64.tar.xz: OK

If this fails, do not proceed. Re-download.

Transfer to the air-gapped host

Whatever path is approved at your site. USB key, internal artefact repo, SFTP through a jumpbox. The two files travel together; you can re-verify the sha256 after transfer.

# On the destination host:
sha256sum -c ongrid-v0.7.159-linux-amd64.tar.xz.sha256

Install

Same as the server install — no flags required for air-gapped, the installer never reaches out:

tar xf ongrid-v0.7.159-linux-amd64.tar.xz
cd     ongrid-v0.7.159-linux-amd64
sudo ./install.sh

install.sh does:

• docker load the three bundled images (images/ongrid.tar, images/frontier.tar, images/ongrid-web.tar).
• Stage configs, set up host data dirs, generate the self-signed TLS cert (uses local openssl; no external CA needed).
• Wire .env from the template, generate strong random secrets in-place, prompt for ONGRID_PUBLIC_URL.
• docker compose up -d, poll /healthz.

You should not see any "downloading..." log lines.

Hosting the install URL on-prem

When edges install themselves they curl https://<manager>/install.sh | bash. The install.sh they fetch is served by the manager itself — specifically by nginx out of /opt/ongrid/edge/install.sh. There's no GitHub or other external dependency in the edge-install path.

The same nginx serves:

Path on nginx	What
/install.sh	The edge install.sh script.
/edge/ongrid-edge-linux-amd64	The edge agent binary.
/edge/ongrid-edge-linux-arm64	Same, arm64.
/edge/promtail-linux-amd64	Plugin binary.
/edge/otelcol-contrib-linux-amd64	Plugin binary.
/edge/node_exporter-linux-amd64	Plugin binary.
/edge/process_exporter-linux-amd64	Plugin binary.
/edge/apply-pending-upgrade.sh	ADR-024 ExecStartPre hook.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz	Upgrade bundle.
/edge/edge-bundle-linux-amd64-<ver>.tar.gz.sha256	Sidecar.

All of those land in /opt/ongrid/edge/ when install.sh runs and are served read-only by the nginx container. Nothing else is required.

Edge install (air-gapped)

The standard one-liner works as long as the edge can reach the manager:

curl -k -sSL https://manager.internal/install.sh | sudo bash -s -- \
    --access-key=AK_xxxxxxxxxxxxxxxx \
    --secret-key=SK_yyyyyyyyyyyyyyyy \
    --server-edge-addr=manager.internal:40012 \
    --server-http-addr=manager.internal:443

If you have an edge host that can't reach the manager directly but can reach an internal artefact mirror, you can:

1. Mirror the manager's /install.sh, /edge/* paths onto your internal webserver.
2. Run the one-liner pointing at that mirror's URL.
3. The agent will still need --server-edge-addr and --server-http-addr pointing at the real manager — the mirror only hosts the install artefacts, not the tunnel.

This is useful for "the edge can talk to the manager only on TCP 40012 + a curated set of ports" setups where TCP 443 to the manager isn't available but a corporate webserver is.

Data plane still needs HTTPS to the manager

Logs and traces push directly from each edge to https://<manager>/loki/api/v1/push and https://<manager>/v1/traces. If your edge can't reach the manager on 443, those plugins will fail. The agent itself will look healthy (it only needs 40012), but the data plane will be silent — make sure 443 is open on the edge → manager path.

Air-gapped model providers

The default ONGRID_*_API_KEY= slots point at vendor URLs (OpenAI, Anthropic, Zhipu, …). To stay air-gapped, configure a Custom (OpenAI-compatible) provider in Settings → Models pointing at your on-prem relay:

• vLLM — OPENAI_API_BASE=http://vllm.internal:8000/v1 with a dummy OPENAI_API_KEY.
• Ollama — OPENAI_API_BASE=http://ollama.internal:11434/v1.
• LocalAI / LMStudio — same pattern.
• OpenRouter (on-prem) — paste your relay base URL.

The agent doesn't care; the OpenAI-compatible wire format is universal. Then set the new provider as Default provider so all back-end calls (alert investigation, translate, summarize) use it.

See the Custom (OpenAI-compatible) entry under Models in the sidebar.

Air-gapped knowledge base (vault sync without GitHub)

The built-in vault syncs from github.com/ongridio/vault on first boot. Air-gapped sites can't reach GitHub. Two options:

Option A — ship the vault inline

The release tarball includes a baseline snapshot of the vault as part of the image. On first boot the manager copies it into Qdrant directly — no network needed. You'll get the baseline (last fully-public sync at release-tag time) but won't see new playbooks until you upgrade the manager.

Option B — mirror the vault repo internally

1. On a connected host, clone the public vault:

   git clone --bare https://github.com/ongridio/vault.git

2. Push to your internal Git server:

   git push --mirror git@git.internal:ops/vault.git

3. In Settings → Knowledge → Vault, set the sync URL to git@git.internal:ops/vault.git and paste an SSH deploy key. The manager uses GIT_SSH_COMMAND to bind the key — see ADR-023.

The manager re-syncs the vault on demand from the UI ("Sync vault" button). Each pull is a git fetch against the configured remote; there's no GitHub-specific code in the path.

Upgrades, air-gapped

Just like the initial install, no internet needed at install time. The flow:

1. On the connected workstation: gh release download v0.7.160 ... and verify sha256.
2. Transfer the tarball.
3. On the air-gapped host:

   tar xf ongrid-v0.7.160-linux-amd64.tar.xz
   cd     ongrid-v0.7.160-linux-amd64
   sudo ./upgrade.sh

4. From the UI, Edges → Upgrade all — edges fetch the new bundle from https://<manager>/edge/edge-bundle-linux-amd64-v0.7.160.tar.gz and apply it via the standard ADR-024 stage-then-swap flow.

There is no step that needs internet beyond the workstation that downloads the tarball.

See upgrade for the gory details.

What's next

• Models / Custom (OpenAI-compatible) — wiring a vLLM / Ollama / on-prem relay as a default provider (see Models in the sidebar).
• Knowledge base capability — what the vault contains and how to add your own runbooks.
• On-prem platform — broader notes on on-prem / air-gapped deployments including SELinux, custom CAs, outbound proxy.