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 agentbox attach — it picks the running agent session in the box automatically. Resync your host config and (re)start a session with agentbox claude start (or codex start / opencode start).

# detach from inside the session: press Control+a then d
agentbox attach 1                     # reattach to whichever agent is running on box 1
agentbox claude start mybox           # start a session (resyncs host ~/.claude)

agentbox attach is agent-agnostic — if multiple agent sessions live in the same box it prompts you to pick. It never auto-starts: when nothing is running it prints a warning and exits non-zero. To start a fresh session use the agent's own command (agentbox claude, codex, opencode) — start also resyncs your host config so new skills, plugins, or a fresh login 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

Sign-in runs in a throwaway container, but the agent's own login TUI never takes over your terminal: AgentBox drives it behind the scenes, prints the approval URL, and prompts you for the code (or API key) itself. That keeps the flow identical in every terminal emulator. Two escape hatches:

--interactive hands your terminal to the agent's own login TUI — the old behavior. Use it for a login method the guided prompt can't drive (an exotic agentbox claude login -- --sso, or OpenCode's GitHub Copilot picker, which AgentBox falls back to automatically).
--headless (claude, and the automatic choice with no TTY) prints the URL and a greppable AGENTBOX_LOGIN_URL= marker, then you finish with agentbox claude login --code <CODE> — so an orchestrating agent can drive the sign-in. Codex's device-code flow needs no keystroke at all, so it already works without a terminal.

$ 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.

Credential sync across boxes

Claude's OAuth refresh rotates the refresh token: the moment any box refreshes, every other copy of that login (the host backup, other boxes) stops working and 401s. AgentBox handles this automatically: the in-box supervisor watches each agent's credential file (~/.claude/.credentials.json, codex/opencode auth.json) and reports a refreshed blob to the host relay, which keeps the newest one (for Claude, expiresAt decides; codex/opencode are last-writer-wins) and pushes it into all your other running boxes — docker boxes via their config volumes (paused ones included), cloud boxes over the provider transport. A paused cloud box is reconciled when it wakes: resume/start compares the box's blobs with the host backup and pushes or captures whichever is newer.

This is on by default; disable it per box with agentbox create --no-credential-sync or globally with agentbox config set box.credentialSync false. A long-running agent session may hold the old token in memory and ask you to /login once even after the file was fixed — restart the session and it picks up the fresh login.

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.