One YAML file per sandbox at ~/.box/sandboxes/<name>/Boxfile. Unknown keys are rejected, so a typo fails loudly.
| Field | Values | Default | Meaning |
|---|---|---|---|
| base | image reference | alpine:latest | The image every VM starts from. |
| backend | podman, krun, firecracker | podman | What boots the VM. See Architecture. |
| isolation | standard, strict | standard | strict runs the VMM as a subordinate UID. |
| cpus | 1 to 16 | 2 | vCPUs. |
| ram_mib | 128 and up | 2048 | Guest RAM in MiB. |
| network | bridge, none | bridge | Internet access, or none at all. |
| readonly | bool | false | Read-only root; /tmp and /data stay writable. |
| timeout_seconds | int | 0 | Per-command limit; exits 124. 0 is unlimited. |
| warm | 0 to 8 | 0 | VMs kept booted for run (podman, krun). |
| warmup | shell lines | Run once in each warm VM before it serves a run. | |
| packages | names | Installed with the image's package manager. | |
| run | shell lines | Extra build steps. | |
| env | map | Environment for every command. | |
| mounts | host, guest, mode | Host directories shared in (podman, krun); ro by default. | |
| blueprint | users, write_files, runcmd | Provisioning applied at build time. | |
| pkgmgr | apk, apt, dnf | inferred | Override the package manager. |
| passt | bool | false | A real NIC with a default route (podman, krun). |
| seccomp | path | A seccomp profile for the VMM. | |
| base | image reference | alpine:latest | The image every VM starts from. |
| backend | podman, krun, firecracker | podman | What boots the VM. See Architecture. |
| isolation | standard, strict | standard | strict runs the VMM as a subordinate UID of the sandbox's own. |
| cpus | 1 to 16 | 2 | vCPUs. |
| ram_mib | 128 and up | 2048 | Guest RAM in MiB. |
| network | bridge, none | bridge | Internet access, or none at all. |
| readonly | bool | false | Read-only root; /tmp and /data stay writable. |
| timeout_seconds | int | 0 | Per-command limit; exits 124. 0 is unlimited. |
| warm | 0 to 8 | 0 | VMs kept booted for run (podman, krun). |
| warmup | shell lines | Run once in each warm VM before it serves a run. | |
| packages | names | Installed with the image's package manager. | |
| run | shell lines | Extra build steps. | |
| env | map | Environment for every command. | |
| mounts | host, guest, mode | Host directories shared in (podman, krun); ro by default. | |
| blueprint | users, write_files, runcmd | Provisioning applied at build time. | |
| pkgmgr | apk, apt, dnf | inferred | Override the package manager. |
| passt | bool | false | A real NIC with a default route (podman, krun). |
| seccomp | path | A seccomp profile for the VMM. |
I'm evaluating box (https://github.com/chxperiments/box) for something I'm building. Help me decide whether it fits, and if it does, how to set it up correctly. Use only the facts below about box; if something isn't covered here, say so instead of guessing. ## What box is @@ -259,7 +259,7 @@Not sure it fits? Ask your AI.
## Security model Two layers: the guest runs on its own kernel under KVM, and the VMM process on the host is itself confined (no_new_privs, seccomp, its own network namespace, pids and memory limits, a reduced capability set; Firecracker's VMM runs with zero capabilities). With `isolation: strict` the VMM runs as a subordinate UID instead of yours, so escaping both the VM and the VMM does not land in your account. Use strict for agents. An escape test suite ships in the repo. -Not covered: all strict sandboxes share one subordinate UID, so strict separates sandboxes from you, not from each other. The kernel check catches a fallback to a plain container but cannot catch a guest that lies about its kernel. It is not designed for hostile multi-tenant hosting. +Each strict sandbox gets its own subordinate UID, so one sandbox cannot reach another's files; the number of strict sandboxes is limited by the user's /etc/subuid range (box doctor shows it, and box prints the fix when it runs out). Not covered: the kernel check catches a fallback to a plain container but cannot catch a guest that lies about its kernel. It is not designed for hostile multi-tenant hosting. ## Requirements and limits Linux with KVM (/dev/kvm), podman and libkrun (crun built with +LIBKRUN). macOS works through a podman machine, but up/exec, the warm pool, forks and the krun and firecracker backends are Linux-only. It runs on your machine or your server: it is not a hosted service and has no GPU support. `box shell` has a TTY; `exec` does not yet. @@ -273,8 +273,8 @@Not sure it fits? Ask your AI.
Still unsure? Ask your AI with the prompt above.
-A container shares your host's kernel, so a kernel bug or a careless mount reaches your machine. box runs each sandbox as a microVM under KVM with its own kernel, and refuses to run one whose kernel matches the host's, which would mean it quietly became a plain container.
Only once, to install podman and libkrun and create the krun symlink. After that everything runs as you, with rootless podman. Your user needs write access to /dev/kvm (usually the kvm group), and isolation: strict needs a range in /etc/subuid. box doctor checks all of it and prints the fix.
Linux with KVM is the main target. On macOS it runs through a podman machine, but up/exec, the warm pool, forks and the krun and firecracker backends are Linux-only. On Windows, use WSL2 with /dev/kvm available: the published benchmarks were measured that way.
A cold run takes about 1.3 s on podman, 0.75 s on krun and 0.3 s on firecracker. With warm: set, a fresh-VM run takes 20 to 45 ms, and exec into a running sandbox about 15 ms. Method and numbers.
Only /data, a directory on your host at ~/.box/data/<name>/. Every run is a new VM, so installed packages, files elsewhere and processes are gone. up keeps one VM alive when you want state to last across commands.
With network: bridge it reaches the internet; with network: none it has no network at all. Either way it has its own network namespace and cannot reach services on your host's loopback. It sees only the host directories its Boxfile declares, read-only unless you say rw.
Not outside its sandbox. Inside, it can do anything, even rm -rf /, and the next run starts clean. Only /data and the host folders you declare are kept, and forks let you review its changes before they reach your data. Use isolation: strict: the VMM around the agent is confined and runs as a UID that is not yours. box is built for your own agents, not for hosting strangers' code, and strict sandboxes share one UID between them. The threat model covers what it does not protect.
Start with podman, the default: it supports everything. krun boots faster but supports isolation: standard only, for now. firecracker is fastest to start but is x86_64-only and has no network, host mounts or forks yet.
Add the MCP server: claude mcp add box -- box mcp. The agent can run, exec, read and write files, and fork, but cannot apply a fork to real data unless you start the server with --allow-apply. Creating and building sandboxes stays with you.
Neither. box runs on your laptop or your own server, MIT-licensed and free. Nothing is sent anywhere. It also has no GPU support, so GPU workloads need something else.
A container shares your host's kernel, so a kernel bug or a careless mount reaches your machine. box runs each sandbox as a microVM under KVM with its own kernel, and refuses to run one whose kernel matches the host's, which would mean it quietly became a plain container.
Only once, to install podman and libkrun and create the krun symlink. After that everything runs as you, with rootless podman. Your user needs write access to /dev/kvm (usually the kvm group), and isolation: strict needs a range in /etc/subuid. box doctor checks all of it and prints the fix.
Linux with KVM is the main target. On macOS it runs through a podman machine, but up/exec, the warm pool, forks and the krun and firecracker backends are Linux-only. On Windows, use WSL2 with /dev/kvm available: the published benchmarks were measured that way.
A cold run takes about 1.3 s on podman, 0.75 s on krun and 0.3 s on firecracker. With warm: set, a fresh-VM run takes 20 to 45 ms, and exec into a running sandbox about 15 ms. Method and numbers.
Only /data, a directory on your host at ~/.box/data/<name>/. Every run is a new VM, so installed packages, files elsewhere and processes are gone. up keeps one VM alive when you want state to last across commands.
With network: bridge it reaches the internet; with network: none it has no network at all. Either way it has its own network namespace and cannot reach services on your host's loopback. It sees only the host directories its Boxfile declares, read-only unless you say rw.
Not outside its sandbox. Inside, it can do anything, even rm -rf /, and the next run starts clean. Only /data and the host folders you declare are kept, and forks let you review its changes before they reach your data. Use isolation: strict: the VMM around the agent is confined and runs as a UID that is not yours. Each strict sandbox gets a UID of its own, so one cannot reach another's files. box is built for your own agents, not for hosting strangers' code. The threat model covers what it does not protect.
Start with podman, the default: it supports everything. krun boots faster but supports isolation: standard only, for now. firecracker is fastest to start but is x86_64-only and has no network, host mounts or forks yet.
Add the MCP server: claude mcp add box -- box mcp. The agent can run, exec, read and write files, and fork, but cannot apply a fork to real data unless you start the server with --allow-apply. Creating and building sandboxes stays with you.
Neither. box runs on your laptop or your own server, MIT-licensed and free. Nothing is sent anywhere. It also has no GPU support, so GPU workloads need something else.
Use isolation: strict for agents. Under standard isolation the VMM runs as your user, so escaping both the guest kernel and the VMM lands in your account. Strict maps it to your first subordinate UID instead.
Use isolation: strict for agents. Under standard isolation the VMM runs as your user, so escaping both the guest kernel and the VMM lands in your account. Strict maps it to a subordinate UID of the sandbox's own instead, which owns nothing of yours and nothing of any other sandbox's.
/data, a mount or env: is the workload's. Credential brokering is planned.uname.network: bridge it reaches the internet; with network: none it has no network at all. Either way it has its own network namespace and cannot reach services on your host's loopback. It sees only the host directories its Boxfile declares, read-only unless you say rw."),
("Can my AI agent break anything?",
- "Not outside its sandbox. Inside, it can do anything, even rm -rf /, and the next run starts clean. Only /data and the host folders you declare are kept, and forks let you review its changes before they reach your data. Use isolation: strict: the VMM around the agent is confined and runs as a UID that is not yours. box is built for your own agents, not for hosting strangers' code, and strict sandboxes share one UID between them. The threat model covers what it does not protect."),
+ "Not outside its sandbox. Inside, it can do anything, even rm -rf /, and the next run starts clean. Only /data and the host folders you declare are kept, and forks let you review its changes before they reach your data. Use isolation: strict: the VMM around the agent is confined and runs as a UID that is not yours. Each strict sandbox gets a UID of its own, so one cannot reach another's files. box is built for your own agents, not for hosting strangers' code. The threat model covers what it does not protect."),
("Which backend should I use?",
"Start with podman, the default: it supports everything. krun boots faster but supports isolation: standard only, for now. firecracker is fastest to start but is x86_64-only and has no network, host mounts or forks yet."),
("How do I let an agent use it?",
@@ -550,7 +550,7 @@ def conf_table():
Use isolation: strict for agents. Under standard isolation the VMM runs as your user, so escaping both the guest kernel and the VMM lands in your account. Strict maps it to your first subordinate UID instead.
Use isolation: strict for agents. Under standard isolation the VMM runs as your user, so escaping both the guest kernel and the VMM lands in your account. Strict maps it to a subordinate UID of the sandbox's own instead, which owns nothing of yours and nothing of any other sandbox's.
/data, a mount or env: is the workload's. Credential brokering is planned.uname.