---
title: "AgentBox: Docker Sandboxes for Claude Code, Codex and OpenCode"
date: "2026-09-17"
video_id: "7686377420378606855"
tiktok_url: "https://www.tiktok.com/@github.signals/video/7686377420378606855"
creator: "@github.signals"
category: "AI"
tags: ["agentbox", "claude code", "docker", "coding agents", "sandbox"]
excerpt: "AgentBox runs each coding agent in its own Docker box with checkpoints and host-side git credentials. How it works, what it isolates and where it does not."
---
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

- [madarco/agentbox on GitHub](https://github.com/madarco/agentbox) - the README, provider matrix and command list.
- [@madarco/agentbox on npm](https://www.npmjs.com/package/@madarco/agentbox) - the published package.
- [Quickstart, AgentBox docs](https://agent-box.sh/docs) - install steps, requirements and supported agents.
- [Core concepts, AgentBox docs](https://agent-box.sh/docs/core-concepts) - how a box is seeded and what a box is per provider.
- [Sync & git, AgentBox docs](https://agent-box.sh/docs/sync-and-git) - the per-box branch, host relay and approval prompts.
- [Checkpoints and pausing, AgentBox docs](https://agent-box.sh/docs/checkpoints-and-pausing) - what a checkpoint captures and excludes.


## Video description and verification notes

**AgentBox is a real MIT-licensed CLI that puts Claude Code, Codex, or OpenCode inside a sandboxed box per agent run, and its checkpoint system is `docker commit` under the hood.** The video scrolls the GitHub README for `madarco/agentbox` and repeats the headline bullets, which check out. The part that does not survive verification is the closing line about code that "never touches your real system," because the box bind-mounts your host's `.git/` directory and agent commits land in your real repository right away. Everything else in the 36 seconds is accurate, if thin on the parts that matter when you actually run it.

## What one command sets up

`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, and the docs describe the seeding step precisely: AgentBox copies your uncommitted work, meaning 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`). Requirements are modest: macOS on arm64 or Intel, or Linux, plus Docker Desktop or OrbStack and Node 20.10 or newer. The first run builds an `agentbox/box:dev` image of roughly 1 GB, once.

## The checkpoint speed claim, and where it comes from

The video calls the checkpoint system the standout feature and says a warm snapshot boots in under a second. 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. I could not benchmark this, so treat the number as the project's claim rather than a measured result.

The mechanism is documented and mundane, which is a point in its favor. 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 entirely. The docs also name the limit the video does not: 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 marker.

## The credential handling is the strongest part, and it has a name

The video says credentials stay safe on the host while agents work freely. The docs back this with a specific design. 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.

The approval model is graded rather than all-or-nothing. Pushing to the box's own `agentbox/<box-name>` branch and opening a pull request run without prompting. Pushing a branch the agent switched to itself, `gh pr merge`, `gh pr checkout`, and any file transfer that escapes the project folder each raise a host-side approval prompt. That is a more useful threat model than per-command approval, and the video skips it.

## The isolation claim is oversold in one specific way

The transcript ends with "a sandbox that never touches your real system." The docs contradict this directly for the local provider. The box's `/workspace` is a worktree against the same `.git/` that is bind-mounted from your host, so commits made inside a box land on your machine immediately, on that box's branch. Tracked work needs no sync because it is already in your repository. That is a deliberate feature, and it is also the opposite of untouched.

The isolation boundary also varies by provider, which neither the video nor the README badge art makes clear. The default local provider is a Docker container sharing your host kernel. The docs reference a Firecracker microVM for the Vercel provider. A container and a microVM are not equivalent boundaries, and the README's use of the word "VM" throughout papers over that difference.

## What the video omits about running this in the cloud

The README provider matrix lists local Docker, remote Docker over SSH, Hetzner, Daytona, Vercel, E2B, and DigitalOcean. Live snapshots are marked experimental for Daytona and supported elsewhere. The docs add hard session caps that override persistent box settings: roughly one hour on E2B and about 45 minutes on Vercel. For long-running agent sessions those caps matter more than boot speed.

Adoption is early. As of 2026-09-19 the repository shows 453 stars and 32 forks, created on 2026-05-12, with the most recent push that same day. The npm package `@madarco/agentbox` first published on 2026-05-17, is at version 0.32.1, and recorded 7,448 downloads in the last 30 days. The frame captured in the video shows 402 stars, so the count moved by about 50 in the two days since upload.

## Key Takeaways

- `agentbox claude` starts a Docker box with Claude Code in tmux, copies your uncommitted work in, and gives the box its own browser, shell, tunnel, and IDE attachment.
- Checkpoints are `docker commit` snapshots of the writable layer, which is why new boxes start warm. Docker-in-docker volumes are excluded, so sidecar databases come back empty.
- Credentials stay on the host through a relay process that runs git with your real SSH agent. Pushing to the box's own branch is unprompted, and anything reaching further asks for approval.
- The video's "never touches your real system" line is wrong for the local provider, because the host `.git/` is bind-mounted and agent commits land in your repository on an `agentbox/<box-name>` branch.
- The sub-one-second checkpoint boot is unverified here. It is the project's own claim in the README and docs, and I did not measure it. The same applies to the ~1 GB image size and the E2B and Vercel session caps, which come from the documentation rather than a test run.
- E2B and Vercel cap sessions at roughly one hour and 45 minutes, which constrains long agent runs regardless of how fast a box boots.
- The project is young: created May 2026, version 0.32.1, 453 GitHub stars, 7,448 npm downloads in the last month.

## Resources

- [madarco/agentbox on GitHub](https://github.com/madarco/agentbox) -- the MIT-licensed TypeScript CLI shown in the video, with the README, provider matrix, and full command list.
- [@madarco/agentbox on npm](https://www.npmjs.com/package/@madarco/agentbox) -- the published package, currently 0.32.1, installed with `npm -g install @madarco/agentbox`.
- [AgentBox Quickstart](https://agent-box.sh/docs) -- install steps, requirements, first-run behavior, and the supported agents (`claude`, `codex`, `opencode`, `pi`).
- [AgentBox Core concepts](https://agent-box.sh/docs/core-concepts) -- how a box seeds from your working state and what a box is per provider.
- [AgentBox Sync & git](https://agent-box.sh/docs/sync-and-git) -- the per-box branch, the host relay, and the graded approval prompts.
- [AgentBox Checkpoints & pausing](https://agent-box.sh/docs/checkpoints-and-pausing) -- what a checkpoint captures, what it excludes, and how auto-pause works.
