README
¶
aibox
aibox runs Claude Code in a small virtual machine on your computer.
Claude Code can read and change files, run commands and access the internet. That is what makes it useful, but it also means a bad prompt or a malicious file in a repository can make it do things you did not want. aibox limits the damage. Claude Code only sees the files you give it, and it can only connect to hosts you allow.
You can use aibox in two ways:
aibox runstarts Claude Code in your project folder, like you would on your machine. Changes show up in the folder right away.aibox taskhands Claude Code a job to do on its own. It works on a clone of the last commit and you get its commits back to review. The VM is deleted afterwards.
aibox runs on Linux with QEMU and on macOS with Virtualization.framework. The VM boots in about a second.
Note that with aibox run the VM can change anything in your project folder,
.git included. Treat those changes like a pull request from a stranger.
Read What the VM writes
before you start.
Why a VM
Claude Code's own sandbox only covers shell commands. Its file tools, MCP servers and hooks still run on your machine. A Docker container covers the whole process, but shares your kernel. A VM has its own kernel, so a kernel bug alone is not enough to get out. aibox keeps that VM small, with no network card and a proxy as its only way to the network. Why a VM compares aibox with these, Apple's container tool and Docker Sandboxes.
Installing
On macOS with Apple silicon, install it with Homebrew:
brew install --cask the127/tap/aibox
On Linux, download a package from the
releases. There is a deb and an
rpm for amd64, which pull in QEMU, virtiofsd and bubblewrap. There is also
a tar.gz with just the binary, and then you install those three yourself.
aibox needs Linux 6.7 or newer and access to /dev/kvm.
With Nix, on Linux on amd64 or macOS on Apple silicon:
nix profile install github:The127/aibox
The first aibox run downloads the VM image, which is about 150 MB.
Installing has the details
and shows how to check a download.
Your first run
Go to a project and start aibox:
cd ~/projects/my-app
aibox run
This boots the VM with my-app at /project and starts Claude Code in it.
Open the project in your editor next to it and watch the changes come in.
Log in to Claude Code like you would on your machine. aibox keeps the login for the next run.
The first run also writes a config for the project. It only allows the hosts Claude Code needs. To allow more, run:
aibox config edit
Your first task
A task works on a clone of the last commit, with nobody there to log in. So
it takes a token from your shell instead. First make one with
claude setup-token and export it as CLAUDE_CODE_OAUTH_TOKEN. Then add it
to env in the project config:
env:
- CLAUDE_CODE_OAUTH_TOKEN
Now give Claude Code a job:
aibox task "fix the flaky test in internal/proxy"
When the task is done, aibox prints a command that fetches its commits into a branch. Read them before you use them.
Note that a task can use every host, port and secret the config gives it, with nobody watching. Read Tasks before you run one. It also explains when to use an API key instead of a token.
Documentation
The documentation is at https://the127.github.io/aibox. It covers tasks, the project config, git, containers, what aibox protects you from and what it doesn't, and how it all works.
Contributing
Contributions are welcome. See CONTRIBUTING.md for the
development setup and how to build the VM image. In short: commits follow
plain Conventional Commits (type: description, no scopes) and must be DCO
signed off (git commit -s). Git hooks check both.
Security
Please report vulnerabilities privately, see SECURITY.md.
License
aibox is licensed under the Apache License 2.0.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
aibox
command
Command aibox runs Claude Code inside a microVM.
|
Command aibox runs Claude Code inside a microVM. |
|
aibox-init
command
Command aibox-init is the first process of the aibox VM.
|
Command aibox-init is the first process of the aibox VM. |
|
internal
|
|
|
anthropic
Package anthropic forwards the requests of Claude Code in the VM to the Claude API and adds the API key on the host, so that the VM never holds the key.
|
Package anthropic forwards the requests of Claude Code in the VM to the Claude API and adds the API key on the host, so that the VM never holds the key. |
|
backend
Package backend says what a run of the aibox VM needs and what runs it.
|
Package backend says what a run of the aibox VM needs and what runs it. |
|
cli
Package cli defines the aibox command line.
|
Package cli defines the aibox command line. |
|
config
Package config reads the settings of a project.
|
Package config reads the settings of a project. |
|
confine
Package confine takes from the aibox process what it no longer needs once the VM runs: new privileges, the file system but for the resolver files, TCP but for connecting to the allowed ports, and the syscalls that reach into the kernel, other processes or namespaces.
|
Package confine takes from the aibox process what it no longer needs once the VM runs: new privileges, the file system but for the resolver files, TCP but for connecting to the allowed ports, and the syscalls that reach into the kernel, other processes or namespaces. |
|
gitbroker
Package gitbroker lets git in the VM fetch from and push to the remotes the project config names, with the git login of the host, so that the VM never holds the login.
|
Package gitbroker lets git in the VM fetch from and push to the remotes the project config names, with the git login of the host, so that the VM never holds the login. |
|
gitconfig
Package gitconfig carries the git identity of the host into the VM.
|
Package gitconfig carries the git identity of the host into the VM. |
|
guest
Package guest is the first process of the VM.
|
Package guest is the first process of the VM. |
|
host
Package host serves the proxy and the terminal of a running VM, however the VM was started and however its listeners came about, and says how the run ended.
|
Package host serves the proxy and the terminal of a running VM, however the VM was started and however its listeners came about, and says how the run ended. |
|
image
Package image downloads the VM image of a release of aibox: the kernel and the root disk, which a release carries as one archive for each architecture.
|
Package image downloads the VM image of a release of aibox: the kernel and the root disk, which a release carries as one archive for each architecture. |
|
launch
Package launch runs the aibox VM: virtiofsd for each share, the proxy and the terminal for the VM, then QEMU.
|
Package launch runs the aibox VM: virtiofsd for each share, the proxy and the terminal for the VM, then QEMU. |
|
machine
Package machine prepares on the host what a backend that boots the kernel of aibox itself needs, whichever VMM it uses: the files of the image, the state disk with its lock, and the vm.Machine of a spec.
|
Package machine prepares on the host what a backend that boots the kernel of aibox itself needs, whichever VMM it uses: the files of the image, the state disk with its lock, and the vm.Machine of a spec. |
|
project
Package project manages the folders aibox keeps for each project.
|
Package project manages the folders aibox keeps for each project. |
|
proxy
Package proxy forwards connections to the internet with HTTP CONNECT.
|
Package proxy forwards connections to the internet with HTTP CONNECT. |
|
sandbox
Package sandbox builds the bubblewrap command line that runs QEMU with nothing of the host but its own program, its libraries and firmware, the kernel, and the files it inherits.
|
Package sandbox builds the bubblewrap command line that runs QEMU with nothing of the host but its own program, its libraries and firmware, the kernel, and the files it inherits. |
|
seatbelt
Package seatbelt takes from the aibox process on macOS what it no longer needs once the VM runs, as confine does with Landlock on Linux: the file system but for the resolver files, TCP but for connecting to the allowed ports, and starting programs.
|
Package seatbelt takes from the aibox process on macOS what it no longer needs once the VM runs, as confine does with Landlock on Linux: the file system but for the resolver files, TCP but for connecting to the allowed ports, and starting programs. |
|
session
Package session carries a session between the host and the VM over SSH, on a terminal or without one.
|
Package session carries a session between the host and the VM over SSH, on a terminal or without one. |
|
task
Package task is what the host and the VM agree on for a task that runs unattended: the files the host gives it and the results it gives back.
|
Package task is what the host and the VM agree on for a task that runs unattended: the files the host gives it and the results it gives back. |
|
tunnel
Package tunnel accepts connections and joins pairs of them.
|
Package tunnel accepts connections and joins pairs of them. |
|
version
Package version reports the version of the aibox binary.
|
Package version reports the version of the aibox binary. |
|
vm
Package vm builds the command lines of QEMU and virtiofsd for the aibox VM.
|
Package vm builds the command lines of QEMU and virtiofsd for the aibox VM. |
|
vsockns
Package vsockns gives a VM a vsock namespace of its own: a network namespace in local mode, where the guest CID is private, so every VM can have the same one, and where only aibox has sockets.
|
Package vsockns gives a VM a vsock namespace of its own: a network namespace in local mode, where the guest CID is private, so every VM can have the same one, and where only aibox has sockets. |
|
vzlaunch
Package vzlaunch runs the aibox VM with Virtualization.framework of macOS, as launch runs it with QEMU on Linux: aibox owns the VM, the shares are virtiofs, the state disk is a block device and the terminal and the proxy are on vsock ports only aibox can reach.
|
Package vzlaunch runs the aibox VM with Virtualization.framework of macOS, as launch runs it with QEMU on Linux: aibox owns the VM, the shares are virtiofs, the state disk is a block device and the terminal and the proxy are on vsock ports only aibox can reach. |