kosa8 docs

kosa8 documentation

kosa8 gives an AI assistant its own sealed computer, and gives you a way to save that computer mid-task, copy it, and put it back when something goes wrong.

These pages cover all of it: short walkthroughs you can follow end to end on your own machine, and a reference page for every one of the 225 commands, generated from the binary itself so it cannot drift from what your copy actually does.

New here?

Read Install, then Your first sandbox. Fifteen minutes and you will have run something in an isolated machine, saved it, broken it on purpose, and put it back.

Nothing to install? Sign in to kosa8 Cloud and run the same sandboxes on our hosts from code; kosa8 Cloud walks through it.

Start with a walkthrough

Install One line, or the Mac app. Both take about a minute. Your first sandbox Make a sealed machine and run something inside it. kosa8 Cloud No install: sign in, make an API key, create sandboxes from code. Save and undo Checkpoint before something risky, rewind after it goes wrong. Try several ideas at once Fork a machine per idea and let kosa8 report which worked. The Mac app A window onto everything running. Local models Run AI on your own machine, no tokens, nothing sent out.

Run AI agents safely

A sealed machine keeps an agent away from your computer. It does not, by itself, keep your API key away from the agent, or stop the agent sending your work to a host it is allowed to reach, or tell you which agent did what. These pages cover the parts of kosa8 that do.

The layers around an agent Six layers, left to right, each checking an agent's action in turn: a virtual machine of its own, a network closed except for named hosts, API keys that stay on your computer, tool definitions pinned and checked, rules that decide each tool call, and an audit log of all of it. its own VMone folder,nothing else networknamed hostsonly keysstay on yourcomputer toolspinned andchecked rulesallow, deny,or ask you audit logwho did what,provably
Everything an agent does passes each of these, in turn.
Run an AI assistant Claude Code, Codex, Gemini and others, sealed off, without your key. Securing an agent Every layer, what it answers, and what it does not. Keep API keys out The agent uses your key without ever holding it. Network rules What a sandbox can reach, and where that is enforced. Tool servers (MCP) Third-party tools, each in its own machine, definitions pinned. Rules for tool calls Decide a call by what it asks for. Hold the risky ones for a person. Agent identity A name the audit log can trust, and rules per agent. Writing a kit Describe an agent's environment; pin and sign it. Agent troubleshooting Every refusal message, what it means, what to do.

SDKs in five languages

Official SDKs for Python, TypeScript, Go, Ruby and Java do the same things with the same names: sandboxes, running code, checkpoints and rewind, fork and explore, snapshots and approvals. None has a runtime dependency.

SDKs overview What they do in plain words, and how to install each. Python pip install kosa8 Go go get github.com/kosa8ai/kosa8-go Ruby gem install kosa8 Java com.kosa8:kosa8 on Maven Central Native HTTP API The API every SDK is built on, endpoint by endpoint.

From JavaScript and TypeScript

Two npm packages drive kosa8 from Node: @kosa8/sdk, a typed client for sandboxes, checkpoints, forks and the broker, and @kosa8/ai-sdk-sandbox for the Vercel AI SDK. Every example in that section was run against a real daemon, with its output.

Choosing a path The SDK, the AI SDK adapter, MCP or the Docker API. Quickstart A sandbox, a command, a checkpoint and a rewind, in five steps. Vercel AI SDK adapter Give an AI SDK agent a sealed machine. Recipes Untrusted code, coding agents, migrations, API routes, MCP, Testcontainers.

For a company

Company rules Signed policy that a laptop cannot edit its way around. Policy reference Every field of both signed documents, and where each is enforced. The audit log What is written down, and how to prove nobody edited it.

Under the hood

How kosa8 works The parts, what runs where, and what crosses each boundary. For developers The source layout, the API, and how to build and test.

What makes kosa8 different

Most container tools can save your files. kosa8 saves the whole running machine — the programs that are open and what they were part-way through doing. Bringing one back does not restart anything: a server that was running is still running, from the moment you saved it.

That is what makes copying useful. A copy is not a fresh machine you have to set up again. It is the finished one, already warm, ready to try something.

# save it, break it, put it back
$ kosa8 checkpoint web --label "before migration"
checkpoint web-ckpt-1 (before migration) saved in 2281ms

$ kosa8 rewind web -y
web is back at web-ckpt-1 (1065ms)
  processes resumed from 2m ago

Find a command

Press / anywhere on these pages to search, or browse the full command reference. Every page lists the flags, their defaults and what the command prints.

Before you start

The part that actually runs containers needs Apple's Virtualization framework, so it works on Apple Silicon Macs only. On Windows and Linux you get the command-line tool, pointed at a Mac that does the work. Shared folders run at about a third of native speed — a real cost of the isolation, and one we would rather you read here than discover later.