Guides / AI agents / One task, one sandbox

One task, one sandbox

kosa8 prompt is the shortest way to use kosa8. You give it a task. It starts a fresh sandbox, runs a coding agent on the task with no one at the keyboard, prints what the agent says, and removes the sandbox when the agent is done.

$ kosa8 prompt "add a test for parseConfig and make it pass"
kosa8: kit claude (node:22-slim)
kosa8: workspace /Users/you/src/app -> /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 (the sandbox holds a placeholder, never the key)
kosa8: sandbox claude-41822 ready in 690ms
...the agent works...
kosa8: claude finished in 2m14s (sandbox claude-41822 removed; what it did: `kosa8 audit ls`)

What the agent can and cannot do

It is the same sandbox kosa8 agent run makes, so the same limits hold:

One folder. The current directory, or the one you name with -w, appears at /work. The agent can change files there, and you see the changes on your machine. Nothing else on the host is visible.
Listed hosts only. The network is the kit's allow-list. --no-network closes it completely.
No API key. Your key stays on your machine, in kosa8's egress broker. The sandbox gets a placeholder that is worthless anywhere else.
Checked tool calls. With the claude kit, each tool call is checked against your rules before it runs. Calls held for a person show up in kosa8 mcp asks.
A record. Everything lands in the hash-chained audit log.

Inside that boundary the agent runs with its own permission prompts off, because there is no one to answer them. That is what the sandbox is for: the agent can do anything to the machine it is in, and nothing to yours.

Choosing the agent

Flag	Agent	Key it needs on your machine
`-a claude` (default)	Claude Code	`CLAUDE_CODE_OAUTH_TOKEN` (your Claude Pro or Max plan, from `claude setup-token`), or `ANTHROPIC_API_KEY`
`-a codex`	OpenAI Codex CLI	`OPENAI_API_KEY`
`-a gemini`	Gemini CLI	`GEMINI_API_KEY`
`-a opencode`	OpenCode	`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
`-a copilot`	GitHub Copilot CLI	`GITHUB_TOKEN` (passed in: Copilot cannot use the broker)
`-a shell`	A plain shell; the task is a shell command	none, and no network

Set KOSA8_AGENT to change the default.

With the claude kit, a subscription token is used when one is set, and the API key otherwise. Either way it stays on your machine in the broker: the sandbox only ever holds a placeholder. Make the token in a terminal of your own (it is shown once), then add export CLAUDE_CODE_OAUTH_TOKEN=... to your shell profile.

Giving it the task

$ kosa8 prompt -w ~/src/api "why does TestLogin flake? fix it if you can"
$ git diff main | kosa8 prompt -a codex -
$ kosa8 prompt --dry-run "upgrade lodash"     # shows the plan, creates nothing

The task is the rest of the command line. With -, or with nothing and input piped in, it is read from standard input. Put flags before the task: everything after the first word that is not a flag is the task. Large material belongs in the workspace, with the task saying where it is. The task itself is limited to 96 KiB.

Afterwards

The exit status is the agent's, so kosa8 prompt works in scripts and CI. To look inside the sandbox when it is done, pass --keep. It stays until you remove it with kosa8 sandbox rm NAME.

Your own agent

Any kit can take a task once it says how. Add a prompt line to it, with {{prompt}} where the task goes:

$ kosa8 agent init claude          # copy the built-in to ~/.kosa8/kits/claude.yaml
# then, in the file:
prompt: ["claude", "-p", "{{prompt}}", "--permission-mode", "bypassPermissions"]
prompt_env:
  IS_SANDBOX: "1"

Each item is passed as one argument, so the task is never read as shell. A kit without a prompt line can still be run interactively with kosa8 agent run. See Writing a kit.