Air-gapped / on-prem

O Ongrid distribui como um tarball auto-contido precisamente para que funcione offline. Não há apt install, sem Go-module-fetch-at-build-time no host alvo, sem pull do Docker Hub em runtime. Coloque o tarball, rode install.sh, e você tem uma frota de manager + edges funcionando.

Os trade-offs que você vai bater indo air-gapped são em torno do provider LLM, do modelo de embedding para RAG, e upgrades contínuos. Esta página é a checklist.

Passo 1: Baixe o tarball de release

De um host com internet, pegue o último asset de release:

gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz'
gh release download v0.7.167 --repo ongridio/ongrid \
    --pattern 'ongrid-*-linux-amd64.tar.xz.sha256'
sha256sum -c ongrid-v0.7.167-linux-amd64.tar.xz.sha256

Ou builde o tarball você mesmo com make package. De qualquer jeito o artefato é um único .tar.xz mais seu .sha256.

Mova ambos os arquivos para o host alvo via o canal de air-gap que você usar (sneakernet USB, servidor de artefato interno, bucket S3 assinado, etc.).

Passo 2: Instalação por tarball

O tarball expande para um diretório auto-contido:

ongrid-v0.7.167-linux-amd64/
  install.sh
  upgrade.sh
  docker-compose.yml
  images/
    ongrid.tar              # imagem docker, salva
    ongrid-web.tar
    frontier.tar
    mysql.tar               # bundled para que não tenha pull do Docker Hub
    prometheus.tar
    loki.tar
    tempo.tar
    grafana.tar
    searxng.tar
  bin/
    linux-amd64/ongrid-edge
    linux-arm64/ongrid-edge
    darwin-amd64/ongrid-edge
    darwin-arm64/ongrid-edge
    linux-amd64/promtail
    linux-arm64/promtail
    linux-amd64/otelcol-contrib
    linux-arm64/otelcol-contrib
    linux-amd64/node_exporter
    linux-arm64/node_exporter
    linux-amd64/process_exporter
    linux-arm64/process_exporter
  edge/
    apply-pending-upgrade.sh
  .cache/
    bge-base-en-v1.5/       # modelo de embedding de RAG offline opcional

Rode:

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

install.sh carrega cada images/*.tar no docker local, escreve um .env sensato, sobe a stack com docker compose up -d, e imprime a URL do novo manager. O host precisa de Docker Engine + Compose v2 — veja Linux (servidor).

Veja Instalação air-gapped para o passo-a-passo completo com checksums e primeiro boot.

Passo 3: Espelhar para um registry privado (opcional)

Se você tem um registry de container privado (Harbor / Artifactory / ECR / GCR), e prefere docker pull a docker load, faça push das imagens bundled uma vez:

for img in images/*.tar; do
  name=$(docker load -i "$img" | awk -F': ' '/Loaded image/ {print $2}')
  registry_tag="registry.internal/${name}"
  docker tag "$name" "$registry_tag"
  docker push "$registry_tag"
done

Então escreva um docker-compose.override.yml que aponta cada serviço para registry.internal/... em vez da imagem original, e você pode fazer deploy em N hosts sem re-enviar o tarball. Upgrades futuros viram "pull da nova tag de imagem, docker compose up -d".

Passo 4: Instalação de edge numa rede air-gapped

O instalador curl-pipe (https://<manager>/install.sh | bash) funciona bem dentro de uma rede air-gapped desde que os edges consigam alcançar o manager (porta 443 para o bundle estático + porta 40012 para o tunnel). O instalador baixa o binário do agent e os quatro binários de plugin de https://<manager>/edge/, que o nginx do manager serve do diretório bind-mounted ./bin/.

Se seus edges não conseguem alcançar o manager por HTTPS — por exemplo, edges estão em um segmento de rede que só permite porta 40012 — copie os binários à mão:

# em cada host de edge
sudo install -m 0755 ongrid-edge /usr/local/bin/ongrid-edge
sudo mkdir -p /usr/local/lib/ongrid-edge
sudo install -m 0755 promtail otelcol-contrib node_exporter process_exporter \
    /usr/local/lib/ongrid-edge/
# então escreva /etc/ongrid-edge/ongrid-edge.env e a unit systemd
# (veja deploy/install/edge/install.sh para o conteúdo exato da unit)

Ou, mais robustamente: suba um mirror HTTPS interno pequeno que mantenha uma cópia de ./bin/linux-*/ e aponte um install.sh forkado para ele.

Passo 5: Provider LLM

O Ongrid não embarca um LLM. O agent kernel chama um provider upstream — Anthropic, OpenAI, Zhipu, DeepSeek, Gemini, Kimi, ou qualquer relay compatível com OpenAI — pela conexão de internet outbound do manager. Em uma rede air-gapped você tem três opções:

1. Proxy outbound. Defina HTTPS_PROXY=http://your-proxy:3128 no bloco env do manager. Todas as chamadas ao provider fluem pelo proxy.
2. Relay compatível com OpenAI self-hosted. Rode vLLM / TGI / Ollama / one-api dentro da sua rede, aponte ONGRID_OPENAI_BASE_URL para ele, defina ONGRID_OPENAI_API_KEY para o que o relay esperar. É o padrão mais comum para instalações totalmente desconectadas.
3. Provider Custom na UI. Settings → Models → Custom (OpenAI-compatible) te dá a mesma fiação sem restart.

Se você quer usar Zhipu (GLM) contra um endpoint hospedado pela Tencent Cloud dentro da China, defina ONGRID_ZHIPU_BASE_URL para o endpoint regional e ONGRID_ZHIPU_API_KEY para sua chave — sem proxy necessário, GLM é alcançável dentro da rede da China continental.

Passo 6: RAG offline (o modelo de embedding)

Ingestão de base de conhecimento precisa de um modelo de embedding. Por padrão o manager chama a API de embedding GLM (embedding-3) que precisa de internet. Para um deployment totalmente offline, troque para o perfil embedding local:

ONGRID_EMBEDDING_PROVIDER=local
ONGRID_EMBEDDING_LOCAL_MODEL_PATH=/var/lib/ongrid/embeddings/bge-base-en-v1.5

O tarball de release distribui o modelo BAAI/bge-base-en-v1.5 sob .cache/bge-base-en-v1.5/ (~400 MB). O script de instalação o copia para o volume nomeado no primeiro boot. Se você pulou make fetch-embedding-model ao buildar o tarball, o modelo está ausente e o embedding vai falhar — rode esse passo uma vez e re-package.

O vault built-in padrão do Ongrid (github.com/ongridio/vault) é público e contém runbooks baseline distribuídos no seed RAG embarcado. Sincronizá-lo requer alcançar o GitHub. Em uma rede air-gapped você pode:

• Vendorizar o vault no seu próprio servidor Git interno e atualizar ONGRID_VAULT_REPO_URL.
• Ou, pular o sync do vault inteiramente — o seed embarcado (cerca de 96 playbooks) vive dentro do binário e está sempre disponível.

Passo 7: Upgrades

Dois caminhos:

1. Mesmo mecanismo de tarball. Baixe o novo tarball em um host conectado à internet, sneakernet para cá, rode ./upgrade.sh. Isso é install.sh menos o bootstrap — load de imagem + docker compose up -d. Os edge agents pegam os binários correspondentes de agent + plugin na próxima vez que reconectam (staging de whole-bundle do ADR-024).
2. Pull de registry privado. Se você espelhou as imagens (Passo 3), docker compose pull && docker compose up -d é suficiente. Edges ainda precisam dos novos binários de agent + plugin, que eles fetcham do path estático /edge/ do manager — isso atualiza automaticamente quando você troca o diretório bin/ distribuído no tarball.

O que NÃO funciona air-gapped

• Auto-sync do vault built-in sem um mirror — o repo do vault vive no GitHub.
• LLMs hospedados do provider sem um proxy outbound ou relay — não há LLM local distribuído.
• O perfil de embedding GLM padrão — troque para local (veja Passo 6).
• Instalações de skill do marketplace público (ADR-017) — aponte para um registry privado em vez disso.

Tudo mais, incluindo o kernel completo do agent, evaluator de alerta, pipeline de telemetria, e UI de chat, roda totalmente offline.