kosa8

kosa8 / Guides

Guide · Air-gapped and offline

How do I run an AI coding agent fully air-gapped?

Updated

Collect everything on a connected machine, carry it across on approved media, and serve the model locally so the agent talks to an OpenAI- or Anthropic-compatible server on the same machine instead of a cloud API. With kosa8 that means an offline site licence, KOSA8_OFFLINE=1 so nothing is fetched, container images moved with kosa8 save and kosa8 load, and models moved through your internal OCI registry and served on 127.0.0.1:7434. Local models cost nothing per token, but they are not a drop-in replacement for the largest hosted models on hard tasks.

01Steps

  1. Collect the software on the connected side. Download the kosa8 package for the target (the Mac app, or the .deb, .rpm or .apk from the releases page) and the air-gap bundle with the guest image for that release. Save the container images your agents need as OCI archives.

    terminal
    kosa8 pull alpine:latest
kosa8 save alpine:latest -o alpine.tar

  2. Pull the model and publish it to your registry. Models come from Hugging Face as GGUF files. kosa8 model push stores one as a standard OCI artifact, so it can cross the gap the same way your container images do.

    terminal
    kosa8 model pull Qwen/Qwen2.5-0.5B-Instruct-GGUF:q4_k_m
kosa8 model push qwen2.5-0.5b-instruct-q4_k_m registry.company.com/models/qwen:v1

  3. Install offline on the air-gapped machine. Copy the guest image into ~/.kosa8/guest. With KOSA8_OFFLINE=1 kosa8 fetches nothing. A site licence is checked against a key built into kosa8 and needs no activation or check-in.

    terminal
    export KOSA8_OFFLINE=1
kosa8 license install site-licence-file
kosa8 daemon start
kosa8 doctor
kosa8 load -i alpine.tar

  4. Install and serve the model. The download is checked against its digest; a damaged or altered file is refused. The gateway answers both OpenAI and Anthropic requests.

    terminal
    kosa8 model pull-oci registry.internal/models/qwen:v1 --name qwen
kosa8 model serve qwen
kosa8 model gateway on http://127.0.0.1:7434
  OpenAI:    POST /v1/chat/completions
  Anthropic: POST /v1/messages

  5. Point the agent at the local model. Any agent that accepts a base URL works. The gateway serves one model and answers whatever model name is sent. Aider, for example, reads OPENAI_API_BASE.

    terminal
    export OPENAI_BASE_URL=http://127.0.0.1:7434/v1
export ANTHROPIC_BASE_URL=http://127.0.0.1:7434
OPENAI_API_BASE=http://127.0.0.1:7434/v1 OPENAI_API_KEY=local aider --model openai/qwen

  6. Run the code it writes in a sandbox with no network. The built-in shell kit is a plain shell with the project mounted and no network. Use it for builds and tests the agent proposes.

    terminal
    kosa8 agent run -w ~/code/api shell

02Can an AI coding agent work with no internet at all?

Yes, if the agent accepts a custom base URL for its model API and a model runs on the same machine or network. Agents that can only call their vendor's address cannot run air-gapped.

kosa8's docs give one example: the GitHub Copilot CLI cannot be pointed at a different address. kosa8's model gateway answers callers on the machine it runs on only, serves one model at a time, and has no login of its own, so any program running as you can use it. kosa8 does not document connecting an agent inside a kosa8 sandbox to that gateway, so in this setup the agent runs on the host and the code it proposes runs in the sandbox.

03How do I move models into an air-gapped network?

Publish the model to an OCI registry as an artifact with kosa8 model push, move it into the registry on the air-gapped side with the process you already use for container images, and install it there with kosa8 model pull-oci, which checks the digest before installing.

Pull by digest (repo@sha256:…) rather than tag so the model cannot change under you. An organisation can list approved models by the fingerprint of their weights in its signed policy, and kosa8 then refuses to serve anything else; kosa8 model check NAME shows where a model stands.

04What about licensing, FIPS and audits offline?

An offline site licence is a signed file carrying a plan and an expiry, verified against the issuer key compiled into kosa8, and it makes no licensing requests. kosa8.com lists FIPS 140-3 builds for Enterprise and Government contracts.

The hash-chained audit log works offline, and kosa8 audit verify checks it locally. Ask about FIPS builds and air-gap bundles through Enterprise & Government.

05Other options

  • Ollama. Serves local models with an OpenAI-compatible API at http://localhost:11434/v1.
  • llama.cpp's llama-server or vLLM. OpenAI-compatible servers for GGUF files and for GPU serving respectively.
  • Docker with --network none. A container with no network for running agent-proposed code.
  • A full VM in UTM or Lima. A separate offline workstation with the agent and model inside.
  • gVisor, Kata Containers or Firecracker. For teams building their own isolated runners on Linux.

06Sources