Run multiple agents in parallel, with a single command, on your PC, self-hosted, or in the cloud

Works with iterm2 - cmux - tmux - Herdr

How it works

agentbox claude # launch a new VM with claude and your project inside

• 📦 Teleport - Move your project to a dedicated VM, local or in the cloud, with a single command.
• 🤖 Automatic - Bring all your skills, plugins, and settings for Claude Code, Codex, Open Code
• 🌐 A full Computer — Dedicated browser, screen sharing, persistent shells and warmed up VS Code / Cursor IDE, with each box.
• 💾 Checkpoints — Sub <1s startup of new boxes from a previous checkpoint, auto pause to save cost/resources when not in use.
• 🔒 Safe - Your git credentials are kept on your local machine, with permission requests to push to the remote repository.

Full Documentation

Complete setup:

npm -g install @madarco/agentbox
agentbox install

# Launch a new VM with claude, copy all your settings and workspace
agentbox claude

# Also install required project libraries and launch your dev server
> Run setup wizard? -> Yes

# Also use a cloud:
agentbox hetzner claude # or vercel, daytona

# Ctrl+a d to detach, claude keep going, to reconnect later:
agentbox attach 1

# To open a persistent shell inside the box:
agentbox shell 1

# Create a second box:
agentbox claude
agentbox attach 2
agentbox shell 2

# Open your web project on a .local url tunnel on your pc
agentbox url 2
# Or the in-box browser via webVNC:
agentbox screen 2
# Or connect to vscode/cursor inside the box:
agentbox code 2

# See status and quickly switch between agents:
agentbox dashboard

Demo

Install

npm -g install @madarco/agentbox

Requirements: macOS (arm64 or Intel) or Linux, Docker (Docker Desktop or OrbStack), Node >=20.10. The first agentbox create / agentbox claude builds the agentbox/box:dev image (~1 GB, one-time). Uses portless to give box web apps the same URL from inside the box and on the host.

Cloud Providers

Cloud setup (optional — skip for local Docker)

• agentbox install — interactive setup wizard to choose which providers to use and configure them.
• agentbox vercel login — interactive Vercel Sandbox token setup, saved to ~/.agentbox/secrets.env
• agentbox hetzner login — interactive Hetzner Cloud token setup, saved to ~/.agentbox/secrets.env
• agentbox daytona login — interactive Daytona API key setup, saved to ~/.agentbox/secrets.env
• agentbox e2b login — interactive E2B API key setup, saved to ~/.agentbox/secrets.env
• agentbox prepare [--provider daytona|hetzner|vercel|e2b] — build the image and initial snapshot (e2b builds from a Dockerfile via Template.build())
• agentbox hetzner claude, agentbox hetzner codex, agentbox hetzner create, etc.

How to use

<box> is optional almost everywhere — it defaults to the box for the current project, or use its short index (1, 2, …), name, or id prefix.

Create & run

• agentbox create — Create and start a new agent box (Docker container with FUSE overlay)
• agentbox claude — Create a sandboxed box and launch Claude Code in a detachable tmux session

Access

• agentbox url — Open a box's web app URL in the browser (even with no expose: service)
• agentbox screen — Open a box's VNC (noVNC) viewer in the browser
• agentbox code — Open a box in VS Code or Cursor via the Dev Containers extension
• agentbox shell — Open an interactive bash shell in a box
• agentbox open — Open a box's merged workspace in Finder
• agentbox logs — Print recent log lines from a box service; -f to stream
• agentbox dashboard — Box list + the selected box's live agent session

Inspect

• agentbox list (ls) — List boxes in current project or -g for all
• agentbox status — Show service + task status from a box's agentbox-ctl daemon
• agentbox top — Live resource monitor (cpu/mem/pids/disk) for a box, project, or all boxes

Lifecycle

• agentbox start — Start a stopped box (docker start + re-mount the FUSE overlay)
• agentbox stop — Stop a box (preserves the upper volume, node_modules included)
• agentbox destroy (rm) — Destroy a box and discard its upper volume
• agentbox pause / agentbox unpause — Freeze / resume a box (sub-second)

Sync & state

• agentbox download — Download a box's /workspace back into your host workspace (gitignore-aware)
• agentbox cp <src> [dst] — Copy individual files between host and box (like docker cp; direction picked by name: prefix)
• agentbox checkpoint (alias checkpoints) — List and manage project checkpoints (warm box state to start new boxes from); bare command lists, checkpoint create captures

Advanced

• agentbox wait — Block until the box reports all autostart units ready
• agentbox prune — Clean up orphan state records (and with --all, orphan docker resources)
• agentbox self-update — Update agentbox, wipe the box image so it rebuilds, reload the relay
• agentbox config — Read / write layered config (global, per-project, workspace defaults:)
• agentbox relay — Manage the host relay process (status / stop / start / restart)

Run agentbox <command> --help for command-specific options.

Documentation

Full documentation lives at agent-box.sh/docs:

• Quickstart and Core concepts
• Teleport a project, Run an agent, Access your box
• Configuration, Services & tasks, Sync & git
• Cloud providers: Hetzner, Daytona, Vercel, E2B
• Full CLI reference

Development

git clone https://github.com/madarco/agentbox && cd agentbox
pnpm install && pnpm build
node apps/cli/dist/index.js --help

The full development workflow, stack, end-to-end smoke tests, and teardown live in docs/development.md.

Author

Marco D'Alia - @madarco - Linkedin

License

MIT. See LICENSE.