E2B

Run your agents in a fast E2B cloud sandbox with a public HTTPS preview URL and free pause/resume — no local Docker needed. Each box is a remote E2B sandbox you drive with the same agentbox commands as a local box. It runs on Firecracker, so there's no Docker-in-Docker and the Hobby tier caps sessions at one hour — but it's the only provider that builds its base straight from a Dockerfile.

Switch per box with --provider e2b, or pin it project-wide with box.provider: e2b in agentbox.yaml. Comparing options? See local-docker, hetzner, daytona, and vercel.

Set up

The easiest path is the interactive wizard — it signs you in and bakes the base image in one flow:

agentbox install        # then select e2b

Paste an E2B_API_KEY (mint at e2b.dev/dashboard) when prompted. Credentials persist to ~/.agentbox/secrets.env; project .env files are never harvested. install also bakes the base template (a one-time agentbox prepare --provider e2b under the hood) with the AgentBox runtime — agentbox-ctl, the agents, tmux — so every new box boots ready in seconds.

For CI or scripted setup, run the explicit equivalents:

agentbox e2b login                 # credentials only
agentbox prepare --provider e2b    # bake the base template

See environment for where the E2B_API_KEY and ~/.agentbox/secrets.env live.

Use it

agentbox e2b claude

agentbox e2b create|claude|codex|opencode is sugar for the same command with --provider e2b.

Prepare the base template (Dockerfile → Template.build())

agentbox prepare --provider e2b drives a TypeScript-described Template.build() that includes everything the box needs (agentbox-ctl, the vscode user, Claude / Codex / OpenCode, tmux, VNC). The resulting templateId:tag is recorded under the per-provider key box.imageE2b and to ~/.agentbox/e2b-prepared.json; every create --provider e2b boots from it.

agentbox prepare --provider e2b

A repeat prepare reuses the existing template unless you pass --force. The bake takes a couple of minutes the first time; subsequent layer-cached builds are faster. See CLI commands for all flags.

When you upgrade AgentBox, create --provider e2b notices if the new install would bake a different runtime (the comparison is checksum-based on the baked files — CLI version strings on their own don't count) and offers to rebuild the template inline; with -y or non-TTY it instead prints a loud warning and boots on the existing template. agentbox e2b login also nudges you toward agentbox prepare --provider e2b on the first successful login, so the login-only path doesn't silently leave you to trip the "no base template" error on create.

Create a box

Once you're logged in and prepared, the flow is standard. The workspace is seeded from a host git bundle plus your stash and untracked files (see teleport-a-project). The box runs as user vscode, and /workspace is checked out on branch agentbox/<box-name>.

agentbox create --provider e2b

# sugar: argv-prefix rewrite equivalent to --provider e2b
agentbox e2b claude

agentbox e2b create|claude|codex|opencode all map to the same provider. From there, run an agent and access your box as usual.

Limits

Pause / resume

E2B sandboxes pause via Sandbox.pause(id) and auto-resume on the next Sandbox.connect(id) op. The provider's state/get use the non-resuming Sandbox.getInfo() so existence checks don't wake (and bill) a paused sandbox. agentbox list and agentbox url are both resume-free — previewUrl constructs the public hostname locally rather than going through Sandbox.connect.

agentbox pause <box>
agentbox start <box>

The public *.e2b.app URL stays stable across a stop/start. destroy calls Sandbox.kill() and tears the sandbox down.

Checkpoints

Cloud checkpoints map to E2B snapshots — Sandbox.createSnapshot(sandboxId, { name }) returns an id-addressed reusable template (same shape as Vercel). agentbox checkpoint create captures it; agentbox create --checkpoint <name> boots from it with /workspace intact and skips workspace seeding. Pair checkpoint create with box.defaultCheckpointE2b so repeat creates boot from your project-ready snapshot.

agentbox checkpoint create --name setup
agentbox create --provider e2b --checkpoint setup

Maintenance

agentbox prune --provider e2b lists every E2B sandbox the configured E2B_API_KEY can see, cross-references against this CLI's local state.json, and offers to delete sandboxes you no longer track (typically left behind by an interrupted create). The orphan set is restricted to sandboxes that carry the agentbox marker tag, so manually-provisioned E2B sandboxes are never touched.

agentbox prune --provider e2b --dry-run
agentbox prune --provider e2b -y

agentbox doctor --provider e2b checks the credential file + the prepared base template.

Specs

Caveats

• No live stats — agentbox top / dashboard render — for cloud boxes, and list reports them optimistically as running.
• Privileged ports are rejected — the WebProxy runs on 8080 (not 80); agentbox url resolves the 8080 domain.
• Push through the relay — use agentbox-ctl git push from a box; the relay holds the credentials. See sync-and-git.
• E2B-only config keys are ignored by other providers — box.imageE2b / box.defaultCheckpointE2b / box.sizeE2b only apply to e2b.
• Template-level resources — vCPU/RAM/disk are baked at Template.build() time; per-create --size overrides are advisory metadata for the dashboard only.
• Templates are not enumerable — the E2B SDK has no Template.list(), so prune --provider e2b covers sandboxes only. Remove built templates from the E2B dashboard if you need to.

Related

• core-concepts — what a box, branch, and worktree are.
• teleport-a-project — how /workspace is seeded.
• run-an-agent · access-your-box — work in a cloud box.
• web-apps-and-tunnels — preview URLs, the 8080 WebProxy, expose: ports.
• checkpoints-and-pausing — pause/resume and checkpoints.
• sync-and-git — relay-backed push/pull.
• services-and-tasks — agentbox.yaml services and expose.
• cli · agentbox-yaml · configuration · environment — reference.