agentbox CLAUDE.md

AgentBox — context for Claude Code

agentbox is an npm CLI that spins up isolated sandboxes ("boxes") for coding agents (Claude Code, Codex, others) to work in, so they can't touch the host. Seven backends share one provider abstraction: Docker (the default — one local container per box, isolated by per-box git branch in an in-container worktree against the bind-mounted host .git/), Daytona Cloud (--provider daytona — a managed remote sandbox seeded from a host git bundle + per-agent credential volumes, reached via SSH-token attach and an in-sandbox bridge relay), Hetzner Cloud (--provider hetzner — a bare VPS per box, pure OpenSSH ControlMaster comms, locked-down Hetzner Cloud Firewall, baked from a one-time agentbox prepare --provider hetzner snapshot), Vercel Sandbox (--provider vercel — a Firecracker microVM per box, persistent snapshots, public HTTPS preview URLs; nested containers (in-box docker) now supported and baked in, no SSH, baked from a one-time agentbox prepare --provider vercel snapshot), E2B Sandbox (--provider e2b — a Firecracker microVM per box, SDK-only comms, public HTTPS preview URLs, persistent pause/resume; uniquely among the cloud providers, E2B builds its base template directly from a Dockerfile via Template.build() — agentbox prepare --provider e2b runs the build), and Remote Docker (--provider remote-docker, spelled agentbox docker:<host> … — one container per box on a machine the user already owns, reached over an OpenSSH ControlMaster and driving that machine's docker engine. Cloud-shaped despite being docker: a bind mount can't cross a network, so the workspace is synced (git clone + carried-over stash/untracked) exactly as for the clouds, while the image (Dockerfile), checkpoints (docker commit) and DinD stay docker-shaped. No credential — it connects as you, over your own ~/.ssh/config).

Architecture overview

• Boxes — one isolated sandbox per agent run. The shape differs by provider but the abstraction is one Provider interface (packages/core/src/provider.ts):
  • docker: container agentbox-<id|name>; /workspace is the in-container git worktree on branch agentbox/<box-name>; host's .git/ is bind-mounted RW so commits land on the host immediately. Boxes pause/unpause for cheap context switching and survive stop/start; destroy wipes the container + per-box volumes. The base image (agentbox/box:dev) is pulled from GHCR on first use (tagged by build-context fingerprint, see pullOrBuild/registryRefForSha in image.ts) and only built locally on a pull miss; --build / box.imageRegistry="" force a local build. See docs/development.md → "Image: pull vs rebuild".
  • daytona (cloud): Daytona sandbox with /workspace seeded from a host git bundle create (incl. stash + untracked carry-over for the user's local state). Lifecycle goes through the Daytona SDK; agent credentials (~/.claude, ~/.codex, ~/.config/opencode) live in shared per-org volumes seeded from the host. Host↔box comms go through a per-box bridge URL (CloudFront preview) that the host relay's CloudBoxPoller long-polls.
  • hetzner (cloud): one Hetzner VPS per box (default cx23 / nbg1). Workspace seeded the same way (git bundle + stash + untracked tar). Per-box ed25519 SSH key minted on the host into ~/.agentbox/boxes/<sandboxId>/ssh/ and injected via cloud-init. Per-box Hetzner Cloud Firewall auto-locked to the host's egress IP (multi-probe fail-loud). All comms (exec, scp, port forwards, attach) flow over one persistent ssh -fNT -M ControlMaster per box; previewUrl(port) mints ssh -O forward on demand. No agent credentials volume — credentials pushed via scp at create time (Hetzner has no shared-volume primitive). agentbox prepare --provider hetzner bakes a one-time base snapshot since Hetzner can't build images from a Dockerfile.
  • vercel (cloud): one Vercel Sandbox (Firecracker microVM, Amazon Linux 2023) per box. Workspace seeded the same way (git bundle + stash + untracked tar). Boots from a Vercel snapshot baked once by agentbox prepare --provider vercel (no Dockerfile build). Persistent sandboxes auto-snapshot on stop and auto-resume on Sandbox.get({ resume: true }) → pause/resume for free. Comms via the SDK: exec runs as vscode (root → sudo -u vscode); previewUrl(port) returns the public sandbox.domain(port) (HTTPS, no token), so the host relay's CloudBoxPoller reaches the in-box bridge directly. In-box docker (DinD) is baked into the base snapshot and dockerd is auto-started on create/resume (launchDockerd:true, via the shared agentbox-dockerd-start) — Vercel Sandbox now supports nested containers. No SSH (attach is a custom attach-helper.js tmux bridge over the SDK). Max 4 exposed ports, region iad1 only.
  • e2b (cloud): one E2B Sandbox (Firecracker microVM, Debian 12) per box. Workspace seeded the same way (git bundle + stash + untracked tar). Key differentiator from Vercel/Hetzner: E2B builds its base image directly from a Dockerfile via the SDK's Template.build() — agentbox prepare --provider e2b drives the build and pins the resulting template id to box.imageE2b. Sandbox.pause/Sandbox.connect (auto-resume) gives free pause/resume; Sandbox.createSnapshot is the reusable, id-addressed checkpoint primitive (same shape as Vercel). Comms via the SDK: exec runs as vscode; previewUrl(port) returns the public {port}-{sandboxId}.e2b.app URL (HTTPS, no token; constructed locally so it doesn't wake a paused sandbox). In-box docker (DinD) is baked into the base template and dockerd auto-starts on create/resume (launchDockerd:true) — E2B microVMs support nested containers (full root + cap_sys_admin, verified 2026-06-23), contrary to the original "same as Vercel" assumption. No SSH — attach is a custom attach-helper.cjs SDK-streaming PTY bridge over pty.create. 1-hour platform session cap on the Hobby tier (the attach helper caps at 55 minutes for headroom).
• In-box supervisor (@agentbox/ctl) — reads /workspace/agentbox.yaml and runs the declared tasks/services under a DAG scheduler. Ships as agentbox-ctl inside every box (docker, daytona, hetzner, vercel, e2b).
• Host relay (@agentbox/relay) — a host node process boxes call for things they have no credentials for (git push, checkpoint capture, cp/download) and to push status events. Keeps SSH keys out of the box. The cloud path drives the same relay via CloudBoxPoller + executeCloudAction.
• Checkpoints — docker commit (+ periodic FROM scratch flatten) for docker; Daytona snapshots (sb._experimental_createSnapshot) for daytona; Hetzner create_image snapshots (no-pause default — matches docker commit) for hetzner; Vercel sb.snapshot() (id-addressed; stores the snapshot id in the cloud-checkpoint manifest) for vercel; E2B Sandbox.createSnapshot (id-addressed template, same shape as Vercel) for e2b. All flow through provider.checkpoint.create. box.defaultCheckpoint is the cross-provider fallback; box.defaultCheckpointDocker / box.defaultCheckpointDaytona / box.defaultCheckpointHetzner / box.defaultCheckpointVercel / box.defaultCheckpointE2b override per provider.
• The full design — file-handling rationale, the checkpoint model, pause/resume strategy, what we explicitly rejected — lives in docs/architecture.md and docs/create-and-checkpoints.md. Each cloud provider's shape and its known caveats live in docs/cloud-providers.md. Read them before making non-trivial changes to the lifecycle code.