Guides / Keep API keys out of the sandbox

Keep API keys out of the sandbox

An AI agent needs an API key to do anything. It does not need to hold one. With a brokered kit the key stays on your computer; the sandbox is given a placeholder that only works from inside that sandbox, and the real key is added to each request after it has left.

What changes

A kit is the recipe kosa8 agent run builds an agent's sandbox from: an image, a command, the hosts it may reach, and its credentials. Kits used to copy your key into the sandbox. Brokered kits do not.

The egress broker is the part that makes this work. It is a small HTTP proxy that runs inside the kosa8d service on your computer, one per sandbox. "Egress" means traffic leaving the sandbox. The broker is the only way out a brokered sandbox has.

One request, start to finish

What a stolen placeholder is worth

Assume the worst: something in the sandbox reads the placeholder and sends it to an attacker. This is what they can do with it.

The one place it does work is where it was issued: inside that sandbox, through that broker, while it runs. That is still a real power, and it is the first item under limits.

Try it

$ kosa8 agent run --dry-run claude
kosa8: kit claude (node:22-alpine)
kosa8: workspace /Users/you/code/api -> /work (nothing else on the host is visible)
kosa8: network closed except through the egress broker: registry.npmjs.org, statsig.anthropic.com
kosa8: brokering ANTHROPIC_API_KEY -> api.anthropic.com (the sandbox holds a placeholder, never the key)
kosa8: --dry-run, stopping before creating the sandbox

$ kosa8 agent run -w ~/code/api claude
kosa8: kit claude (node:22-alpine)
kosa8: workspace /Users/you/code/api -> /work (nothing else on the host is visible)
kosa8: network closed except through the egress broker: registry.npmjs.org, statsig.anthropic.com
kosa8: brokering ANTHROPIC_API_KEY -> api.anthropic.com (the sandbox holds a placeholder, never the key)
kosa8: sandbox claude-44059 ready in 653ms
kosa8: pulling node:22-alpine
kosa8: running kit setup, then: claude
...
kosa8: sandbox claude-44059 removed

kosa8: warning: ANTHROPIC_API_KEY is not set on the host; the agent may fail to authenticate

The sandbox is removed when the agent exits, and the broker with it. --keep keeps the sandbox; see where the key lives for why a kept sandbox does not keep its broker across a restart. All the flags are on the agent run reference page.

Which kits are brokered

kosa8 agent kits lists the kits you can run. The KEYS column says where each one's credentials will be.

$ kosa8 agent kits
KIT       IMAGE           NETWORK                             KEYS                  DESCRIPTION
azmx      node:22-alpine  api.azmx.ai,registry.npmjs.org      brokered + passed in  UNAVAILABLE — AZMX AI agent CLI in an isolated sandbox
claude    node:22-alpine  registry.npmjs.org,statsig.anthr..  brokered              Claude Code in an isolated sandbox
codex     node:22-alpine  registry.npmjs.org                  brokered              OpenAI Codex CLI in an isolated sandbox
copilot   node:22-alpine  api.githubcopilot.com,api.github..  passed in             GitHub Copilot CLI in an isolated sandbox
cursor    node:22-alpine  api2.cursor.sh,api.cursor.sh        passed in             UNAVAILABLE — Cursor CLI (cursor-agent) in an isolated sandbox
gemini    node:22-alpine  registry.npmjs.org                  brokered              Gemini CLI in an isolated sandbox
opencode  node:22-alpine  registry.npmjs.org                  brokered              OpenCode in an isolated sandbox
shell     alpine:latest   none                                none                  A plain shell with the workspace mounted and no network

brokered: the key stays on this machine and the sandbox holds a placeholder
passed in: the real key is in the sandbox's environment
kits in ~/.kosa8/kits override built-ins of the same name

The API's host does not appear in the NETWORK column of a brokered kit. That is deliberate: claude lists the package registry and a telemetry host, and reaches api.anthropic.com only through its credential's route. The agent cannot open its own connection to the API, with or without a key.

What each brokered kit does

The three exceptions

copilot still passes its token in. Brokering works by pointing the agent's tool at the broker instead of at the API, so it needs a tool that accepts a different base URL. The Copilot CLI has no such setting. Its kit therefore still copies GITHUB_TOKEN into the sandbox, and every run says so:

kosa8: passing GITHUB_TOKEN into the sandbox as plain environment variables — the agent can read them

Give that kit a token with the narrowest scope that works, and treat it as exposed to whatever the agent runs.

cursor and azmx are unavailable. A kit installs the agent's tool before it hands over a key, so kosa8 will not ship a kit whose installer it cannot verify. The cursor kit used to install an npm package named cursor-agent, which is not published by Cursor. The azmx kit names a package that is not registered at all, so anyone could publish under that name and be handed the keys. Both refuse to run and say why:

$ kosa8 agent run cursor
kosa8: kit cursor cannot be run as shipped: the npm package "cursor-agent" is not published by Cursor, so this kit no longer installs it; write a kit that installs Cursor's CLI from a source you have verified (`kosa8 agent init cursor`)

See Kits for pinned packages and signing.

Broker your own tool's key

Any HTTP API whose client lets you set its base URL can be brokered. You describe the credential in a kit file under credentials:. This is a complete kit: a shell that can call a weather API without holding its key.

# weather.yaml
name: weather
description: A shell that can call a weather API without holding its key
image: alpine:latest
command: [sh]
egress_allow:
  - docs.example.com
credentials:
  - name: weather
    upstream: https://api.example.com
    secret: WEATHER_API_KEY
    header: Authorization
    scheme: "Bearer "
    methods: [GET]
    paths: [/v1/forecast]
    env:
      WEATHER_API_URL: "{{url}}"
      WEATHER_API_KEY: "{{placeholder}}"

$ kosa8 agent run --dry-run ./weather.yaml
kosa8: warning: kit file ./weather.yaml is unsigned: nothing vouches for its contents (sign it with `kosa8 agent sign`, and pin the key with `kosa8 policy trust`)
kosa8: kit weather (alpine:latest)
kosa8: workspace /Users/you/code/api -> /work (nothing else on the host is visible)
kosa8: network closed except through the egress broker: docs.example.com
kosa8: brokering WEATHER_API_KEY -> api.example.com (the sandbox holds a placeholder, never the key)
kosa8: --dry-run, stopping before creating the sandbox

Inside that sandbox, a client that reads WEATHER_API_URL and WEATHER_API_KEY can GET anything under /v1/forecast at api.example.com, and can open docs.example.com. It can do nothing else on the network.

Every field

Three details decide whether a route means what you intended.

• Paths match on segment boundaries. /v1/messages covers /v1/messages and /v1/messages/batches. It does not cover /v1/messages_admin, which a plain text prefix would have let through.
• Methods are upper-case. Write GET, POST. An entry in another case is folded to upper-case when the route is loaded, and a request's method is compared exactly.
• {{url}} can carry a suffix. The built-in codex kit sets OPENAI_BASE_URL to "{{url}}/v1" because that tool expects the version in its base URL. Quote any value that contains braces, or YAML reads it as a mapping.

When the kit file is wrong

A kit is checked when it is loaded, and the message names the credential and the fix. These are the messages for three common mistakes:

kosa8: ./weather.yaml: credential "weather": env must give the sandbox {{placeholder}} in some variable
kosa8: ./weather.yaml: credential "weather": upstream "https://api.example.com/v1" must be https://host with no path
kosa8: ./weather.yaml: credential name "Weather_API" must be 1-32 characters of a-z, 0-9 and '-'

Path prefixes and header names are checked a step later, by the broker, when the sandbox is created.

What the sandbox sees

This is the environment of a real brokered sandbox, from a test kit with one credential named echo for httpbin.org:

ECHO_KEY=kosa8-placeholder-1803c857986afe6bc9f59600e4d6f6f8
ECHO_URL=http://192.168.127.254:57504/echo
HTTPS_PROXY=http://192.168.127.254:57504

The plain address is http://, not https://. That hop never leaves your computer: it runs from the virtual machine to a port on the loopback interface of the same machine. The broker makes the connection to the upstream over TLS, checked against the upstream's own name.

A request to $ECHO_URL/headers with the placeholder asked the upstream to report what it received:

"Authorization": "Bearer real-secret-xyz-0123456789"

The upstream saw the real key. The sandbox that sent the request never had it.

What the broker refuses

A refusal is an ordinary HTTP response, so the agent's tool fails immediately with a status it understands. The body is one line that starts kosa8: and says what to change, for example kosa8: this route needs the sandbox's placeholder credential. The same decision goes to the audit log with a short, stable reason.

For a route the checks run in this order: the path's spelling, the method, the path's prefix, then the placeholder. Paths with two possible readings are refused instead of tidied up, because the broker cannot know which reading the upstream would take. TRACE is refused because its purpose is to echo the request back, key included.

Each of the first five rows was produced by a real request. These are the entries they left:

sandbox.egress.allow {"kind":"route","host":"httpbin.org","port":443,"method":"GET","path":"/headers","route":"echo","status":200,"bytes_in":225}
sandbox.egress.deny  {"kind":"route","host":"httpbin.org","port":443,"method":"GET","path":"/headers","route":"echo","reason":"placeholder credential missing or wrong"}
sandbox.egress.deny  {"kind":"route","host":"httpbin.org","port":443,"method":"GET","path":"/anything","route":"echo","reason":"path not allowed on route"}
sandbox.egress.deny  {"kind":"route","host":"httpbin.org","port":443,"method":"POST","path":"/get","route":"echo","reason":"method not allowed on route"}
sandbox.egress.deny  {"kind":"route",...,"reason":"placeholder also sent in the URL"}
sandbox.egress.deny  {"kind":"route",...,"path":"/get/../anything","reason":"path has a . or .. segment"}

An entry carries the path and never the query string, which is where keys and personal data tend to travel. Entries are limited to 120 a minute for each sandbox and each kind of request (refused, credentialed, other allowed), so ordinary traffic cannot crowd out a credentialed call or a refusal; past that, requests are counted and the count rides on the next entry. See The audit log.

Where the real key lives, and for how long

When the sandbox stops, its broker stops and the key is dropped from memory. Nothing wrote it down, so nothing can bring it back.

Limits

Where to go next