AgentBox: Run Parallel Coding Agents in Isolated VMs with One Command

The Problem: Parallel Agents Need Isolation, Not Just Processes

Running several coding agents at once on one machine leads to file conflicts, environment drift, and resource contention. AgentBox gives each agent an isolated box with its own filesystem, browser, and shell. Locally, a box is a Docker container with a FUSE overlay. The intended user is a developer who wants to run multiple agents against the same project without them stepping on each other, or who wants to offload agents to a cloud machine. The README shows a workflow where you launch one box per agent, attach and detach, and keep them running independently. This is not a tool for a single agent on a single laptop; it is a tool for parallel, isolated execution.

How It Works: FUSE Overlays, Checkpoints, and a Control Daemon

Each box is a Docker container with a FUSE overlay filesystem, which lets the box see your project while keeping changes isolated in an upper layer. The `agentbox create` command builds a container, and `agentbox claude` launches Claude Code inside a detachable tmux session. The container runs an `agentbox-ctl` daemon that reports service and task status, which `agentbox status` reads. Checkpoints capture the box state, and starting a new box from a checkpoint is described as sub-second. The overlay means that `stop` preserves the upper volume, including `node_modules`, while `destroy` discards it. This design lets you freeze a box with `pause` and resume it quickly, saving resources when idle.

Getting Started: Commands and Setup

Installation is a global npm package: `npm -g install @madarco/agentbox`. Then run `agentbox install`, which starts an interactive wizard to configure providers. The first `agentbox create` or `agentbox claude` builds the `agentbox/box:dev` image, about 1 GB, one-time. Requirements are macOS (arm64 or Intel) or Linux, Docker Desktop or OrbStack, and Node >=20.10. To launch a box with Claude, run `agentbox claude`. You can optionally say yes to a setup wizard that installs project libraries and starts a dev server. For cloud, run `agentbox hetzner claude` or `agentbox vercel claude` after logging in with commands like `agentbox hetzner login`. The README also shows `agentbox remote-docker doctor <host>` to run boxes on a machine you already own over SSH, then `agentbox docker:<host> claude`.

Parallel Workflow: Attach, Detach, and Manage Multiple Boxes

The README demonstrates a multi-box workflow: launch `agentbox claude` to create box 1, detach with Ctrl+a d, then launch a second `agentbox claude` to create box 2. You can reattach with `agentbox attach 1` or open a persistent shell with `agentbox shell 1`. The `url` command opens a web app URL on a .local tunnel, and `screen` opens a VNC viewer. This is a real parallel workflow: each box has its own tmux session, so agents keep running while you detach. The `dashboard` command shows a box list and the selected box's live agent session, which helps monitor multiple agents at once. The `top` command gives a live resource monitor per box, project, or all boxes, which is useful when you run many boxes and need to see which one is consuming CPU or memory.

Cloud Providers: A Mixed Bag of Support

AgentBox supports local Docker, remote Docker, Hetzner, Daytona, Vercel, and E2B, but the support levels differ. The table in the README marks Daytona as partial support. Live snapshots are available on local Docker, remote Docker via `docker commit`, Hetzner, Vercel, and E2B, but Daytona's snapshots are experimental. Private preview URLs are available everywhere, but the mechanism differs: portless for local and Hetzner, native for Daytona, Vercel, and E2B. This matters if you need to share a web app running in a box with a colleague or yourself from another device. The setup for each provider is a login command that saves tokens to `~/.agentbox/secrets.env`, which is a single file for all secrets. The remote Docker option is notable because it uses your existing `~/.ssh/config` with no separate token, which is a simpler model for people who already manage SSH hosts.

Limitations and Wrong Use Cases

The most obvious limitation is the Docker requirement. If you do not have Docker Desktop or OrbStack, AgentBox will not run locally. The one-time image build of about 1 GB is a real cost, especially on a slow connection. The tool is early-stage: the latest release is 0.1.15, and there is a nightly channel. That suggests the API and commands may change. Also, the README says git credentials are kept on your local machine with permission requests to push, but it does not explain how that works or whether it covers all git operations. If you need to push to a remote frequently, the permission prompt could become a bottleneck. The tool is also not for people who want a simple single-agent setup; the overhead of creating an isolated box per agent is only justified when you run multiple agents in parallel or need isolation from your host environment.

Alternatives and the Trade-off in Approach

A common alternative is to run agents directly on your host, using tools like tmux or `screen` to manage multiple sessions. That approach has zero VM overhead and no Docker dependency, but it offers no isolation: agents share the same filesystem and can overwrite each other's changes. Another alternative is to use container orchestration like Docker Compose to spin up separate containers per agent, but that requires writing Dockerfiles and managing networking yourself. AgentBox's difference is that it automates the entire workflow: it builds the image, sets up the FUSE overlay, starts tmux, and provides commands for attach, shell, URL, and checkpoint. The trade-off is that you trade setup complexity for a higher-level interface. If you already have a container workflow, AgentBox may feel redundant, but if you want a purpose-built tool for agent isolation, it is a distinct approach.

Maintenance, Upgrades, and License

The project is MIT licensed, which means you can use it freely, including in commercial products, without paying royalties. For maintenance, AgentBox has a `self-update` command that updates the tool, wipes the box image so it rebuilds, and reloads the relay. There is also a `prune` command to clean up orphan state records and, with `--all`, orphan Docker resources. The nightly channel gives you pre-release builds, and you can switch back to stable with `agentbox self-update --channel stable`. The last push was in August 2026, and the project is not archived, so it appears actively maintained. However, the reliance on Docker and cloud provider APIs means that when those dependencies change, AgentBox must adapt, and the nightly channel suggests that breakage is possible. You should expect to run `self-update` periodically and be prepared for occasional image rebuilds.

Editorial conclusion

Adopt AgentBox if you need to run multiple coding agents in parallel without cross-contamination, especially if you already use Docker or want cloud flexibility. Skip it if you prefer a single-agent workflow or cannot tolerate the one-time ~1 GB image build and Docker dependency. Before adopting, verify that your provider (local, Hetzner, Vercel, etc.) supports the live snapshots and private URLs you need, and test that your git credentials stay local as documented. The tool is early-stage (0.1.15) with nightly builds, so check the changelog and test on a non-critical project first.

Frequently asked questions

Official sources

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