# 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`](https://docs.kosa8.com/guides/agents/) 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](https://docs.kosa8.com/guides/tool-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](https://docs.kosa8.com/guides/audit/).

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](https://docs.kosa8.com/guides/kits/).

---
Source: https://docs.kosa8.com/guides/prompt/