box

A box for your AI.

They can install, delete and break whatever they like inside it; nothing outside changes. Every command runs in a disposable microVM with its own kernel, defined in one file and started in milliseconds.

Docs · Architecture · Security · Benchmarks

Note: The codebase was developed using a vibe-coding approach, but the architecture, solution design, and key technical decisions were conceived and governed by me. The tool remains under development and should not yet be considered production-ready.

Install

curl -fsSL https://chxperiments.github.io/box/install.sh | sh
box doctor    # checks podman, libkrun and KVM, and prints a fix for anything missing

Needs Linux with KVM, podman and libkrun.

Quick start

box new devbox --from tiny-python     # scaffold a Boxfile
box build devbox                      # build the image, verify isolation
box run devbox -- python3 -c 'print(42)'   # one command, fresh VM

box up devbox                         # keep one VM running
box exec devbox -- pytest             # milliseconds per command
box down devbox

Boxfile

base: docker.io/library/alpine:latest
backend: auto          # firecracker when it fits, else podman; or name one
isolation: strict      # the VMM runs as a UID that is not yours
network: bridge        # or none, for no network at all
warm: 2                # keep VMs booted so runs start in ms
data_size: 10G         # cap /data, so an agent cannot fill your disk
packages: [python3, git]

Only /data persists between runs. Everything else is rebuilt every time.

Forks

box fork devbox try-a    # branch /data
box run try-a -- make
box diff try-a           # review what changed
box apply try-a          # or: box discard try-a

From code and agents

• SDKs: Python, TypeScript, Go, Rust
• MCP: claude mcp add box -- box mcp. Agents can fork but not apply, unless you start it with --allow-apply. Long output is shown by its first and last lines, with the rest one output call away, and a re-read of something unchanged costs one line, not the content.
• Other machines: list them in ~/.box/hosts.yaml and box mcp fronts them too, over ssh; a sandbox there is host/name. box hosts shows them.

hosts:
  - name: gpu1
    ssh: me@gpu1.example.com

from sdbox import Sandbox

with Sandbox("devbox") as sb:
    print(sb.exec(["python3", "-c", "print(6 * 7)"]).stdout_text)

Security

Each sandbox is a microVM under KVM, and the VMM itself is confined: no new privileges, seccomp, a reduced capability set, its own network namespace and, under isolation: strict, a UID that is not yours. box inspect <name> --security-report shows what a sandbox can and cannot touch, read from the configuration box applies and checked against the running VMM. security/escape-test.sh tries what an agent gone wrong would. See SECURITY.md for the threat model.

Development

CGO_ENABLED=0 go build -o box ./cmd/box
go test ./...
security/escape-test.sh ./box strict    # needs KVM

License

MIT