Agentbox Info

<!-- agentbox-managed:v1 -->

AgentBox (host-side)

You are operating on the user's host machine (laptop / dev workstation), not inside a box. Use the agentbox CLI to provision isolated sandboxes for coding agents and to attach to them.

If you find yourself inside a box (/workspace exists and AGENTBOX_RELAY_URL is set in the env), this is the wrong skill — use the in-box /agentbox-setup skill instead.

What AgentBox is, in one paragraph

AgentBox spins up one isolated sandbox per agent run — a local Docker container (default), a Hetzner VPS (--provider hetzner), a Vercel Sandbox (--provider vercel), an E2B microVM (--provider e2b), or a Daytona cloud sandbox (--provider daytona, partial support). Each box has its own /workspace, but the host's .git/ is shared, so commits made inside the box land on the host immediately. The agent inside the box has no host credentials — git push, opening URLs in the host browser, capturing checkpoints, and all other host-side operations flow through a small host process called the relay that runs alongside the CLI.

The two starting commands

agentbox create

Provision a box and stop. The box exists and is ready, but nothing is launched inside it.

agentbox create                       # docker, auto-named after the workspace
agentbox create -n review             # docker, friendly name
agentbox create --provider hetzner    # cloud VPS (requires `agentbox prepare --provider hetzner` once)
agentbox create --attach              # drop into a shell inside the box after create

Useful flags: -n <name> (friendly box name), --provider docker|daytona|hetzner|vercel|e2b, --attach, -w <path> (workspace to mount; defaults to cwd), --snapshot <ref> (start from a checkpoint).

Non-docker providers require a one-time agentbox prepare --provider <name> to bake the base image / snapshot.

agentbox claude

Provision (same as create) and launch Claude Code inside the box, in a detachable tmux session. This is the main entry point most users want.

agentbox claude                       # docker, attaches your terminal
agentbox claude -n review             # second box, named
agentbox claude --provider hetzner    # cloud
agentbox claude -- --model sonnet     # extra args after `--` go to claude itself

While attached: Ctrl+a d detaches without killing claude. The box keeps running. Reattach with agentbox claude attach <name|n>.

Variants with the same shape for other agents: agentbox codex, agentbox opencode.

-i / --initial-prompt: background queue

With -i "<prompt>", agentbox claude (and codex / opencode) does not attach. It writes a job manifest to ~/.agentbox/queue/<id>.json and exits immediately, printing the job id and log path. The host relay's queue loop drains these manifests respecting queue.maxConcurrent (global config; override per invocation with --max-running <n>).

Use this to fan out parallel agent runs:

agentbox claude -i "fix the failing test in src/auth and open a PR"
agentbox claude -i "draft a CHANGELOG entry from the last 20 commits"
agentbox claude -i "audit our dependencies for known CVEs"

Each call returns instantly. The queue drains them concurrently up to queue.maxConcurrent. Inspect / attach later:

agentbox dashboard                    # TUI with status + leader-key actions
agentbox claude attach <name|n>       # reattach to a specific box

-i works on every provider — pass --provider daytona|hetzner|vercel|e2b (or set box.provider) and the queued job creates a cloud box and pre-starts the seeded agent session detached, same as docker. The host must have valid agent credentials. Extra args after -- are forwarded to the in-box agent (e.g. agentbox claude -i "<prompt>" --provider vercel -- --permission-mode=plan).

-i honors the project's carry: block: the carry gate runs on the host when you submit (it prompts there, since you're at the terminal), and the approved files ride the queued job and land in the box at create time. Auto-approve non-interactively with --carry-yes (or AGENTBOX_CARRY_YES=1); skip with --carry skip (or AGENTBOX_CARRY=skip). The same three work on a plain agentbox create with no TTY. A file that IS present and approved but cannot be copied (permissions, an unwritable dest) fails the create and names the entry — only optional: true sources that are simply absent are skipped silently.

Forking the current session into a box

From host Claude, run the /agentbox slash command (optional arg: docker | daytona | hetzner | vercel | e2b) to snapshot the current Claude Code session into a brand-new box that resumes it. With tmux or iTerm it opens in a new terminal tab; otherwise it starts in the background. The host session is unaffected — you get two parallel timelines. The underlying CLI is agentbox fork (agentbox fork --help); /agentbox requires agentbox install to have been run once. This is distinct from -i, which seeds a new prompt rather than resuming the live conversation. Fork sends the project's carry: block by default (the host is trusted; the box is the untrusted side, so host→box copy is safe) — opt out with agentbox fork --carry skip.

Workspaces: tasks, and the timeline when you manage

A workspace has a task list (T-n). When the user asks to split or parallelize work across boxes, make tasks first (agentbox tasks add "…"), then start boxes with them (agentbox claude -i --tasks T-1,T-2) or hand one to a running box (agentbox tasks assign T-3 --box <box>).

A claude or codex session running agentbox in a workspace is one of its managers: its tasks, boxes and pushes land on the timeline, stamped with its turn. The timeline can't see your reasoning, so when you re-plan (reorder, hold, split, move work between boxes), say why in the same call:

agentbox tasks reorder T-14 T-11 T-12 --note "T-14 unblocks the payment tasks"
agentbox tasks assign T-17 --box b169ec5 --note "same files as T-16, same branch"
agentbox manager note "holding T-12 until #405 merges" --replan

An approval arrives as a new prompt (Approved: merge PR #409 (checkout-copy, T-14, T-15).): merge that PR, then mark its tasks done.

Driving one agent from another (drive, agent, queue wait-for)

When you are the host-side agent and want to orchestrate other agents running inside boxes — read what they're doing, send them a prompt, wait until they're done or need input — use these three command families. Everything is stateless / one-shot, and the human-text default switches to machine-friendly JSON with --json.

agentbox drive <box> — terminal driving

Targets the running tmux session inside a box (auto-picks the agent session: claude → codex → opencode → the only running session; override with --session <name>). Provider-uniform — works the same on docker / daytona / hetzner / vercel / e2b.

agentbox drive snapshot 1                          # print rendered TUI as plain text
agentbox drive snapshot 1 --with-cursor            # JSON envelope: { session, cols, rows, cursor, screen }
agentbox drive snapshot 1 --ansi --rows -200:-1    # include color, walk into scrollback
agentbox drive keypress 1 "<C-c>"                  # DSL: <Enter>, <C-x>, <Tab>, <F5>, <Up>, etc.
agentbox drive send-text 1 "hello"                 # literal text, no DSL parsing, no trailing Enter
agentbox drive prompt 1 "summarize /workspace/README" # type + Enter (the convenience action)
agentbox drive wait 1 --text "✓" --timeout 60000   # block until <text> appears on screen
agentbox drive resize 1 200 60

keypress uses a small DSL: <Enter>, <Tab>, <Esc>, <Space>, <BS>, <Del>, <Up>/<Down>/<Left>/<Right>, <Home>/<End>/<PageUp>/<PageDown>, <F1>–<F12>, <C-a>..<C-z>. Use << for a literal <. Multiple args concatenate with no spaces ("ls" "<Enter>" → ls\r).

agentbox agent <box> — agent state introspection (Claude / Codex / OpenCode)

Sub-second latency. State source by agent:

• Claude Code: lifecycle hooks (UserPromptSubmit, PreToolUse, Stop, Notification, ExitPlanMode, AskUserQuestion, PreCompact/PostCompact, StopFailure, SubagentStart/SubagentStop).
• Codex: tmux-pane scraper inside the box (codex 0.134.0's own hook firing is unreliable; staged hooks remain for the day that's fixed upstream).
• OpenCode: a plugin (agentbox-state.js) seeded into the OpenCode config volume, subscribing to OpenCode's event bus.

All three feed the same status pipeline; agent state / agent wait-for work the same regardless of which agent runs inside the box. Reports come from ~/.agentbox/boxes/<id>/status.json and the relay event stream.

agentbox agent state 1                # → working | idle | waiting | end-plan | question | prompt | compacting | error
agentbox agent state 1 --json         # full AgentStatusEntry (state, updatedAt, sessionTitle, plan?, question?)

agentbox agent get-plan-question 1            # print the plan body OR question + options (human)
agentbox agent get-plan-question 1 --json     # structured payload

Stdout carries only the value — spinners, notices and errors all go to stderr — so S=$(agentbox agent state 1) is safe to capture directly. --json is for structure (the full entry), not a workaround for dirty output.

For orchestration, agent wait-for input-needed is the tool to reach for. It is the single sync point that wakes whenever the agent needs you — whether the turn finished and it's ready for the next message, or it's blocked on a question, a plan to approve, a permission prompt, or an error. It matches every state except working / compacting, and prints the concrete state it matched so you can branch on why it woke:

agentbox agent wait-for input-needed 1 --timeout 600000   # → prints: prompt | end-plan | question | waiting | error

# Race a whole fan-out with ONE waiter — `--box` is repeatable, first box to match wins.
agentbox agent wait-for input-needed --box design --box tests --box docs --timeout 1200000
# → prints "<box>\t<state>" (with --json: { "box": { "id", "name" }, "state", "agent" })

Use the multi-box form instead of one background waiter per box: it returns as soon as any of them needs you, and tells you which. A single-box wait still prints the bare state.

A wait survives a hub restart — the relay going away mid-wait is retried with backoff until your --timeout actually elapses.

Prefer it over waiting on one specific transition — a narrow wait-for end-plan hangs to its timeout if the agent instead asks a question, hits a permission prompt, finishes, or errors. The granular states are still waitable when you know exactly what to expect: prompt (ready for next message), idle (Stop hook fired), end-plan, question, waiting, compacting, error — e.g. agentbox agent wait-for prompt 1.

agentbox queue wait-for <event> — queue + box lifecycle

agentbox queue wait-for new-box                          # any new box gets registered
agentbox queue wait-for empty-queue --timeout 1800000    # all queued/running jobs settled
agentbox queue wait-for box-running --box review
agentbox queue wait-for box-paused  --box 2
agentbox queue wait-for box-stopped --box 2
agentbox queue wait-for job-done --job b45f1603841bd2b5  # terminal status (done/failed/cancelled)

All wait-for commands accept --json for parseable output. agent wait-for exit codes:

Treat 7 as "my relay is down", not "my agent is stuck": the wait already retried for the whole window before reporting it. queue wait-for still exits 0 on match / 1 on timeout.

Recipe: drive a Claude Code from another Claude Code

Queue a prompt, then loop on wait-for input-needed and act on whatever it reports — that one waiter handles every "the agent needs me" case, so the loop never hangs on an unexpected state.

# 1. Kick off a box with a planning prompt, in background.
agentbox claude -n design -i "Plan how to add an OAuth login flow to apps/web, then enter plan mode. Don't start coding."

# 2. Wait until the agent needs you, and branch on what it reports.
STATE=$(agentbox agent wait-for input-needed design --timeout 1200000)
case "$STATE" in
  end-plan|question) agentbox agent get-plan-question design   # read the plan / question
                     agentbox drive keypress design "<Enter>" ;;  # approve / answer (option 1 pre-highlighted)
  waiting)           agentbox drive keypress design "<Enter>" ;;  # approve the tool/permission
  prompt|idle)       agentbox claude -i "Write the OAuth provider unit tests in apps/web/test/auth/" ;; # turn done — fan out more
  error)             echo "agent errored — inspect with: agentbox drive snapshot design" ;;
esac

# 3. Block until the whole batch settles before reporting back.
agentbox queue wait-for empty-queue --timeout 3600000

Driving several boxes at once is the same loop with one waiter over all of them — no background waiter per box:

while :; do
  HIT=$(agentbox agent wait-for input-needed --box design --box tests --timeout 1800000) || break
  BOX=$(printf '%s' "$HIT" | cut -f1); STATE=$(printf '%s' "$HIT" | cut -f2)  # the line is <box>TAB<state>
  case "$STATE" in
    end-plan|question|waiting) agentbox drive keypress "$BOX" "<Enter>" ;;
    prompt|idle)               echo "$BOX finished" ;;
    error)                     echo "$BOX errored — agentbox drive snapshot $BOX" ;;
  esac
done
# `|| break` catches exit 1 (timeout) and exit 7 (the hub never answered).

agentbox destroy --box design --box tests -y   # tear the fan-out down in one call

Wrap step 2 in a loop to babysit a box across many turns. Use the narrow wait-for <state> forms only when a step must gate on one specific transition.

Quick mental model

• agent wait-for input-needed = the orchestration sync point — "wake me when the agent needs me" (done OR blocked). Reach for this first.
• agent (state / get-plan-question / narrow wait-for) = "what is the agent currently doing" — hook-driven, race-free, machine-readable.
• drive = "send keystrokes / read screen" — provider-uniform tmux capture-pane / send-keys; how you act once wait-for returns.
• queue wait-for = "block on queue or box lifecycle transitions" (empty-queue, box-running, job-done, …) — settle a whole batch.
• All commands are stateless — safe to invoke from any script, any agent, in parallel.
• --json everywhere. Default human text is for the operator; an agent should pass --json.

Git through the host relay

The box has no SSH keys, GPG keys, or git remote credentials. Don't ask the user to add any. When an in-box agent (or a script you run inside the box) does git push or git pull, the AgentBox-provided agentbox-ctl git wrapper POSTs a JSON-RPC call to the host relay (POST /rpc, bearer-auth, loopback-only). The relay runs the real git push origin … on the host, using the user's SSH_AUTH_SOCK, ~/.gitconfig, and identity — and streams stdout/stderr back into the box's terminal. The box's exit code matches the host's.

Implications for you, the host-side agent:

• Inside the box you can git commit … && git push exactly as normal. No setup needed.
• Pushes follow the same blocklist model as gh below: publishing commits to any branch is ordinary, revertable work and runs silently. Only a push that cannot be undone asks the user first — a deletion (--delete, :branch), a force-push to a branch other than the box's own agentbox/* one, --mirror/--prune, a tag overwrite, --repo/--receive-pack, or any flag the gate does not recognise. --force-with-lease is the safe force spelling and stays silent. If a push appears to hang, it's waiting on that approval (the user sees it in the dashboard footer, ~25 s TTL) — see "Answering approvals" below.
• The relay process is started lazily by the first agentbox create / agentbox claude and persists across runs (PID at ~/.agentbox/relay.pid, log at ~/.agentbox/relay.log). You normally don't need to manage it.
• For HTTPS origins (https://github.com/...), pushing usually needs a credential — recommend the user run gh auth login and gh auth setup-git once on the host. After that, host git push uses gh's OAuth token automatically. SSH origins (git@github.com:...) keep using the host's SSH agent as before.