Guides / Run an AI assistant
Run an AI assistant
kosa8 ships ready-made setups, called kits, for the common coding assistants. Each runs in a virtual machine of its own, sees only the folder you hand it, reaches only the hosts it needs — and works with your API key without ever being given it.
- You choose one folder. Nothing else on your computer exists as far as the assistant is concerned.
- The assistant starts in its own virtual machine with a stand-in where the API key would be.
- Its only way out is a broker running on your computer, which holds the real key.
- A request to the model provider goes out with the real key added on the way.
- A request anywhere else is refused before it leaves your computer, and recorded.
What is ready to go
$ 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 KEYS column is the one to read. Brokered means the assistant never holds your
key. Passed in means it does: the Copilot CLI cannot be pointed at a different address, so
its token still has to go inside, and kosa8 says so every time you run it. Two kits,
cursor and azmx, are listed as unavailable until their installers can be
verified — Writing a kit explains why.
Set your key, on your computer
$ export ANTHROPIC_API_KEY=sk-ant-…
This is the only place it needs to be. kosa8 reads it when you start the assistant and hands it to the broker, not to the sandbox.
Run one in your project
$ cd ~/code/api $ kosa8 agent 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: sandbox claude-44059 ready in 653ms kosa8: pulling node:22-alpine kosa8: running kit setup, then: claude
Read the four lines at the top. They are kosa8 telling you, before anything runs, exactly what this assistant will be able to see, reach and use.
Or point it at another folder
$ kosa8 agent run -w ~/code/web claude
Options go before the kit's name; anything after it is passed to the assistant itself.
--dry-run prints the plan and stops without starting anything.
When it ends, it is gone
kosa8: sandbox claude-44059 removed
The sandbox is removed when the assistant exits — cleanly, with an error, or because you
pressed Ctrl-C — and the broker and the key it held go with it. Your project folder keeps
whatever the assistant changed. Use --keep to keep the machine for a look around.
What the assistant can and cannot do
| It can | It cannot |
|---|---|
| Read and change the folder you shared. | See any other file on your computer. |
| Call its model provider, through the broker. | Read your API key, or send it anywhere. |
| Reach the hosts its kit lists, by name. | Reach any other host, any address directly, or any service on your own computer. |
| Install the exact package version its kit pins. | Install a different one: the download is checked against a fingerprint first. |
| Run as root inside its own machine. | Change any of the above from in there. The rules live on your side. |
The assistant can change anything in the folder you give it, including .git and
any .env file in it. Share a project, not your home directory, and take a
checkpoint or a commit first.
See what it did
Every request the assistant made through the broker — allowed or refused — is in the audit log, along with every command kosa8 ran for it. So is every tool call the model told it to make: kosa8 reads them from the model's own reply on your side of the sandbox, so the assistant cannot leave one out. The log keeps each call's name and a fingerprint of its arguments, not the arguments.
$ kosa8 audit ls 21 02:16:29 guest sandbox.egress.allow claude-44059 200 22 02:16:29 guest sandbox.tool_call claude-44059 200 23 02:16:31 guest sandbox.egress.deny claude-44059 403 $ kosa8 audit verify audit chain intact: 23 entries verified
The audit log shows how to read these and how to ask it questions.
Checked before it runs
With the claude kit, every tool call is checked against kosa8's
rules for tool calls before it runs, not only recorded after. A
download piped into a shell, or an edit to the assistant's own settings, is refused. A force push,
a package publish or a terraform destroy waits for you:
$ kosa8 mcp asks 9c41e07b2d5a6f18 pending sandbox:claude-44059/Bash by (unidentified agent) why: K8-A001: rewrites or deletes history on a remote, which a rewind here cannot undo args: {"command":"git push --force origin main"} until 14:32:10 $ kosa8 mcp approve 9c41e07b2d5a6f18
The assistant is told the call is waiting and tries it again once you approve; it runs once,
exactly as approved. If the check cannot be made — the broker is gone, or the assistant has
broken the hook — the call is refused, and a call the model asked for that was never checked is
written to the audit log as sandbox.tool_call.unchecked.
Stop everything, now
$ kosa8 sandbox pause --all
paused claude-44059, codex-1187
Every running sandbox freezes where it is — the assistants stop mid-step, with their memory and
files intact for you to look at. kosa8 sandbox resume NAME lets one carry on.
Letting an assistant drive kosa8 itself
kosa8 is also an MCP server: an assistant running anywhere can ask it to make sandboxes, take checkpoints and fork machines, without you typing the commands.
$ kosa8 mcp serve # stdio, for a local client $ kosa8 mcp serve --http 127.0.0.1:7433 --allow-mount ~/work # prints a token; send it as a Bearer header $ kosa8 mcp tools # everything it exposes
A sandbox an assistant creates this way has no network unless it asks for specific hosts, and
can share a folder only from the directories you allowed with --allow-mount.
Tool servers (MCP)
Run third-party tool servers sealed off, with their definitions pinned.
Rules for tool calls
Decide a call by what it asks for, and hold the risky ones for a person.
Agent identity
Give each agent a name the audit log can trust and rules of its own.
MCP from TypeScript
kosa8's tools in the AI SDK, LangChain.js and Mastra, tested.
Building your own agent
If you are writing the agent rather than running one, give it a sandbox from code. With the
Vercel AI SDK, @kosa8/ai-sdk-sandbox hands your tools a sealed machine to read, write
and run in; with anything else, @kosa8/sdk drives sandboxes, the broker, checkpoints
and forks directly.
Vercel AI SDK adapter
An AI SDK agent whose files and commands live in a microVM.
JavaScript and TypeScript
The SDK, the adapter, MCP and the Docker API: which to use.
The built-in assistant
kosa8 also has its own, which sees your live container state and runs every proposed action through an approval gate.
$ kosa8 ai -m "why did the api container exit?"
You can let ordinary work run without prompting, but destructive and escalating actions are always confirmed — whatever you put in the settings. A switch that turns off every safeguard is not a safeguard.
Where to go next
Securing an agent
Every layer between an assistant and what it could damage, and what each does not do.
Keep API keys out
How the broker works, and how to broker your own tool's key.
Writing a kit
Describe your own assistant's environment: image, packages, hosts, keys.
Agent troubleshooting
Every refusal message, what it means and what to do.