Access your box

A box is a full computer, not just an agent REPL. Once it's running you can reach into it many ways — an interactive shell, the box's web app, its live desktop over VNC, one TUI that ties them all together, your desktop IDE, and the workspace files in Finder.

Every command below takes an optional <box>. Omit it for the project's only box, or pass a project index (1, 2, …), a name, an id prefix, or the container name. Run agentbox list to see indices and names.

Shell

agentbox shell [box] drops you into bash -l as vscode in /workspace, inside a detachable tmux session. Ctrl+a d detaches without killing it, and closing the terminal doesn't kill it either — reattach later with agentbox shell attach [box].

A box can hold many shells (the agent is still exactly one per box): --new opens an auto-numbered shell, -n <label> opens or attaches a named one.

# interactive detachable shell (Ctrl+a d to detach)
agentbox shell mybox

# a second, named shell in the same box
agentbox shell mybox -n logs

# run a one-shot command (no tmux, machine-readable output)
agentbox shell mybox -- npm run build

A one-shot -- <cmd> is never tmux-wrapped, so stdout stays clean for scripts. See CLI commands for all flags.

The footer's (<state>) slot — next to the box name — shows your agentbox.yaml service status: starting N/M… while services boot in the background, service error if one crashed, ready once they're all up. (Boxes with no services show the agent's activity there instead.) It's the answer to "are my services up yet?" without leaving the session.

While attached to any box session, Ctrl+a t opens a fresh shell in the same box in a new tab — a cmux surface in the current workspace, a new tmux window, or a new iTerm2 tab, depending on your terminal. Ctrl+a k destroys the box (after a confirmation) — the same key the dashboard uses, so it never collides with Ctrl+a d (detach). For per-terminal setup — where sessions open, the full chord list, and the cmux sidebar — see the integration pages for iTerm2, tmux, and cmux.

cmux: a button + shortcut that opens into the box

If you use cmux, you can add a tab-bar button and shortcut that opens a shell in the current project's box (and behaves normally everywhere else). Add this to ~/.config/cmux/cmux.json and run cmux reload-config:

{
  "actions": {
    "agentbox-shell": {
      "type": "command",
      "title": "Shell in box",
      // Auto-pick the project's box; fall back to a normal login shell elsewhere.
      "command": "agentbox shell || exec $SHELL -l",
      "target": "newTabInCurrentPane",
      "icon": { "type": "symbol", "name": "terminal" },
      "shortcut": "cmd+shift+t"
    }
  },
  "ui": { "surfaceTabBar": { "buttons": ["cmux.newTerminal", "agentbox-shell"] } }
}

agentbox shell with no argument auto-picks the only box in the current directory's project; outside an AgentBox project it exits non-zero and the || exec $SHELL -l fallback opens an ordinary shell. This adds a "Shell in box" button to the surface tab bar plus a Cmd+Shift+T shortcut, leaving cmux's standard Cmd+T (new surface) untouched. If you'd rather it be Cmd+T, set the action's shortcut to cmd+t and add "shortcuts": { "bindings": { "newSurface": "cmd+shift+t" } } to move the built-in off it.

For the AgentBox Dock panel (a live box list pinned to the cmux right sidebar via agentbox install cmux), see cmux integration → The AgentBox Dock.

Web app URL

agentbox url [box] opens the box's web app in your host browser. This works even when no service declares expose: — every box reserves the web port at create time, so the URL is always openable (you'll just get a connection error until something listens).

# open the box's web app in your browser
agentbox url mybox

# just print the URL (pipe into scripts)
agentbox url mybox --print

The URL form depends on the engine (OrbStack .orb.local, Docker Desktop Portless <box-name>.localhost, cloud preview HTTPS). See CLI commands for --loopback, --ttl, and other flags.

Live screen

agentbox screen [box] opens the box's live desktop in your browser over noVNC. This is where you watch the in-box headed Chromium the agent drives, or any other GUI process. The per-box VNC password is embedded in the auto-connect URL, so the browser jumps straight to the desktop.

# watch the box's desktop (in-box browser, GUI apps) in your browser
agentbox screen mybox

# print the noVNC URL instead of opening
agentbox screen mybox --print

This is distinct from agentbox url: url opens the web app, while screen opens the desktop. A box created with --no-vnc has no screen. The shared --loopback / --ttl flags are in CLI commands.

The deeper VNC and agent-browser story lives in Browser and screen.

Dashboard

agentbox dashboard is the interactive TUI: a sidebar box list grouped by project on the left, and the selected box's live agent session on the right.

# the box list + live agent session TUI
agentbox dashboard

# scope to the current project only
agentbox dashboard --project

Switch boxes with Control+Option+↑/↓. Everything else is a Ctrl+a leader chord — press Ctrl+a to show the which-key menu in the footer, then a single key (c code, s screen, u url, p pause, and so on). These shell out to the same commands above, so they inherit the same behavior.

VS Code / Cursor

agentbox code [box] opens VS Code or Cursor Desktop attached to the box via the Dev Containers extension, with /workspace as a remote folder. It auto-detects your IDE (prefers code, falls back to cursor); force a flavor with --ide. See CLI commands for all flags.

# open the box in your IDE (auto-detects code, falls back to cursor)
agentbox code mybox

# force a flavor
agentbox code mybox --ide cursor

It also writes /workspace/.vscode/tasks.json so the IDE auto-opens terminal panels tailing each service's log, from the services and tasks you declare in agentbox.yaml.

Open files

agentbox open [box] opens the box's /workspace in Finder. The merged /workspace only exists inside the container, so open first rsyncs it to a per-box host directory and then launches Finder. The export is a snapshot, refreshed on demand — re-run to re-sync. See CLI commands for flags like --no-refresh, --include-node-modules, and --path.

# rsync /workspace and open it in Finder
agentbox open mybox

# print the host path without opening Finder (for editors/scripts)
agentbox open mybox --path --no-refresh