AgentBox: parallel coding agents in disposable VMs, one command per box

The problem AgentBox targets: one checkout, many agents

Running a single coding agent in your working directory is easy. Running three of them is not. Two agents editing the same files, a dev server holding a port, and a package install mutating node_modules produce conflicts that have nothing to do with the models. AgentBox takes the opposite approach: each agent gets its own VM, its own copy of the project, and its own browser, shell and IDE session. The README frames this as "Teleport", moving the project to a dedicated VM with a single command.

The audience is developers who already use Claude Code, Codex or Open Code and want to fan out. The README lists automatic transfer of "all your skills, plugins, and settings" for those three tools, which suggests the intended user has an existing configuration worth carrying over rather than a blank machine. It is not a hosted service: the boxes run on your own Docker, on a machine you own over SSH, or on a cloud provider you supply a token for.

How a box is built: Docker, a FUSE overlay and a ctl daemon

The mechanism visible in the README is a Docker container with a FUSE overlay. `agentbox create` is described as creating "a Docker container with FUSE overlay", and `agentbox start` as "docker start + re-mount the FUSE overlay". That overlay is what lets the box present a merged workspace while keeping writes in an upper layer, which is also why `agentbox stop` can preserve "the upper volume, node_modules included" and why `agentbox destroy` discards that volume.

Inside the box, an `agentbox-ctl` daemon reports service and task status, which is what `agentbox status` reads and what `agentbox wait` blocks on until "all autostart units ready". Networking is handled by `portless`, which the README says gives box web apps "the same URL from inside the box and on the host". The cloud table shows this is not universal: private preview URLs come from portless or OrbStack locally, portless over SSH for remote Docker, and native URLs on Daytona, Vercel and E2B. Daytona is marked partial support with experimental live snapshots, so the abstraction is thinner there than the single CLI suggests.

Installing AgentBox and launching a first box

AgentBox ships on npm as `@madarco/agentbox`. The README's install section gives one global install command, and the requirements are macOS (arm64 or Intel) or Linux, Docker (Docker Desktop or OrbStack), and Node `>=20.10`.

npm -g install @madarco/agentbox
agentbox install

The second command is the interactive setup wizard, which is also where you choose cloud providers if you want them. For a purely local first run you can skip provider configuration. The first `agentbox create` or `agentbox claude` builds the `agentbox/box:dev` image, which the README puts at roughly 1 GB and describes as a one-time cost.

agentbox claude

This creates a sandboxed box and launches Claude Code inside a detachable tmux session. The README shows an optional setup wizard prompt during launch, asking whether to install required project libraries and start your dev server. Detaching with `Ctrl+a d` leaves the agent running; `agentbox attach 1` reconnects to the first box.

agentbox shell 1
agentbox url 2

`agentbox shell` opens a persistent bash shell inside the box, and `agentbox url` opens a box's web app URL in your browser, which the README notes works "even with no `expose:` service". Boxes are addressed by short index, name, or id prefix, and the argument is optional almost everywhere, defaulting to the box for the current project.

Checkpoints, pause and the cost of treating boxes as disposable

The feature that changes how you use the tool is checkpoints. The README describes "Sub <1s startup of new boxes from a previous checkpoint" and says boxes "auto pause to save cost/resources when not in use". `agentbox checkpoint` lists and manages project checkpoints, and `checkpoint create` captures the current state as warm box state to start new boxes from. `agentbox pause` and `agentbox unpause` are described as freeze and resume, sub-second.

That combination is the real argument for the project. If starting a second agent costs a checkpoint restore rather than a full image build plus dependency install, then spinning up a box per task stops being wasteful. The trade-off is state management: you now have boxes, checkpoints, upper volumes and a host workspace that can drift apart. The CLI acknowledges this with `agentbox download`, which pulls a box's `/workspace` back into your host workspace and is described as gitignore-aware, plus `agentbox prune` for orphan state records and, with `--all`, orphan docker resources. If you never run `download` or `cp`, the work stays in the box.

Credential handling, and what the README does not promise

The README's safety claim is narrow and specific: "Your git credentials are kept on your local machine, with permission requests to push to the remote repository." That is a meaningful boundary. The agent runs in a VM with your project, but pushing to a remote goes through a permission step rather than handing the box your git credentials.

What the documentation does not cover is equally worth noting. The README does not document rollback for a checkpoint, so it is unclear whether `checkpoint create` gives you a restore point you can return to or only a template for new boxes. It does not describe how cloud provider tokens stored in `~/.agentbox/secrets.env` are protected beyond being written there, and it does not state a retention policy for boxes you forget to destroy. Resource usage is observable through `agentbox top`, which shows cpu, mem, pids and disk for a box, project, or all boxes, but the README does not give guidance on how many boxes a laptop can carry. Those gaps matter more than the feature list when you decide how many agents to run at once.

Where AgentBox is the wrong tool

If you develop on Windows, AgentBox is out: the README lists macOS and Linux only. If you cannot run Docker Desktop or OrbStack, there is no path, because local execution is a Docker container with a FUSE overlay.

The second mismatch is scale of need. AgentBox adds a VM, an image build, a daemon, a relay and a checkpoint store to solve a concurrency problem. For one agent working on one branch, that is infrastructure you have to maintain for no benefit, and the roughly 1 GB image build is pure overhead. The third is the cloud table: Daytona is marked partial with experimental snapshots, so if Daytona is your provider of choice, the consistency the CLI advertises across backends does not hold there.

A simpler alternative is the plain terminal: run your agent directly in your project, and use git worktrees plus separate shells when you need two agents at once. Worktrees give each agent its own checkout with no VM, no image, and no daemon, and they cost nothing to start. What they do not give you is a browser, a VNC screen, a persistent shell, or a disposable filesystem that cannot damage your host. That is the actual difference in approach: AgentBox buys isolation and a full computer per agent, and pays for it in build time, disk, and a state layer you have to keep tidy.

Maintenance, licence and the upgrade path

The repository is not archived, and the last push was on 2026-08-26. Releases are split into two channels: `tray-latest` carrying AgentBox 0.1.15, and `tray-nightly` carrying 0.1.15-nightly.202608202107. The README documents the nightly channel explicitly: installing `@madarco/agentbox@nightly` puts you on pre-release builds "with stable releases still reaching you automatically", and `agentbox self-update --channel stable` opts back out. That is a clean escape hatch, and it is the main reason the nightly channel is not a trap.

Upgrade cost is concentrated in `agentbox self-update`, which the README says updates agentbox, wipes the box image so it rebuilds, and reloads the relay. Wiping the image means the next box pays the build again, so upgrades are not free even though the command is one word. The project is MIT licensed, which permits commercial use and modification; the repository includes a LICENSE file at the root. This is a description of the licence terms, not legal advice, and you should read the LICENSE file yourself if your organisation has specific requirements.

Editorial conclusion

Adopt AgentBox if you want several coding agents running at once without them touching your host checkout, and you already run Docker Desktop or OrbStack on macOS or Linux with Node 20.10 or newer. Skip it if you work on Windows, if you cannot spare roughly a gigabyte for the agentbox/box:dev image, or if a single agent in your current terminal is enough. Before committing, verify that agentbox install completes the provider wizard you need, that agentbox claude builds the image on your machine, and that agentbox download brings a box's /workspace back into your host workspace the way you expect.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes