Local Docker

Local Docker is the default — no --provider flag needed. agentbox claude and agentbox create use it out of the box. Everything runs on your own machine, so a box is free and instant but only lives while your laptop is on and shares its CPU/RAM.

Each box is one local container. /workspace is an in-container git worktree on branch agentbox/<box-name>, and the host's .git/ is bind-mounted so commits land on the host immediately. It's fast, free, and fully local. It's the docker row of the provider matrix — see core-concepts for the box model, or reach for a cloud alternative with hetzner, daytona, or vercel.

Requirements

• macOS (arm64 or Intel) or Linux.
• A Docker engine: Docker Desktop or OrbStack.
• Node >=20.10.
• First create pulls (or builds) the agentbox/box:dev image, a one-time ~1 GB cost covered below.

Install the CLI and run the setup wizard:

npm -g install @madarco/agentbox
agentbox install

agentbox install is the interactive wizard. Verify your host is ready with agentbox doctor.

Installation basics are also covered in teleport-a-project; override the engine with engine.kind in configuration.

First-run image

On first use the CLI pulls the agentbox/box:dev image from public GHCR (no docker login needed) and retags it locally; only on a pull miss does it build locally. The first box pays the one-time ~1 GB cost — later boxes reuse the cached image and start fast.

# First box pulls (or builds) agentbox/box:dev automatically
agentbox claude

Use --build to force a local build, or set box.imageRegistry to an empty string to always build locally — see configuration for all flags. Cloud providers bake their images differently via agentbox prepare (see cli).

Resource limits

Docker boxes default to unlimited. Cap a box's resources with --memory, --cpus, --disk — see configuration for all keys and defaults.

agentbox create --memory 4g --cpus 2

Watch live per-box usage (cpu/mem/pids/disk) with agentbox top. Cloud sizing uses box.size / --size on hetzner and daytona.

Pause and resume

Inactive boxes are docker paused, not stopped — RAM stays mapped, so docker unpause resumes instantly with no cache rehydration. Switching is sub-second. agentbox stop / agentbox start also work; /workspace survives both.

agentbox pause 1
agentbox unpause 1

Shared docker cache

Each box runs its own in-box dockerd. The --shared-docker-cache flag instead routes all boxes to one shared volume that's preserved on destroy/prune, for faster rebuilds.

agentbox claude --shared-docker-cache

In-box docker details live in docker-in-docker.

Web URLs

agentbox url <box> opens the box's web app at its OrbStack .orb.local, Portless .localhost, or loopback address — see web-apps-and-tunnels for the full URL and expose model.

agentbox url 1

Lifecycle and state

/workspace lives in the container's writable layer (not a volume), so node_modules, .next, target, and .venv all land there. It survives pause and stop, and is wiped on agentbox destroy.

Capture warm state to start future boxes fast with agentbox checkpoint create <box> --set-default. Checkpoint after your setup wizard runs to carry build caches into every new box. See checkpoints-and-pausing.

The bind-mounted host .git/ means commits land on the host immediately; pushes go through the host relay, so no credentials live in the box (see sync-and-git). Inspect a box's files on the host with agentbox open or agentbox download.

Specs