<- all tokdocs

AgentBox: Docker Sandboxes for Claude Code, Codex and OpenCode

By , founder of Mavric and Apso

View on TikTok ->

AgentBox is an MIT-licensed CLI that runs Claude Code, Codex or OpenCode inside a sandboxed box, one box per agent run, and boots new boxes from docker commit checkpoints. The core features hold up against the project's docs. The one claim that does not is that the agent "never touches your real system," because the local box bind-mounts your host's .git/ directory and agent commits land in your real repository right away.

A TikTok from @github.signals scrolls the README for madarco/agentbox and repeats its headline bullets. This post covers what the docs say about how it works.

What AgentBox sets up with one command

agentbox claude creates a box and launches Claude Code inside a detachable tmux session. The README describes a box as a Docker container with a FUSE overlay. AgentBox copies your uncommitted work (a git stash plus untracked files) into the box, and /workspace becomes a git worktree on a branch named agentbox/<box-name>.

Each box also gets a browser reachable over noVNC (agentbox screen), a local URL tunnel for web projects (agentbox url), a persistent shell (agentbox shell), and a VS Code or Cursor attachment through the Dev Containers extension (agentbox code).

The supported agents listed in the quickstart are claude, codex, opencode and pi.

How to install AgentBox

Install it from npm with npm -g install @madarco/agentbox. You need macOS on arm64 or Intel, or Linux, plus Docker Desktop or OrbStack and Node 20.10 or newer. According to the docs, the first run builds an agentbox/box:dev image of roughly 1 GB, once.

How fast do AgentBox checkpoints boot?

The README states "Sub <1s startup of new boxes from a previous checkpoint," and the docs say a new box boots from a checkpoint in about a second instead of installing from scratch. That number is the project's own claim and has not been independently measured here.

The mechanism is simple. A checkpoint is a docker commit of the box's writable layer into a project-scoped image, capturing installed dependencies, build output and caches. A new box starts from that image and skips workspace seeding.

The docs also name a limit. The writable layer is captured, and docker-in-docker volumes are not. If your stack runs Postgres as a sidecar container, that database comes back empty, and you need re-seeding logic rather than a restored state.

How AgentBox keeps git credentials off the box

Anything that touches a remote runs on a host relay, a small process on your machine that executes git using your real SSH agent and ~/.gitconfig. SSH keys and tokens never enter the box.

Approval is graded by risk:

  • Pushing to the box's own agentbox/<box-name> branch runs without a prompt.
  • Opening a pull request runs without a prompt.
  • Pushing a branch the agent switched to itself, gh pr merge, gh pr checkout, and any file transfer that leaves the project folder each raise an approval prompt on the host.

This is the strongest part of the design, and the video skips it.

Does AgentBox fully isolate the agent from your system?

No. For the default local provider, the box's /workspace is a worktree against the same .git/ that is bind-mounted from your host. Commits made inside a box land on your machine immediately, on that box's branch. The docs present this as a feature, since tracked work needs no sync.

The isolation boundary also depends on the provider. The local provider is a Docker container that shares your host kernel. The docs reference a Firecracker microVM for the Vercel provider. A container and a microVM are different boundaries, and the README uses the word "VM" throughout without drawing that line.

Running AgentBox in the cloud

The README lists these providers: local Docker, remote Docker over SSH, Hetzner, Daytona, Vercel, E2B and DigitalOcean. Live snapshots are marked experimental for Daytona and supported on the others.

The docs list session caps that override persistent box settings: roughly one hour on E2B and about 45 minutes on Vercel. For long agent sessions those caps matter more than boot speed.

How mature is AgentBox?

The project is young. As of 2026-09-19 the GitHub repository showed 453 stars and 32 forks, and it was created on 2026-05-12. The npm package @madarco/agentbox first published on 2026-05-17, was at version 0.32.1, and recorded 7,448 downloads in the previous 30 days.

Bottom line

AgentBox gives each coding agent its own Docker box, seeds it with your uncommitted work, and keeps git credentials on the host behind a relay with graded approval. Checkpoints are docker commit images, so they skip reinstalls but do not restore sidecar databases. The local provider writes agent commits straight into your repository, so treat it as a separate branch on your machine rather than a sealed sandbox.

Sources

Published September 17, 2026. Based on a TikTok by @github.signals. Full video notes (markdown)