Introduction

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 run starts Claude Code in your project folder, like you would on your machine. Changes show up in the folder right away. See Running Claude Code.
• aibox task hands 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. See Tasks.

You can also mount other folders into the VM, read-only.

With aibox run, the VM connects to your machine like this:

%%{init: {"flowchart": {"nodeSpacing": 60}}}%%
flowchart LR
  subgraph vm["VM"]
    claude["<br><br>Claude Code<br><br>"]
  end
  subgraph machine["Your machine"]
    terminal["Your terminal"]
    project["Project folder"]
    mounts["Mounts and skills"]
    subgraph aibox["aibox"]
      proxy["Proxy"]
      broker["Git broker"]
    end
  end
  hosts["Hosts on the allow list"]
  repos["Repositories on the git list"]

  claude <-->|"SSH over vsock"| terminal
  claude <-->|"virtio-fs, 9p on Windows"| project
  claude ---|"the same, read-only"| mounts
  claude <-->|"vsock"| proxy
  proxy ---> hosts
  proxy --> broker
  broker -->|"your git login"| repos

The VM has no network card. vsock connects it to your terminal and to a proxy in aibox. On a Linux kernel without vsock namespaces, a serial port does that. Apart from that, it only shares folders with your machine. With git in the config, a broker adds your git login to the VM’s git requests, so the login never enters the VM.

aibox runs on Linux with QEMU, on macOS with Virtualization.framework and on Windows with Hyper-V. The VM boots in about a second.

Why a VM

There are other ways to fence in Claude Code. Here is why aibox uses a VM instead.

Claude Code has a sandbox of its own. It’s quick to turn on and good for cutting down on permission prompts. But it only covers shell commands. Claude Code’s file tools, MCP servers and hooks still run directly on your machine. Anthropic’s sandbox runtime wraps the whole process, but it still shares your kernel, and you configure the paths and hosts yourself.

A Docker container, like Anthropic’s dev container, puts the whole process in a box. But containers share the kernel with your machine, so a kernel bug is a way out. The dev container’s firewall runs inside the same container as Claude Code, and it allows the IP addresses it looked up when the container started. On a Mac, Docker Desktop runs all containers in one shared Linux VM.

A VM has its own kernel, so a kernel bug alone is not enough to get out. Something has to break the hypervisor or the programs that serve the VM. aibox keeps that VM small: no network card, no kernel modules, and a proxy on your machine as its only way to the network. It also locks down the programs that run the VM on your machine.

Apple’s container tool also runs each container in its own VM. But aibox can’t lock down its runtime, and with it aibox would have to reach the VM through a socket that other programs of yours could reach too. So on macOS aibox runs the VM with Virtualization.framework itself, like it runs QEMU on Linux.

Docker Sandboxes is the closest to aibox. It also runs agents in a microVM, with a proxy that only lets allowed hosts through and keeps API keys on your machine. You need to sign in to Docker to use it. aibox needs no account, and it has a git broker that only lets pushes through to the branches you name.

What aibox does not do

aibox keeps Claude Code away from the rest of your machine. It does not check what Claude Code does with the things you give it. With aibox run the VM can change anything in your project folder, .git included, and a task can use every host and secret you allow it. Read What the VM writes, Security and the Threat model to see where the limits are.