CLI commands

This is the command catalog. Conceptual depth lives in the linked task pages — here you get what each command does and the flags worth knowing.

Two conventions that apply everywhere

Box references. Almost every command takes an optional [box] argument: a project index (1, 2, …), the box name, an id (or id prefix), or the container name. Omit it and AgentBox uses the only box in the current project. Paused or stopped boxes are auto-resumed when you act on them.

Provider sugar. agentbox <provider> <subcommand> is rewritten to --provider <provider> before parsing. So agentbox hetzner claude, agentbox vercel codex, agentbox e2b create, and agentbox docker create all work — they're identical to passing --provider.

Create & run

create makes a box but launches no agent. claude, codex, and opencode create (or reuse) a box and launch that agent in a detachable tmux session — they mirror create's entire flag surface, so you can swap the verb without relearning flags. fork teleports the agent session you're running on the host right now into a fresh box.

# Create a box, no agent
agentbox create

# Create a box and launch an agent (tmux, detachable — Ctrl+a d to detach)
agentbox claude
agentbox codex
agentbox opencode

Each agent command has three subcommands: attach reattaches to a running session (never re-syncs config), start (re)starts a session in an existing box (rsyncs host config unless --no-sync-config), and login runs that agent's auth flow.

# Create a box and drop into a shell once it's ready
agentbox create --attach

# Reattach to / restart a session in box 1
agentbox claude attach 1
agentbox claude start 1

# Teleport + resume your most recent host Claude session into the box
agentbox claude -c
agentbox claude --resume <session-id>

# Fork the host session you're in now into a new box (opens a new tab)
agentbox fork
agentbox fork --agent codex --attach-in background

# Anything after -- is forwarded to the in-box agent
agentbox claude -- --model sonnet

Shared create/agent flags include -n, --name, -w, --workspace <path>, --provider <name>, --snapshot <ref> (start from a checkpoint), --image <ref>, --build (build the base image locally instead of pulling), -y, --yes, --with-env, --with-playwright, --no-vnc, --portless / --no-portless, --from-branch <ref>, -b, --use-branch <name>, --memory, --cpus, --disk, --size <spec> (cloud), and --carry-yes / --carry <mode>.

Agent-specific: --attach-in <split|window|tab|same>, -d, --no-attach, -i, --initial-prompt <text> (background queue), and for claude only -c, --continue, --resume <id>, --plan <path>, and --dangerously-skip-permissions (on by default in boxes). fork adds --agent, --session <id>, and --attach-in (default tab).

These commands tee progress to ~/.agentbox/logs/<command>.log; ~/.agentbox/logs/latest.log always points at the most recent run.

See Run an agent, Teleport a project, Background & parallel, and Sync & git.

Access

# Interactive shell in box 1 (tmux session)
agentbox shell 1
agentbox shell 1 -n logs     # a second, named shell
agentbox shell 1 --new

# One-shot command after `--`:
agentbox shell 1 -- ls /workspace               # multi-token: run as a literal argv
agentbox shell 1 -- 'cd web && npm run build'   # single quoted string: run as a shell snippet

# Open the box's web app / desktop / IDE
agentbox url 2
agentbox screen 2
agentbox code 2

# Open /workspace in Finder
agentbox open 2

# Multiplexed box dashboard (TUI)
agentbox dashboard

url opens the box's web app in your browser even with no expose: service. screen opens the in-box desktop over noVNC. code opens the box in VS Code or Cursor via Dev Containers. dashboard shows a box list alongside the selected box's live session.

Add --print to url, screen, or code to print the URL instead of opening it. url/screen accept --loopback (docker: use 127.0.0.1 instead of the OrbStack/Portless URL) and --ttl <seconds> (cloud signed-URL expiry). shell has attach, ls, and kill subcommands.

A one-shot command after -- is run under the box's login shell. A single quoted argument is treated as a shell snippet (so &&, pipes, redirections, and $VAR are interpreted by the box); multiple tokens are passed through verbatim as a literal argv (like docker exec), so quoting and format strings such as curl -w '%{http_code}' reach the command intact — no double-parsing.

See Access your box, Web apps & tunnels, and Browser & screen.

Inspect

# List boxes (this project, then all projects)
agentbox ls
agentbox ls -g

# Service + task status from the box's supervisor
agentbox status 1
agentbox status 1 --inspect

# Live cpu/mem/pids/disk monitor
agentbox top
agentbox top --once

# Tail (and stream) a service log
agentbox logs 1 web
agentbox logs 1 web -f

# Block until the box's autostart units are ready
agentbox wait 1

list (alias ls) lists boxes in the current project; -g spans all projects. status shows live service/task state from the in-box agentbox-ctl daemon, and status --inspect adds detailed box info (volumes, limits, paths). top is a live resource monitor, logs tails a service log, and wait blocks until autostart units are ready.

The agent group is a scripting surface for the agent's live state: agent state, agent wait-for <state>, and agent get-plan-question, all with --json. It also unifies approvals an orchestrator answers on a box's behalf: agent approvals [box] lists everything the box is blocked on — relay host-action confirms (git push, cp, gh PR writes, checkpoint) and the agent's in-TUI prompts (plan approval, question, tool permission) — each with an id, and agent approve <id> (with --option/--deny) answers that exact one. The id is a safety token: a prompt that changed since you listed it is refused, not mis-answered. Pair it with agentbox drive (snapshot the screen / send keystrokes) to drive one agent from another — see Orchestration & queue boxes.

See Services & tasks and Background & parallel.

Lifecycle

# Cheap freeze / resume
agentbox pause 1
agentbox unpause 1

# Full stop / start (volumes preserved)
agentbox stop 1
agentbox start 1

# Destroy (discard the box; alias rm)
agentbox destroy 1
agentbox rm 1 -y

pause/unpause is the cheap context switch (docker freezes the cgroup, sub-second resume; cloud archives and rehydrates, slower). stop/start is a full stop that preserves the upper volume, including node_modules. destroy (alias rm) wipes the box and its writable layer; --keep-snapshot leaves the snapshot dir under ~/.agentbox/snapshots/ in place. If the name/id matches no tracked box but a leftover agentbox-<name> container exists, destroy removes that orphan container directly (then suggests prune -y for any leftover volumes).

See Checkpoints & pausing and the provider pages for cloud pause/stop semantics.

Sync & state

# Pull the box's /workspace back to the host (gitignore-aware)
agentbox download 1
agentbox download 1 --dry-run
agentbox download 1 --with-env

# Copy files/dirs (direction inferred from the box: prefix)
agentbox cp mybox:/workspace/.env      # download to cwd
agentbox cp ./local.txt mybox:/workspace/   # upload
agentbox cp ./dir mybox:/workspace/ --exclude=.git --exclude="*/cache"  # upload, trimmed

# Git/gh through the host relay (your credentials stay on the host)
agentbox git push 1
agentbox git fetch 1
agentbox git pull 1 main --ff-only
agentbox git checkout 1 feature-x
agentbox git status 1
agentbox git pr create 1

download pulls /workspace back into your host workspace, honouring .gitignore. It has typed subcommands for agent state: download env, download claude, download codex, download opencode, download config. cp copies files or directories in either direction, like docker cp. git runs git/gh operations against the box from the host through the relay, so push and fetch use your host credentials and the box never sees them.

cp drops heavy, regenerable directories by default (.git, node_modules, bin, obj, packages, dist, .next, target) — keep them with --no-default-excludes, or add more with repeatable --exclude=<glob|name>. An upload whose size (after excludes) exceeds box.cpMaxBytes (default 100 MB) is blocked and prints a du-style tree of the biggest remaining folders so you can decide what to drop; trim it with --exclude, copy the heavy folders one at a time, or pass --yes to copy it all anyway.

Useful flags: download takes --dry-run, --no-respect-gitignore, --include-node-modules, --with-env, --pattern <glob>; git push/fetch take --remote <name> (default origin) and forward extra args like --force-with-lease.

See Sync & git and Environment.

Checkpoints

A checkpoint is warm box state that new boxes start from instantly. checkpoint (alias checkpoints) defaults to ls.

# List this project's checkpoints; -g spans all projects
agentbox checkpoint ls
agentbox checkpoint ls -g

# Capture box 1 and pin it as the project default
agentbox checkpoint create 1 --set-default

# Capture with a name; recapture idempotently
agentbox checkpoint create 1 --name warm --replace

# Pin / clear / scope the default
agentbox checkpoint set-default warm
agentbox checkpoint set-default --clear
agentbox checkpoint set-default --provider hetzner warm

# Delete a checkpoint
agentbox checkpoint rm warm

# Start a box from a checkpoint
agentbox create --snapshot warm
agentbox claude --snapshot warm

Checkpoints are per-project and provider-aware. set-default --provider <name> pins for one provider; otherwise it sets the cross-provider fallback. Docker stacks docker commit layers; cloud providers use native snapshots.

See Checkpoints & pausing.

Config

config reads and writes layered config; precedence is CLI flag > workspace defaults: > per-project > global > built-in default.

# Read / write keys (--project is the default layer)
agentbox config get box.hostSnapshot
agentbox config set box.memory 2g
agentbox config set box.memory 2g --global
agentbox config unset box.memory

# Inspect layers and file locations
agentbox config get box.provider --all
agentbox config list
agentbox config path --project
agentbox config edit

# First-run wizard (auto-runs on first command; or run it explicitly)
agentbox install
agentbox install --skills-only   # just (re)install the host /agentbox skill
agentbox install cmux            # add a box-list panel to the cmux sidebar dock

# Diagnose system + provider readiness
agentbox doctor
agentbox doctor -p hetzner

# Prepare base images / snapshots, or just show status
agentbox prepare
agentbox prepare -p hetzner
agentbox prepare -p docker --build

install is the first-run setup wizard (system check, pick a provider, log in, prepare its base image, install the host skill). install cmux pins a live agentbox list panel (all your boxes) to the cmux sidebar dock — see cmux integration. doctor diagnoses system and provider readiness. prepare builds base images or snapshots — omit --provider for status only.

See Configuration, agentbox.yaml, and Environment.

Providers

The provider commands are both credential/management groups and sugar prefixes. agentbox <provider> <verb> is rewritten to --provider <provider>, so agentbox hetzner claude ≡ agentbox claude --provider hetzner.

# Sugar prefix — identical to passing --provider
agentbox docker create
agentbox hetzner claude
agentbox vercel codex
agentbox e2b claude

# Log in / rotate credentials (saved to ~/.agentbox/secrets.env)
agentbox hetzner login
agentbox vercel login
agentbox daytona login
agentbox e2b login
agentbox hetzner login --status   # show what's configured (masked)

# Provider tools
agentbox hetzner firewall show <box>
agentbox hetzner firewall sync <box>
agentbox daytona resync             # re-sync the credential volume

docker is the default and is pure sugar (no login). Each cloud provider has a login subcommand (run by default); hetzner adds firewall, daytona adds resync. E2B is the only cloud whose prepare builds the base image directly from a Dockerfile via the SDK's Template.build() — the others bake a one-time snapshot.

See Local Docker, Hetzner, Daytona, Vercel, and E2B.

Maintenance

# Clean orphan state records (dry run first)
agentbox prune --dry-run
agentbox prune --all -y
agentbox prune --provider hetzner

# Background jobs (agentbox claude|codex|opencode -i)
agentbox queue list
agentbox queue show <id>
agentbox queue cancel <id>
agentbox queue clear --all

# Host relay process
agentbox relay status
agentbox relay restart

# Update agentbox (wipes the box image so it rebuilds, reloads the relay)
agentbox self-update
agentbox self-update --dry-run

prune cleans up orphan state records; --all also removes orphan docker resources, and --provider <cloud> lists untracked cloud sandboxes and offers to delete them. queue manages background -i jobs. relay manages the host relay (status, stop, start, restart). self-update updates the CLI.

See Background & parallel, Core concepts, and Configuration.