README
¶
aibox
Let Claude Code work on your project without giving it your whole computer.
aibox runs Claude Code in a small virtual machine that only sees the folders you share and only reaches the hosts you allow. The VM has its own kernel and no network card. Its only way to the network is a proxy on your machine that checks every connection. It boots in about a second.
Claude Code can read and change files, run commands and access the internet. That's what makes it useful, but a bad prompt or a malicious file in a repository can turn it against you. In aibox, Claude Code can't see your SSH keys, your cloud logins or your other projects, unless you share them. And it can't send anything to a host you didn't allow.
What stays the same
You start Claude Code with aibox run in your project folder, and it works
like it always does. Its changes show up in the folder right away, so you
keep your editor open next to it. You log in with your Claude account like
you would on your machine, and aibox keeps the login.
You can bring your own tools, install more in the VM and run containers with podman. If you turn it on, Claude Code also connects to VS Code or GoLand.
Your keys and logins
Your API key never enters the VM. Claude Code gets a placeholder, and aibox puts in the real key on the way to the Claude API. A subscription token is different. It goes into the VM as it is, because Anthropic's terms don't allow anyone but you to handle it.
Your git login stays on your machine too. If you list repositories in the config, git in the VM can fetch from them and push to the branches you name. aibox refuses pushes to other branches, deletes and tags. It can't stop a force push to a branch you allowed.
The config lives on your machine and never in the project. So a repository you clone can't give itself hosts, secrets or branches, and the VM can't change its own config.
Two ways to use it
aibox runstarts Claude Code in your project folder, and you work with it like you always do.aibox taskhands Claude Code a job to do on its own. It works on a clone of the last commit, or of any branch, tag or commit you name, and you get its commits back to review. The VM is deleted afterwards. You can give it a plan from a file, a timeout and a budget, and run several tasks at once.
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. Why a VM compares aibox with these, Apple's container tool and Docker Sandboxes.
The threat model says who aibox defends you against and where its limits are.
Installing
aibox runs on macOS with Apple silicon, on Linux on amd64 and on Windows 11 Pro, Enterprise and Education on amd64.
On macOS and Linux, install it with Homebrew:
brew install --cask the127/tap/aibox
On Linux, aibox needs Linux 7.0 or newer with vsock, and access to
/dev/kvm. Homebrew installs just the binary, so also install QEMU,
virtiofsd and bubblewrap from your distribution. The deb and rpm on the
releases page pull them in for
you.
On Windows, download aibox.exe from the releases and, as administrator,
run aibox service install once. See
Installing.
With Nix, on Linux on amd64 or macOS on Apple silicon:
nix profile install github:The127/aibox
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.
The first run downloads the VM image, which is about 150 MB, unless your
package ships it. Log in to Claude Code like you would on your machine.
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
Presets like preset:go, preset:npm and preset:github stand for the
hosts a tool needs. proxy.log in the project's folder in
~/.aibox/projects shows each host the proxy connected to or refused.
Note that the VM can change anything in your project folder, .git
included. Treat those changes like a pull request from a stranger.
What the VM writes
explains why and what to look out for.
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. Tasks explains what that means for your config, and 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. |
|
clipboard
Package clipboard lets the VM read an image from the clipboard of the host, once each time the person presses the paste key.
|
Package clipboard lets the VM read an image from the clipboard of the host, once each time the person presses the paste key. |
|
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. |
|
fence
Package fence does the work of aibox in a folder the VM can write in a helper, aibox started again, that the kernel lets write only below one folder.
|
Package fence does the work of aibox in a folder the VM can write in a helper, aibox started again, that the kernel lets write only below one folder. |
|
filelock
Package filelock locks an open file for one process at a time, with the lock of the system: flock on Unix, LockFileEx on Windows.
|
Package filelock locks an open file for one process at a time, with the lock of the system: flock on Unix, LockFileEx on Windows. |
|
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. |
|
hcs
Package hcs talks to the Host Compute Service of Windows, which runs VMs on Hyper-V, through computecore.dll and nothing else: it creates, starts, ends and lists compute systems and grants a VM access to files on the host.
|
Package hcs talks to the Host Compute Service of Windows, which runs VMs on Hyper-V, through computecore.dll and nothing else: it creates, starts, ends and lists compute systems and grants a VM access to files on the host. |
|
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. |
|
hvinstall
Package hvinstall installs and uninstalls the Windows service of aibox, as an Administrator does from an elevated prompt.
|
Package hvinstall installs and uninstalls the Windows service of aibox, as an Administrator does from an elevated prompt. |
|
hvlaunch
Package hvlaunch runs the aibox VM on Hyper-V, through the Windows service of aibox, as launch runs it with QEMU on Linux: aibox serves the shares itself, over 9p on Hyper-V sockets, and the terminal and the proxy are on ports of the VM only aibox can listen on.
|
Package hvlaunch runs the aibox VM on Hyper-V, through the Windows service of aibox, as launch runs it with QEMU on Linux: aibox serves the shares itself, over 9p on Hyper-V sockets, and the terminal and the proxy are on ports of the VM only aibox can listen on. |
|
hvserver
Package hvserver is the Windows service of aibox, which runs as SYSTEM and makes the VMs of the people who run aibox over the pipe of hvservice.
|
Package hvserver is the Windows service of aibox, which runs as SYSTEM and makes the VMs of the people who run aibox over the pipe of hvservice. |
|
hvservice
Package hvservice is for the Windows service of aibox and the protocol aibox talks to it in.
|
Package hvservice is for the Windows service of aibox and the protocol aibox talks to it in. |
|
ide
Package ide finds the IDEs that Claude Code can connect to, from the lock files that their Claude Code plugins write, and links Claude Code in the VM to one of them.
|
Package ide finds the IDEs that Claude Code can connect to, from the lock files that their Claude Code plugins write, and links Claude Code in the VM to one of them. |
|
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. |
|
ninefs
Package ninefs serves folders of a Windows host to a Linux guest over 9P2000.L, as the user who runs it.
|
Package ninefs serves folders of a Windows host to a Linux guest over 9P2000.L, as the user who runs it. |
|
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. |
|
vhd
Package vhd writes the VHDs Hyper-V attaches, as the VHD specification lays them out: it makes a raw disk image a fixed VHD by appending the footer, so that the guest sees the same bytes as before, and makes an empty dynamic VHD, which takes up space as the guest fills it.
|
Package vhd writes the VHDs Hyper-V attaches, as the VHD specification lays them out: it makes a raw disk image a fixed VHD by appending the footer, so that the guest sees the same bytes as before, and makes an empty dynamic VHD, which takes up space as the guest fills it. |
|
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. |