Configuration keys

AgentBox reads layered defaults at the start of every command. The same key shape lives in three files plus a runtime CLI-flag layer, so a preference can be a one-off flag, sticky for one project, or shared with your whole team.

You rarely need to touch config — every key has a built-in default and most surfaces also expose a one-off CLI flag. Config is for making a preference stick.

Config layers

AgentBox merges four layers on top of the built-in defaults. Highest layer that sets a key wins:

CLI flag > workspace defaults: > per-project > global > built-in default

The per-project <hash> is the first 16 hex chars of the SHA-1 of the project's absolute path. The workspace layer is found by walking up from the current directory to the nearest agentbox.yaml.

config set/unset/edit only write the --global or --project files (project is the default). The committed defaults: block is hand-edited — see agentbox.yaml for its full schema. engine.kind is read by the engine detection itself, so it applies in every process that touches docker — the CLI, the hub, the relay.

The config command

Seven subcommands: get, set, unset, list, path, edit, list-projects. The default write scope is --project. Pass at most one scope flag.

# Read the effective value of a key (and where it came from)
agentbox config get box.provider

# Set a key (default scope is --project)
agentbox config set box.withPlaywright true

# Set a key globally for all projects
agentbox config set box.provider hetzner --global

# Remove a key from a scope (default --project)
agentbox config unset box.image --project

# List effective config; advanced keys hidden unless you ask
agentbox config list
agentbox config list --include-advanced

# List one layer's raw values
agentbox config list --scope global
agentbox config list --scope workspace

# Print or open a scope's file
agentbox config path --workspace
agentbox config edit --global

# Show directories that have per-project config recorded
agentbox config list-projects

config get --all shows every layer's value with its source — the fastest way to see why a key resolved the way it did:

$ agentbox config get box.provider --all
box.provider:
  effective: hetzner   (global ~/.agentbox/config.yaml)
  cli:       <unset>
  workspace: <unset>
  project:   <unset>   ~/.agentbox/projects/3f2a…/config.yaml
  global:    hetzner   ~/.agentbox/config.yaml
  default:   docker

<unset> is the literal token the CLI prints for an absent value. get, set, list, path, and list-projects all accept --json. set coerces the value to the key's declared type (bool/int/enum/string) and errors on an invalid enum or non-int. There is no config set --workspace; to change the committed defaults:, edit agentbox.yaml (or run config edit --workspace, which just opens that file).

box.* — the box keys

The largest group. A pattern runs through it: a generic key plus per-provider overrides of the form <key><Provider> (e.g. box.sizeHetzner). The provider-specific form wins over the generic one for that provider. This applies to box.size*, box.image*, and box.defaultCheckpoint*.

Provider

This is what plain agentbox claude (or create, codex, opencode, pi) uses when you don't pass --provider. agentbox install offers to set it for you at the end of the wizard, so the provider you just logged in to and prepared becomes the one new boxes go to. Set it yourself at any time:

agentbox config set box.provider hetzner --global    # every project on this machine
agentbox config set box.provider hetzner             # this project only

A per-run --provider docker (or the agentbox docker claude prefix) still overrides it.

It also accepts a host-qualified engine spec — docker:<alias> — naming a registered Remote Docker host rather than a provider:

agentbox config set box.provider docker:hub --global      # your control box's own engine
agentbox config set box.provider docker:buildbox          # a machine of yours

That form is shorthand for two keys, and it is stored as two:

box:
  provider: remote-docker
  remoteDockerHost: hub

So agentbox config get box.provider answers remote-docker, with the engine in box.remoteDockerHost. Both spellings work in a hand-written config file — provider: docker:hub is split on read — and each key layers on its own, so a project can point at a different engine without repeating the provider.

Setting up a control box does the first one for you when your default was still plain docker, since a control box turns local docker boxes off.

See local Docker, Remote Docker, Hetzner, Daytona, Vercel, and core concepts.

Resource limits (Docker)

VM size (cloud)

Box image

Default checkpoint per project

See checkpoints and pausing.

Create-time toggles

See teleport a project, environment, browser and screen, sync and git, and Docker in Docker.

Config-volume isolation

Vercel only

See Vercel.

checkpoint.*

See checkpoints and pausing.

Agent sessions — claude / codex / opencode / pi

These keys are generated per agent, so every agent AgentBox ships gets the same set — <agent>.sessionName always, and <agent>.dangerouslySkipPermissions only where that agent actually has such a launch flag (OpenCode and Pi have none — Pi ships with no permission prompts at all).

Agent settings

An agent can also declare settings of its own, and those become config keys in the same block. Claude declares two:

These are deliberately not generic keys. Which installer Claude Code uses and which of its two renderers it picks are facts about Claude, not about agents in general — so the names stay Claude's. What is generic is the mechanism: an agent declares its settings, AgentBox generates the keys, and the values reach that agent's own install recipe and launch. An agent installed with agentbox agent add gets real config keys the same way, with no change to AgentBox — run agentbox config list to see what an agent declares.

attach

split uses a tmux split-window / cmux new-split / Herdr pane.split / iTerm2 vertical split (same workspace). tab opens a new tmux window / a new cmux surface (a tab in the current pane, same workspace) / a new Herdr tab / a new iTerm2 tab. window opens a new tmux window / a separate cmux workspace / a new Herdr workspace / a new iTerm2 window. Outside tmux/cmux/Herdr/iTerm2 every value behaves like same. Under Herdr the default is a new tab (rather than a split) — set attach.openIn (or pass --attach-in) explicitly to override. See access your box.

attach.cmuxStatus surfaces a box's agent state in the cmux sidebar. While you're attached inside a cmux surface, AgentBox reflects the agent's live activity on the box's cmux workspace via its colour and description — blue/"working" while the agent runs, amber/"needs input" when it asks a question or is waiting, and the tint clears when idle. The workspace's original colour and description are restored when you detach. When you open several boxes from one project as tabs in the same workspace (--attach-in tab), AgentBox also flags the individual tab whose agent needs input via a cmux notification (tab badge + reorder + a desktop notification), so you can tell which box is waiting; the flag clears when you focus that tab. (cmux only renders its status pills for workspaces running an agent it recognizes; a box runs the agent inside the container, so AgentBox drives the always-visible workspace colour/description and the per-tab highlight instead.) No effect outside cmux; set to false to disable.

attach.herdrStatus makes a box look like a normal agent inside Herdr. While you're attached inside a Herdr pane, AgentBox reports the box agent's live activity to that pane (working / blocked / idle), so Herdr applies its native agent treatment — including its own needs-input handling. The one thing Herdr can't see is AgentBox's own host-relay approval prompts (git push, PR, checkpoint, …), so those get an explicit Herdr notification. No effect outside Herdr; set to false to disable. See Herdr integration.

code / shell

See access your box.

ssh

For providers that reach a box over plain SSH with a persistent per-box key (Hetzner, and DigitalOcean once wired), AgentBox writes one Host <box-name> entry per box into its own ~/.agentbox/ssh/config file and adds a single Include ~/.agentbox/ssh/config line to the top of your ~/.ssh/config — so ssh <box-name> (and VS Code Remote-SSH, Codex, Claude desktop) just works without touching the rest of your config. The file is regenerated from box state on create and on start/resume (a cloud box's public IP can change across stop/start), and a box's entry is dropped on destroy. Set ssh.autoConfig to false if you manage ~/.ssh/config yourself; the explicit agentbox shell <box> --ssh-config, agentbox code, and agentbox open commands still write the entry on demand. Docker boxes (no SSH) and Daytona (60-minute token auth, no persistent key) are never auto-added.

The same file also gets a Host agentbox-hub entry for a deployed control box, pointing at its VPS and the per-deploy key under ~/.agentbox/control-plane/ssh/<stamp>/ — so ssh agentbox-hub reaches the machine running your hub. A box you happen to name agentbox-hub wins the alias.

browser

See browser and screen.

tools

Policy for the host-tool proxy. The list of granted tools is not config — it is written by agentbox tools add and by approved in-box requests, and lives in a host-only grant file. These two keys are the policy around it.

agentbox tools add terraform                     # grant a tool
agentbox config set tools.gh.enabled false       # revoke the built-in gh grant
agentbox config set --project tools.request.enabled false   # boxes may not ask

Whether a granted tool prompts on every call is controlled by box.autoApproveSafeHostActions (default true — granted tools run quietly, and every call is still audited).

agentbox doctor reports one row per granted tool in a tools: group, probing whether the host binary actually resolves.

queue & autopause

queue.* schedules background -i jobs; autopause.* pauses idle boxes.

agentbox config set queue.maxConcurrent 3 --global
agentbox config set autopause.idleMinutes 10 --global
agentbox config set queue.openIn split --global

By default a background -i run just queues and prints its job line. Set queue.openIn to split, window, or tab and the host relay opens an attached terminal onto the box the moment its worker finishes creating it — no need to find the box and attach by hand. It only fires when the submitting shell is inside tmux, cmux, Herdr, or iTerm2. Under cmux, split splits the pane you submitted from (falling back to the parent workspace, then a new workspace), tab adds a tab in the parent workspace, and window opens a separate workspace; under Herdr, split splits the pane you submitted from, tab adds a tab in the parent workspace, and window opens a separate workspace; iTerm2 opens relative to the frontmost window. Unlike attach.openIn there is no same mode (the box is created asynchronously, so it is always a fresh terminal).

Auto-pause only ever targets a box whose live agent has settled to idle for idleMinutes. A box where any agent (Claude, Codex, or OpenCode) is working, compacting, or waiting on you is never auto-paused. If a box does get paused while you still need it, agentbox drive …, agentbox shell, and agentbox unpause all resume it on demand (drive auto-unpauses before it reaches the session).

See background and parallel and checkpoints and pausing.

cloud / engine / portless / relay / vnc / maintenance

The remaining infrastructure knobs — mostly advanced.

See web apps and tunnels, local Docker, sync and git, and browser and screen.

Where the files live

$ agentbox config path --global
/Users/you/.agentbox/config.yaml
$ agentbox config path --project
/Users/you/.agentbox/projects/3f2a8c1d9e0b4a76/config.yaml
$ agentbox config list-projects
3f2a8c1d9e0b4a76  /Users/you/Projects/myapp

• Global: ~/.agentbox/config.yaml
• Per-project user: ~/.agentbox/projects/<sha1-16-of-abs-path>/config.yaml
• Workspace (committed): the defaults: block in agentbox.yaml

For the defaults: block and the full agentbox.yaml schema, see agentbox.yaml; for secrets and env files, see environment. The served JSON schema lives at /schema/user-config.schema.json.