Run an agent

AgentBox runs Claude Code, OpenAI Codex, and OpenCode inside a box, in a detachable tmux session — so you can leave the agent working, detach, and reattach later.

The three agent verbs (claude, codex, opencode) each create the box if it doesn't already exist, start the agent, and attach you. They share all agentbox create flags — see CLI commands — plus session-resume and attach controls. This page assumes you've read core concepts; the project-teleport mechanics live in teleport a project.

NOTE

<box> is optional almost everywhere — it defaults to the single box for the current project. Otherwise pass its short index (1, 2, …), name, or id prefix.

Launch an agent

agentbox claude is the one-liner: it creates a box (snapshotting the current directory), starts Claude Code in a detached tmux session, and attaches you. agentbox codex and agentbox opencode have the identical shape.

agentbox claude                       # create a box + start Claude Code, then attach
agentbox claude -- --model sonnet     # pass extra args through to claude

Target another directory with -w, and put pass-through args after --. Boxes get an auto-numbered name by default; pass -n <name> to label one. The first run pulls or builds the agentbox/box:dev image (~1 GB, one-time) and offers a setup wizard that installs project deps and your dev server. See local Docker for the image and services and tasks for the wizard.

$ agentbox claude
log: ~/.agentbox/logs/claude.log
Starting Claude in a box...
> Run setup wizard? › Yes
  ...box ready...
attaching — Control+a d to detach, leaves claude running

Claude Code running inside a box, attached over tmux.

Detach and reattach

The agent runs in a detachable tmux session whose prefix is Control+a (not the usual Ctrl-b). Press Control+a then d to detach — the agent keeps running in the box.

Control+a also opens an actions menu: c (VS Code / Cursor), s (noVNC screen), u (box URL), t (a fresh shell in the same box, opened in a new tab), and k (destroy the box, after a confirmation). The shell tab opens as a cmux surface in the current workspace, a new tmux window, or a new iTerm2 tab depending on your terminal.

Reattach with the attach subcommand, or resync your host config and reattach with start.

# detach from inside the session: press Control+a then d
agentbox claude attach 1              # reattach to box 1's Claude session
agentbox claude start mybox           # start a session (resyncs host ~/.claude)

attach starts a session if none is running and auto-unpauses a stopped box, but never resyncs your host ~/.claude. start does the resync — use it when new skills, plugins, or a fresh login should flow into the box. For --attach-in, --no-attach, and the other attach controls, see CLI commands.

HEADS UP

attach never resyncs your host ~/.claude (skills, plugins, login). After installing a new skill or signing in on the host, use claude start (or a fresh agentbox claude) so the box picks it up.

Switch agents

Codex and OpenCode follow the identical flow — agentbox codex / agentbox opencode, each with attach, start, and login subcommands.

agentbox codex                        # OpenAI Codex in a box
agentbox opencode                     # OpenCode in a box
agentbox dashboard                    # switch between running boxes/agents

Auto-approve is on by default because the box is isolated from your host; pass --no-dangerously-skip-permissions to keep the agent's own approval prompts. Each agent shares an identity volume across boxes by default — opt out per box with --isolate-claude-config (and the codex/opencode equivalents). See configuration and CLI commands.

You can run different agents in different boxes for the same project and switch between them with agentbox dashboard. Claude and Codex resume sessions; OpenCode does not yet (resume starts a fresh box).

WHY

Auto-approve is safe to default on because the box can't touch your machine — it's isolated from the host. The agent works without stopping to ask, and you keep your laptop clean.

First-run auth

Credentials are handled on the host and seeded into every box (macOS Keychain doesn't transfer into containers). On the first agentbox claude with no credentials, AgentBox offers an interactive sign-in that's saved and reused by every future box. Skip it with -y (or in CI) and claude will prompt you to /login inside the box.

agentbox claude login                 # sign in once, reused by every box
agentbox codex login                  # device-auth flow for Codex
agentbox opencode login -- --provider anthropic

$ agentbox claude
? Sign in with your Claude subscription? (saved and reused by every box) › Yes
✔ Signed in with your Claude subscription — saved for future boxes.

Setting ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN (Claude) or OPENAI_API_KEY (Codex) on the host forwards it into the box and skips the sign-in offer. Host ~/.claude stays the source of truth — every create / claude syncs it in, so skills, plugins, MCP, and login flow into the next box. Cloud providers capture the login to ~/.agentbox and push it in on create — see hetzner, daytona, and vercel.

TIP

Sign in once on the host. Install a skill or sign in there, and the next box picks it up automatically. See configuration and sync and git.

Next steps

Access your box — shell, VS Code/Cursor (agentbox code), the dashboard.
Web apps and tunnels — agentbox url for the box's dev server.
Background and parallel — -i/--initial-prompt, --no-attach, and running many boxes at once.
Checkpoints and pausing — --snapshot, pause/unpause.
Teleport a project — -c/--continue, --resume, and how the workspace and git reach the box.