agentbox github ↗
npm @madarco/agentbox license MIT envs Local Docker · Vercel · Hetzner · Daytona os macOS · Linux
// self-hosted agent sandboxes

One command teleport
for agents, in parallel.

Move your project into a dedicated VM — local or in the cloud — and launch Claude Code, Codex, or Open Code inside it. Each box is isolated, checkpointed, and runs on hardware you control.

$ npx @madarco/agentbox claudecodexopencode
full install instructions
01

Orchestrate agents in loops

live

The best builders don't babysit one agent — they run many in a loop.
With the AgentBox skill, your agent spawns subagents in isolated VMs and drives them: waits on their input, reads back plan questions, answers, hands over prompts and commands, and polls status. Full git control per box: switch branch, pull, push, open a PR directly from the host. Also with Notion and Linear integration.

Orchestrator claude / codex
box-2feat/auth
queued
box-3feat/api
queued
box-4fix/cache
queued
+
git control ⎇ branch ↓ pull ↑ push ⎇ PR Notion Linear
02

Your whole setup, baked in

docker · sandbox

Standing up a remote dev box — and keeping it alive — is the tedious part.
AgentBox does it for you. It carries your shell & editor settings, your Claude Code and Codex auth, and your skills and plugins, then provisions the machine end-to-end: Linux packages installed, Docker services up and running, your project bootstrapped and ready. Agentbox.yaml for repetible runs.

agentbox create local · docker-in-docker
ready to provision
03

Like it never left your laptop

full machine

Connecting to a remote box usually means a stripped-down SSH session.
AgentBox gives you the whole machine: a live browser you can screen-share into, a local web tunnel so previews open at your-app.localhost, and a full VS Code / Cursor running inside the box that your local editor attaches to — indistinguishable from local. Plus direct integration with your IDEs and terminals like cmux or Herdr.

webVNC · box-1 :5900● live
box-1 · ubuntudrag the windows ↔
‹ › shop.localhost
‹ › localhost:5173/admin
shop.localhosttunnel
shop — Dev Containers: box-1
srcapp.tsroutes.tsdb.tsDockerfile
// box-1 · the same files as your laptop
import { db } from './db'
export async function checkout(cart) {
const order = await db.insert(cart)
return { id: order.id }
}
SSH: box-1 · port 5173 forwarded
cmux · box-1
1:claude2:codex3:shell4:logs
$ agentbox shell 1
↳ attaching to box-1 · iTerm
user@box-1:~/workspace$ npm run dev
➜ Local: http://shop.localhost
user@box-1:~/workspace$
native hooks iTerm Herd cmux VS Code Cursor + more
04

How it works

Teleport

Move your project to a dedicated VM — local or in the cloud — with a single command.

Automatic

Brings all your skills, plugins, and settings for Claude Code, Codex, and Open Code.

Full computer

Dedicated browser, screen sharing, persistent shells and a warmed-up VS Code / Cursor IDE in every box.

Checkpoints

Sub-1s startup from a previous checkpoint. Auto-pause to save cost and resources when idle.

Safe

Git credentials stay on your local machine. Pushing to a remote always goes through an explicit permission request.

05

The CLI

create & run
agentbox createCreate and start a new agent box.
agentbox claudeCreate a sandboxed box and launch Claude Code in a detachable tmux session.
agentbox <provider> claudeLaunch sandboxed boxes on Vercel, Hetzner, Daytona or local Docker.
agentbox <provider> codexSame, for Codex and Open Code — any agent, any provider.
agentbox attach 2Reattach to the running agent session on box 2 (claude, codex, or opencode — whichever is live).
access
agentbox urlOpen a box's web app URL in the browser.
agentbox screenOpen a box's VNC (noVNC) viewer.
agentbox codeOpen a box in VS Code or Cursor via Dev Containers.
agentbox shellOpen an interactive bash shell in a box.
agentbox dashboardBox list plus the selected box's live agent session.
lifecycle
start / stopStart or stop a box, preserving its upper volume.
pause / unpauseFreeze or resume a box — sub-second.
destroyDestroy a box and discard its upper volume.
checkpointList and manage warm box-state checkpoints.
orchestrate
agentbox queueQueue new agents to start automatically as running boxes go idle.
agentbox agent wait-forBlock until an agent is idle, input-needed or plan-ready.
agentbox agent get-planRead an interactive session's plan questions as data — no screen scraping.
agentbox drive promptDrive y/N answers, or type straight into any CLI agent's prompt.
06

Providers

local or remote
capabilitylocal dockerhetznerdaytonavercel
supportfullfullpartialfull
base imageDockerfilesetup script (Ubuntu)Dockerfilesetup script
live snapshotsyesyesexperimentalyes
private preview urlsportless · orbstackportlessnativenative
07

Security architecture

interactive
actions
Host your machine
HTTP tunnels.localhost · portless
teleport ▸
VM Box isolated
/workspaceawaiting sync…synced · two-way
~/.claudeawaiting inject…injected · sessions
Code
VS Code / Cursor
Browser
Chromium
webVNC
live screen
Docker-in-Docker
DB
Services
// click workspace or .claude on the host to teleport it into the box — or hit the teleport ▸ arrow to send everything
08

Install

$ npm -g i @madarco/agentbox && agentbox install

The first agentbox create builds the agentbox/box:dev image (~1 GB, one-time). Uses portless to give box web apps the same URL inside the box and on the host.

requirements

  • macOS or Linux — arm64 or Intel
  • Docker — Desktop or OrbStack
  • Node >=20.10