OpenCode Offline Mode: Air-Gapped Setup for Local Models

No, not upstream. The names OPENCODE_OFFLINE=true, OPENCODE_OFFLINE_MODE and offline: true come from community forks or from PR #18235, "feat: add offline mode to disable non-essential outbound connections". That PR is open, not merged and not a draft, and its last update was 2026-08-22. The issue behind it, #18233, was closed as not planned on 2026-07-15.

Even as proposed, PR #18235 is narrower than its title. It covers the update check, session sharing and the web UI proxy to app.opencode.ai, and it explicitly leaves the model catalog fetch and Exa web search untouched. Merging it tomorrow would not give you an air-gapped agent.

The maintainers have been clear about why. In issue #10416, "OpenCode is not private by default?", a maintainer wrote on 2026-01-27 that they would "likely add a single offline: true flag that disables everything that needs network", and that it "cannot be the default because it's not the experience the majority of people want". Eight months later, no such flag is merged, and #10416 itself was closed as not planned on 2026-06-23 by an automated sweep of question issues. The older air-gapped installation request, #2224, was closed as not planned on 2026-05-16.

So the working answer for a platform team is the same one that applies to running Claude Code against a local model: enumerate the outbound calls at a pinned version, close each one with the setting that actually governs it, and verify at the network layer.

Nothing. OpenTelemetry log and trace export at v1.18.34 is created only when OTEL_EXPORTER_OTLP_ENDPOINT is set; without it, the logger list is empty and the tracing layer is a no-op. AI SDK spans need experimental.openTelemetry: true in config on top of that. When you do enable it, the only destination is the collector you named. A maintainer put it plainly in #10416: "there is no telemetry".

What earned OpenCode its privacy reputation was a fallback that no longer exists. Until early 2026, a session with no cheap model configured generated its titles with gpt-5-nano on OpenCode's hosted Zen provider. A maintainer described that behaviour on 2026-01-24 and confirmed on 2026-03-19 that "we did remove falling back to the free gpt nano by default". At v1.18.34, the small model resolves from small_model if you set it, then a plugin hook, then a model from the same provider as the session, and otherwise nothing. A local-only provider gets no cross-provider fallback.

The Zen provider itself is still there. With no API key, no auth entry and no config, the provider with id opencode autoloads, keeps only its free models and authenticates with the key public. If a developer picks one of those models from the list, their prompts go to OpenCode's hosted service. For a regulated deployment that default sends source code and prompts outside the perimeter, and it is one config line to remove.

The privacy policy question has a short answer too: a maintainer stated in #10416 that the policy applies only to the Zen hosted offering, not to the open-source CLI.

These 17 rows cover the CLI and TUI at v1.18.34. The desktop app is out of scope: its build is wired for Sentry error reporting when a DSN is configured at build time, and whether the shipped build carries one is not visible from the repository.

Three rows deserve a second look before they go into a change ticket.

The environment block below closes rows 1, 2, 3, 8 and 10, and documents rows 5, 13 and 14 as variables to keep unset. Use 1 for every flag: flag.ts accepts 1 or true in any case, but OPENCODE_DISABLE_SHARE and the flags parsed through Effect (OPENCODE_PURE, OPENCODE_DISABLE_LSP_DOWNLOAD) accept only lowercase values. Put it in the profile your developers' shells load, or in the systemd unit or container spec that launches opencode serve.

# Model catalog: no network fetch; use the cache or the bundled snapshot
export OPENCODE_DISABLE_MODELS_FETCH=1
# Optional: read a reviewed catalog file instead (still needs the flag above)
# export OPENCODE_MODELS_PATH=/opt/opencode/models.json

# No update check (autoupdate "notify" still checks; this does not)
export OPENCODE_DISABLE_AUTOUPDATE=1

# Session sharing hard-off (belt and braces with "share": "disabled")
export OPENCODE_DISABLE_SHARE=1

# Only matters if you enable LSP in config: no downloads
export OPENCODE_DISABLE_LSP_DOWNLOAD=1

# Skip npm plugins listed in config
export OPENCODE_PURE=1

# The TUI talks to a local HTTP server; never send it through a proxy
export NO_PROXY=localhost,127.0.0.1

# Do NOT set: OPENCODE_EXPERIMENTAL (implies Exa web search),
# OPENCODE_ENABLE_EXA, OPENCODE_ENABLE_PARALLEL, OPENCODE_AUTO_SHARE,
# OPENCODE_DISABLE_EMBEDDED_WEB_UI (falls back to proxying app.opencode.ai),
# OTEL_EXPORTER_OTLP_ENDPOINT (unless it points at your own collector)

OPENCODE_DISABLE_DEFAULT_PLUGINS=1 is a reasonable addition if nobody uses the hosted providers it covers (Codex, Copilot, GitLab, Azure, xAI and others). Those plugins are compiled into the binary, so the flag gates no download; it only skips loading them. The source review behind this post did not audit each plugin's initialisation path for network calls, so treat it as defence in depth, not as the fix for a known call.

Three of these variables (OPENCODE_MODELS_PATH, OPENCODE_DISABLE_SHARE, OPENCODE_PURE) do not appear in the docs' environment variable table at v1.18.34; they exist in source, with PURE documented as the --pure flag. That is a reason to re-read the source on upgrade rather than the docs page.

The config file handles rows 2 through 6 and pins the models. Put it in the global config, ~/.config/opencode/opencode.json for each developer: the update check reads autoupdate from the global config only, so the same file in a repository does not close row 2. This one targets a vLLM server; the provider id, host and model id are placeholders.

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["vllm"],
  "disabled_providers": ["opencode"],
  "model": "vllm/qwen3-coder",
  "small_model": "vllm/qwen3-coder",
  "share": "disabled",
  "autoupdate": false,
  "permission": {
    "webfetch": "deny",
    "websearch": "deny"
  },
  "provider": {
    "vllm": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "vLLM (internal)",
      "options": {
        "baseURL": "http://inference.internal:8000/v1"
      },
      "models": {
        "qwen3-coder": { "name": "Qwen3-Coder (internal)" }
      }
    }
  }
}

The $schema URL is read by editors for completion; OpenCode does not fetch it. enabled_providers is the stronger control: per the schema, "When set, ONLY these providers will be enabled. All other providers will be ignored". That alone excludes Zen. disabled_providers: ["opencode"] is redundant beside it, and worth keeping because a reviewer reading the file sees the intent without knowing the semantics.

Pin small_model even though v1.18.34 has no cross-provider fallback. Title generation and other small tasks then run on a model you named, and a future release that changes the resolution order cannot route them elsewhere.

Use "autoupdate": false, not "notify". The update routine returns early only on false or the environment variable; notify still queries the latest version and just skips installing it.

The same provider block works for all three servers because each exposes an OpenAI-compatible API. Only baseURL changes:

@ai-sdk/openai-compatible is in the set of provider packages bundled into the v1.18.34 binary, so pointing at a local endpoint triggers no npm download. Row 9 bites when someone copies a config that names a different provider package: anything outside the bundled set is fetched from the npm registry when the provider loads.

If the inference endpoint terminates TLS with an internal CA, OpenCode trusts it through NODE_EXTRA_CA_CERTS. If a corporate proxy is configured through HTTPS_PROXY or HTTP_PROXY, NO_PROXY=localhost,127.0.0.1 is required, because the TUI is a client of OpenCode's own local HTTP server.

Two adjacent problems belong to other posts. Getting reliable tool calls out of Ollama starts with the context window, covered in Ollama's num_ctx silent prompt truncation. And the server half of the air gap, stopping the inference engine itself from calling Hugging Face, is in the vLLM air-gapped deployment guide. If the Ollama box is reachable from more than one workstation, lock down the Ollama endpoint before you point a fleet of agents at it.

Three artifacts have to arrive on the host before the first run: the binary, ripgrep, and the config-directory dependency.

# On the air-gapped host, with the v1.18.34 archive and install script copied in
tar -xzf opencode-linux-x64.tar.gz
# Point --binary at the opencode executable extracted from the archive
./install --binary ./opencode --no-modify-path
# The binary lands in ~/.opencode/bin; add that to PATH in your managed shell profile

# ripgrep from the OS mirror, so OpenCode never downloads it from GitHub
sudo apt-get install -y ripgrep   # or: sudo dnf install -y ripgrep

# Option A: internal npm mirror (OpenCode reads npm config)
printf 'registry=https://npm.internal.example/\n' >> ~/.npmrc

# Option B: populate once on a staging box with the SAME OpenCode version,
# then copy ~/.config/opencode/{package.json,package-lock.json,node_modules}
# to the target. The install is skipped when node_modules exists and every
# declared dependency is in package-lock.json, or when the dir is not writable.

Reading source tells you which paths exist. Only a capture on your own host tells you which ones your configuration still triggers. This procedure runs OpenCode as a dedicated test user under a deny-by-default egress rule that allows loopback and the model server, logs every dropped packet, records DNS traffic, and traces every connect() the process tree makes. IP, port and user name are placeholders; give the test user the same global opencode.json your developers get.

# 1) Deny-by-default egress for one test user, allow loopback + model server, log drops
sudo nft -f - <<'EOF'
table inet oc_egress {
  chain out {
    type filter hook output priority 0; policy accept;
    meta skuid != octest accept
    oifname "lo" accept
    ip daddr 10.0.0.20 tcp dport 8000 accept      # your vLLM / Ollama host:port
    log prefix "OC-EGRESS " counter drop
  }
}
EOF

# 2) Watch DNS lookups (on hosts with a local resolver, the resolver forwards them)
sudo tcpdump -ni any port 53 -l | tee /tmp/oc-dns.log &

# 3) Trace every connect() OpenCode and its children make
sudo -u octest env OPENCODE_DISABLE_MODELS_FETCH=1 OPENCODE_DISABLE_AUTOUPDATE=1 \
  OPENCODE_DISABLE_SHARE=1 OPENCODE_PURE=1 \
  strace -f -e trace=connect -o /tmp/oc-connect.log \
  opencode run --print-logs --log-level DEBUG "list the files in this repo"

# 4) Review: kernel log for drops, then non-loopback connect() calls
sudo journalctl -k | grep OC-EGRESS
grep connect /tmp/oc-connect.log | grep -v '127.0.0.1\|::1\|AF_UNIX'

Run it twice: once with the environment variables removed from step 3, to see the baseline your host produces, and once as written. Then repeat in the interactive TUI and have the agent read a Python file, which exercises the update check and the tree-sitter download path, neither of which opencode run triggers.

Map each finding back to the table:

Rows 6 and 17 explain why the nftables rule is the control, not the configuration. Denying webfetch stops OpenCode's own fetch tool. It does nothing about the shell tool, which is registered unconditionally and runs whatever command the model produces. A model asked to "check the latest version of this library" can emit curl, pip download or git clone, and no OpenCode setting scopes that. The containment options for that tool, from OS sandboxes to user separation, are in sandboxing coding agents locally without a VM. Remote MCP servers and any npm plugin a developer adds later sit in the same category: each is an outbound path the moment someone configures it.

For a bank, insurer, hospital or defence supplier, that changes how the sign-off is written. The control an auditor can test is the host or network egress policy that allows only loopback and the inference server. The OpenCode settings above are defence in depth that keeps that policy's logs quiet, so a real drop stands out instead of drowning in hourly catalog retries. Write the ticket that way round.

It also changes change control. Row 1 moved hosts in a patch release, v1.18.10. Three of the variables in the environment block are missing from the docs' variable table. Treat every OpenCode upgrade as a re-read of packages/core/src/flag/flag.ts, packages/opencode/src/effect/runtime-flags.ts and the catalog module, plus a re-run of the verification procedure, before the new binary reaches developers. If PR #18235 ever merges, it closes three rows of this table, not all 17.

If you are still deciding between agents rather than hardening one, the token overhead comparison of Claude Code and OpenCode covers the cost side, and the rest of the AI development tools guide covers the surrounding toolchain.

This week, take one developer host, apply the environment block and the opencode.json above, install rg from your mirror, and run the four-step verification as a dedicated user. Whatever shows up in OC-EGRESS is your remaining list.