MAQPNADocs

Run agents in kosa8 sandboxes

Run a local agent in a kosa8 microVM that can reach only the MAQPNA gateway, live-fork it into a governed child session, and cross-anchor the two audit logs.

kosa8 runs every sandbox in its own microVM, and can live-fork a running sandbox into clones in about a second. With maqpna dev, kosa8 gives your agent three things:

  • A boundary. The agent runs in a microVM whose only network destination is the MAQPNA gateway, enforced by kosa8 on the host and in the guest.
  • An identity. The agent has its own short-lived MAQPNA session token, delivered as a file. It never appears in argv or in the agent's environment.
  • Fork. maqpna dev fork clones the running microVM into a child session. The child has its own token and the parent's lineage, taint and budget, and on llamay its model context forks too.

Before you begin#

  • kosa8 installed, with kosa8 daemon start run.
  • The maqpna CLI. See your first governed agent.
  • An agent image with /bin/sh. A small one such as alpine:3.20 is enough to try it.

Run an agent in a microVM#

maqpna dev up --kosa8 --llamay ~/models/qwen2.5-0.5b-instruct-q4_k_m.gguf
maqpna dev run --kosa8-image alpine:3.20 -- sh -c "$(cat examples/integrations/agent.sh)"

The example agent makes one model call and one MCP tool call through the gateway, then tries to reach the internet. You see:

{"choices":[{"message":{"content":"…","role":"assistant"}}],"model":"…","usage":{…}}
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"hello from kosa8","type":"text"}],"isError":false}}
egress: blocked
maqpna dev: dev-1a2b3c4d: 2 allow, cost $0.0000 (maqpna dev timeline --last)

When the command exits, the sandbox is removed and its disks are wiped. Keep it with --kosa8-keep. Size it with --kosa8-cpus and --kosa8-mem-mb.

dev up --kosa8 serves the gateway on this machine's LAN address, because kosa8 guests cannot reach your loopback. Every gateway route still requires a token. On an untrusted network, use a firewall.

Fork a running agent#

Start a long-running agent and keep its sandbox:

maqpna dev run --kosa8-image alpine:3.20 --kosa8-keep -- sh -c "HOLD=30; $(cat examples/integrations/agent.sh)"

From a second terminal, while it holds:

maqpna dev fork
# forked session dev-1a2b3c4d -> dev-1a2b3c4d-fork-1 (kosa8 sandbox maqpna-dev-1a2b3c4d-fork-1, 1997 ms)
maqpna dev timeline --session dev-1a2b3c4d-fork-1

The clone resumes mid-process. MAQPNA replaces its token file with the child session's token at once. If it cannot, it removes the clone. From then on, the clone's calls are audited as the child, with parentSession set. On llamay, the clone's first model call runs in a fork of the parent's inference context.

Agents must read the token from MAQPNA_TOKEN_FILE on each call; the MAQPNA SDKs do. An agent that reads the token once at start keeps the parent's identity after a fork.

Cross-anchored audit#

With dev up --kosa8, the gateway also writes to kosa8's audit log and reads it back:

  • It posts each MCP decision to kosa8's audit chain as an mcp.decision record (digests only), so kosa8 evidence export shows the governance decisions next to the sandbox events.
  • It anchors kosa8's audit head in the MAQPNA ledger every 30 seconds as kosa8/audit-anchor, or kosa8/audit-unverified if kosa8 reports a broken chain.

Good to know#

  • kosa8 is not a Kubernetes RuntimeClass, so in a cluster agents keep running in the gVisor, Kata and Confidential Containers tiers. What kosa8 would need to become a TrustTier runtime is listed in the integration design, docs/integrations/kosa8.md in the MAQPNA source.
  • The clone runs for a moment with the parent's token before MAQPNA can re-key it, because kosa8 resumes forks immediately. Those calls are attributed to the parent.

Next steps#