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 the one key applied at CLI startup; every other key flows through the per-command effective-config load.

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

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

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.

browser

See browser and screen.

integrations

Per-service toggles for relay-gated service integrations. Each integration is disabled by default — even when the host CLI is installed and authed, the box can't call out until you flip it on. The box never holds the service's token; reads pass through, writes prompt on the host. See Notion and Linear.

agentbox config set --project integrations.notion.enabled true
agentbox config set --project integrations.linear.enabled true

agentbox doctor reports a row per integration in a dedicated integrations: group: disabled (default), ntn not installed, not logged in, or authed — with a one-line hint for each non-ok state.

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.