Guides / Writing a kit

Writing a kit

A Sandbox Kit is a short file that describes the environment an AI agent runs in. It names the image, what gets installed, the one folder the agent can see, the hosts it can reach and the credentials it can use. kosa8 turns each line into something the sandbox enforces, so the limits hold whatever the agent decides to do.

What a kit decides

An agent told "only touch this project" can ignore the instruction. An agent whose virtual machine was only given that project's folder cannot. A kit is the list of things the machine is given.

What kosa8 agent run does

This is what it prints, on the error stream, for the built-in claude kit:

$ 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

Start from a built-in

kosa8 ships kits for common agents. List them:

$ 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

$ kosa8 agent init claude
wrote /Users/you/.kosa8/kits/claude.yaml

$ kosa8 agent run --dry-run -w ~/code/api ./team-claude.yaml
kosa8: warning: kit file ./team-claude.yaml is unsigned: nothing vouches for its contents (sign it with `kosa8 agent sign`, and pin the key with `kosa8 policy trust`)
kosa8: kit team-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: passing CI into the sandbox as plain environment variables — the agent can read them
kosa8: --dry-run, stopping before creating the sandbox

$ kosa8 agent run team-claude            # ~/.kosa8/kits/team-claude.yaml
$ kosa8 agent run ./kits/team-claude.yaml  # any path

The kit file, field by field

Only image is required. A kit file that leaves out name takes the file's name without its extension.

A package

A credential

A kit with credentials reaches every host through the broker, by name. Its egress_allow may therefore list host names or single addresses, but not a network such as 10.0.0.0/8; that is refused when the kit is loaded. How the broker uses these fields, and what a refused request looks like, is in Keep API keys out of the sandbox.

Two complete kits

A shell tool with no network

name: lint
description: A shell with the project mounted and no network
image: alpine:latest
command: [sh]
egress: deny
cpus: 2
mem_mb: 1024

$ kosa8 agent run --dry-run -w ~/code/api ./lint.yaml
kosa8: warning: kit file ./lint.yaml is unsigned: nothing vouches for its contents (sign it with `kosa8 agent sign`, and pin the key with `kosa8 policy trust`)
kosa8: kit lint (alpine:latest)
kosa8: workspace /Users/you/code/api -> /work (nothing else on the host is visible)
kosa8: network denied
kosa8: --dry-run, stopping before creating the sandbox

An agent with a pinned package, a brokered key and an allow-list

name: team-claude
description: Claude Code for the API team
image: node:22-alpine
packages:
  - name: "@anthropic-ai/claude-code"
    version: 2.1.296
    integrity: sha512-OX/k/rpcthMqnFKOWcpNcbiLsMKtAjLOpQNJHlYiDCFUznWCIwdRTyl/p9SdHVrsrzZuPMCNqZjnpakIni6upw==
command: [claude]
mount_at: /work
egress_allow:
  - registry.npmjs.org
  - statsig.anthropic.com
credentials:
  - name: anthropic
    upstream: https://api.anthropic.com
    secret: ANTHROPIC_API_KEY          # read on your computer; never enters the sandbox
    header: x-api-key
    methods: [POST]                    # optional
    paths: [/v1/messages]              # optional
    env:                               # what the sandbox gets instead
      ANTHROPIC_BASE_URL: "{{url}}"
      ANTHROPIC_API_KEY: "{{placeholder}}"
env:
  CI: "1"
cpus: 4
mem_mb: 4096

The package, version and digest here are the ones the built-in claude kit pins. If ANTHROPIC_API_KEY is not set where you run the command, kosa8 warns and leaves that route out, so the agent fails to sign in rather than reaching the upstream with nothing:

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

Flags for kosa8 agent run

The full flag list is on the agent run reference page.

Pinning what a kit installs

npm install -g some-cli installs whatever the registry serves at that minute, next to your API key. A pinned package names one version and the SHA-512 digest of that version's tarball, so every run installs the same bytes or stops.

Ask the registry for the digest of the version you have reviewed, and copy both into the kit:

$ npm view @anthropic-ai/[email protected] dist.integrity
sha512-OX/k/rpcthMqnFKOWcpNcbiLsMKtAjLOpQNJHlYiDCFUznWCIwdRTyl/p9SdHVrsrzZuPMCNqZjnpakIni6upw==

For each package kosa8 generates one install step. This is it, with the name, version and digest filled in from the kit (the digest is converted to the hexadecimal form sha512sum prints):

t=$(cd /tmp && npm pack --silent NAME@VERSION) \
  && echo "SHA512_HEX  /tmp/$t" | sha512sum -c - >/dev/null \
  && npm install -g --silent "/tmp/$t" \
  && rm -f "/tmp/$t"

1. npm pack downloads the exact tarball to /tmp.
2. sha512sum -c compares it with the digest in the kit.
3. npm install -g installs that file, never the name, which npm would look up again.

The steps are joined with &&, together with setup and the command, so one failing stops everything after it.

A failed check ends the run before the agent starts, with this from sha512sum:

sha512sum: WARNING: 1 of 1 computed checksums did NOT match

A package that is not written exactly is refused when the kit is loaded:

$ kosa8 agent run --dry-run ./bad.yaml
kosa8: ./bad.yaml: package cowsay: version "latest" is not exact (a range or a tag such as "latest" is whatever the registry says today)

What counts as unpinned

kosa8 reads each setup line and refuses the kit if any of them fetches code to run. The check is on the words of the line, in upper or lower case:

$ kosa8 agent run --dry-run ./unpinned.yaml
kosa8: kit quick installs software that is not pinned to a version and digest:
  npm install -g cowsay
list it under `packages:` with a version and integrity, or pass --allow-unpinned to run whatever the registry serves today

--allow-unpinned accepts those lines for one run. Use it while you are writing a kit, not for one a team depends on.

Signing kits

A kit decides what an agent can reach, so whoever can write a kit file decides that too. Signing lets an organisation say which kit files are its own, and lets each computer refuse the rest. It uses the same key that signs company rules, so one key vouches for policy and kits alike.

$ kosa8 policy keygen -o org.key
public:  kQ+JPoaWWs9JC1Nic/sRli1nJOAgQFAmmm+xtD0oEeo=
private key written to org.key (keep it secret)

$ kosa8 agent sign org.key team-claude.yaml
signed team-claude.yaml -> team-claude.yaml.sig

$ kosa8 policy trust org.key.pub
trusted policy signer set

Making a key, signing and pinning need the Governance subscription or a trial. Checking a signature never does.

What happens to a kit file

A bad signature is refused even where no key is pinned: somebody signed that kit, and these are not the bytes they signed.

A kit file with a built-in's name

A file in ~/.kosa8/kits takes the place of the built-in with the same name. That is how kosa8 agent init claude lets you customise claude, and it is also how something else writing to that folder could swap the kit you think you are running. So every run says when it has happened:

kosa8: warning: kit file /Users/you/.kosa8/kits/claude.yaml replaces the built-in kit of the same name

Where a key is pinned the replacement must also be signed by it, or it does not load at all.

The two built-ins that do not run

cursor and azmx are listed as UNAVAILABLE. Each used to install an npm package by name, and neither name can be vouched for. kosa8 refuses, with the reason, instead of installing something nobody checked and handing it an API key.

kosa8 agent init cursor writes a copy without the unavailable line. That copy is yours to make runnable: add an install step from a source you have checked yourself.

Where to go next