kosa8 docs

Guides / How kosa8 works

How kosa8 works

kosa8 is three programs and a boundary. A command-line tool you type into, a background service that does the work, and a small helper inside every virtual machine. Everything an AI assistant does happens on the far side of the boundary; everything that decides what it may do stays on yours.

The whole thing in one picture

kosa8 architecture On your computer: the kosa8 command and an AI client talk to the kosa8d service over a private socket. kosa8d holds the policy, the audit log and the network guard. Each sandbox is a separate virtual machine with its own kernel, reached only through a control channel and a filtered network. Your computer — trusted kosa8 the command you type kosa8 mcp serve the door an AI client knocks on socket kosa8d the background service — runs as you, not as root policy signed rules, approvals audit log every action, chained identity which agent is asking network guard sees every packet a VM sends egress broker holds the API keys A sandbox — its own virtual machine, untrusted its own Linux kernel kosa8-guestd + containerd your containers run here the AI assistant sees one folder you chose holds a placeholder, not a key control channel (vsock) every packet hosts you named reached through the broker everything else refused on your side, logged
What runs where. The dashed lines are trust boundaries; the moving lines are the only ways across them.
  1. You type a command, or an AI client calls a tool. Both arrive at the same place.
  2. kosa8d, a service running as your user, receives it over a socket only you can open.
  3. Before anything happens it is checked against policy, attributed to whoever asked, and written to the audit log.
  4. The work itself runs in a sandbox: a real virtual machine with its own kernel. Nothing in it can see your files except the one folder you shared.
  5. Every packet the machine sends passes the network guard, which lives on your side where nothing inside the machine can reach it.
  6. API keys stay with the broker. The assistant gets a stand-in that is worthless anywhere else.
  7. Requests to the hosts you named go out, with the real key added on the way.
  8. Anything else is refused before it leaves your computer, and the attempt is recorded.

The three programs

kosa8The command-line tool. It holds no state and does no work of its own: every command is a request to the service. That is why the Mac app, the CLI and an AI client always agree about what is running — they are all asking the same thing.
kosa8dThe background service. It starts and stops virtual machines, enforces policy, runs each sandbox's network, and is the only writer of the audit log. It runs as you, without administrator rights.
kosa8-guestdA small helper inside each virtual machine. It starts containers when the service asks. It is on the untrusted side: nothing the service decides depends on it telling the truth.

Two kinds of place to run things

kosa8 can run a container in two places, and the difference matters.

The shared engine

kosa8 run and the Docker-compatible API use one always-warm virtual machine for all your everyday containers. It starts in milliseconds and behaves like Docker. Containers in it are separated from your Mac by a VM, and from each other by ordinary container isolation.

A sandbox

kosa8 sandbox and kosa8 agent run give the work a virtual machine of its own: its own kernel, its own disk, its own private network with its own rules. This is where an AI assistant belongs, and where save, copy and undo work.

Want everything in a sandbox?

An organisation can require it. With require_sandbox in the signed policy, the shared engine refuses to run anything and every container gets a machine of its own. See Policy reference.

What crosses the boundary

A sandbox is useful only if the list of things that cross into and out of it is short. This is the whole list.

CrossingDirectionWho controls it
Control channelYour side → sandboxThe service only. It is not a network connection, and the sandbox cannot open one back.
Shared folderBothYou, when you create the sandbox. Exactly the folders you named; writable unless you add :ro.
NetworkSandbox → worldThe network guard, by the sandbox's rules. See Network rules.
CredentialsNeverThey stay with the broker. See Keep API keys out of the sandbox.
Disk and memoryNeitherEach sandbox has its own. A snapshot is a file on your side that the sandbox cannot read.

What happens when you create a sandbox

Creating a sandbox Five steps left to right: check policy, clone the disk, start the network, boot the virtual machine, ready. checkpolicy, labels,approvals clone diskcopy-on-write,costs nothing yet networkprivate, with itsrules in place boota real kernel,under a second readyrecorded in theaudit log
The network and its rules exist before the machine boots, so there is no moment in which a sandbox is running without them.
$ kosa8 sandbox create dev --egress-allow registry.npmjs.org
sandbox dev ready in 737ms (32 GB disk)
$ kosa8 sandbox pull dev alpine
$ kosa8 sandbox run dev alpine uname -r
6.18.35
$ kosa8 sandbox egress dev
policy:   allow:registry.npmjs.org (enforced on the host)
frames:   3 passed, 0 denied, 1 dropped as link noise
dns:      2 answered, 0 refused

Where things are kept

All of kosa8's state is in one folder in your home directory, ~/.kosa8, readable only by you.

PathWhat it is
run/kosa8.sockThe socket the command talks to the service over.
sandboxes/Each sandbox's disks and record.
snapshots/Saved machines.
audit.jsonl, audit.keyThe audit log and the key that makes it tamper-evident.
policy.json, mcp-policy.jsonYour organisation's signed rules, if it has any.
agents.jsonAgent identities. Tokens are stored as digests, never as themselves.
mcp-servers.json, mcp-pins.jsonThird-party tool servers and the definitions they are pinned to.
kits/Your own sandbox kits.
log/The service's log and each sandbox's console.

Where to go next

Securing an agent The layers between an AI assistant and the things it could damage. Network rules What a sandbox can reach, and where that is enforced. The audit log What is written down, and how to prove nobody edited it. For developers The source layout, the API, and how to build and test.