Verbs

agentproto config

agentproto config show                 dump the full config as JSON
agentproto config path                 print the config file path
agentproto config get <key>            read one dot-notation key
agentproto config set <key> <value>    write a key (JSON-parsed when valid)
agentproto config unset <key>          delete a key
agentproto config edit                 open the file in $EDITOR

Hand-editable defaults at ~/.agentproto/config.json (or $AGENTPROTO_HOME/config.json when set). Resolution order for every daemon knob:

  1. CLI flag
  2. Env var (where one exists)
  3. config.json
  4. Hardcoded default

CLI flags always win — config.json is for defaults, not lock-in. Full key reference: ../reference/config-schema.md.

Subverbs

show

agentproto config show

Dumps the entire config as pretty JSON. Unknown keys are preserved across CLI versions, so this surface is forward-compatible.

path

agentproto config path
# → /Users/<you>/.agentproto/config.json

Prints the config file path. Scripting helper.

get

agentproto config get daemon.port
# → 18791

Dot-notation lookup. Exits non-zero when the key is unset.

set

agentproto config set daemon.port 18791
agentproto config set daemon.allowedOrigins https://guilde.work,https://app.example.com
agentproto config set tunnel.host wss://guilde.work/api/v1/agentproto/tunnel
agentproto config set features.pty true

Value parsing rules (in order):

  1. true, false, null → JSON literal.
  2. Valid JSON (numbers, arrays, objects, quoted strings) → parsed.
  3. Comma in value, not starting with " → split into a string array, trimmed.
  4. Otherwise → stored as a string.

So daemon.port 18791 is stored as number 18791, and daemon.allowedOrigins https://a.com,https://b.com is stored as ["https://a.com", "https://b.com"]. To force a literal JSON shape, quote it at the shell: agentproto config set foo '["a","b"]'.

The file is written atomically (tmp + rename) so a concurrent agentproto config edit can't half-truncate it.

unset

agentproto config unset tunnel.host

Removes the key. Unsetting a missing key is a no-op (exit 0).

edit

agentproto config edit

Opens the config in $EDITOR (falling back to $VISUAL, then vi). Creates the file if missing before launching the editor.

Common keys

KeyTypeNotes
adaptersstring[]Swarm-kernel adapter package ids loaded by run-swarm. Managed via adapters.md. (Formerly plugins[] — the verb was renamed plugins→adapters.)
profileAliasesRecord<string,string>Map of runtime-profile/<name> → npm package, for third-party profiles. See ../concepts/runtime-profiles.md.
daemon.portnumberDefault 18790.
daemon.bindstringDefault 127.0.0.1.
daemon.workspacestringAbsolute path; passed as serve --workspace when set.
daemon.allowedOriginsstring[]Trusted browser origins for mutating routes (in addition to localhost defaults).
daemon.strictOriginsbooleanWhen true, drop the localhost-default. Only allowedOrigins are honoured.
daemon.labelstringServer label sent in tunnel hello frames.
daemon.reviewSessionRetentionDaysnumberDays after which a terminal review-lane session dir (~/.agentproto/sessions/<id>/) is deleted by the retention sweep. Default 7; 0 disables. See sessions gc --retention.
daemon.sessionRetentionDaysnumberSame, for every other terminal session. Default off (unset / 0). Pinned, keepAlive and live sessions are never deleted.
daemon.idleReapAfterMsnumberRetire an idle agent-cli session after this many ms (SIGTERM the adapter, row killed / idle-reaped, lazily resumable). Default off (unset / 0). Env: AGENTPROTO_IDLE_REAP_AFTER_MS. Needs a restart.
daemon.sandboxIdleReapAfterMsnumberShorter idle threshold for sandboxed sessions (a session in a provider box: e2b, …). Default 900000 (15 min); 0 turns it off. Env: AGENTPROTO_SANDBOX_IDLE_REAP_AFTER_MS. Needs a restart. See Sandbox idle reap.
tunnel.hoststringDefault tunnel URL for serve and daemon install.
tunnel.autoconnectbooleanWhen true, daemon install bakes --connect tunnel.host into the plist; serve falls back to it when --connect is omitted.
tunnel.e2ebooleanOpt into end-to-end encrypting the outbound tunnel (needs tunnel.token; the host must also support it, else it falls back to plaintext). See serve.
features.ptybooleanInformational hint; the daemon detects node-pty at runtime regardless.

Sandbox idle reap

A finished turn does not close a session, so a sandboxed session sits idle with its box (a billed VM) running until the provider lifetime expires. daemon.sandboxIdleReapAfterMs bounds that: a session running in a provider box that has been idle this long is reaped, and its box goes with it.

  • Applies to sessions with a provider box (sandboxId set, not a device: spawn). Non-sandbox sessions are unaffected and keep following daemon.idleReapAfterMs only. If both knobs are on, a sandboxed session is reaped at the shorter one; if the sandbox knob is 0, it falls back to the general knob.
  • Never reaped while busy, awaiting input or a permission decision, blocked on a command or sub-agent, running a background task, parent of a live child session, archived, or keepAlive.
  • Teardown order: final checkpoint of the box's work (uncommitted changes included, capped at 2 min so a hung checkpoint cannot keep the box alive), then the box session is killed, the work branch is delivered, and the box is killed. A spec that asked to pause (lifecycle.pause_after_idle, or a reuse boot) pauses it instead; lifecycle.destroy_on always kills.
  • Ledger: the row for the box in ~/.agentproto/sandboxes.json ends in stopped (or paused) and records reapedAt, reapedIdleMs and reapedSessionId.
  • Revival: the session row stays (killed / idle-reaped). A later prompt cold-boots a fresh box from the checkpoint branch (the same path as session_restart) and delivers the prompt there. The old row is superseded (continuedTo); later prompts to the old id are told to use the new one. A failed move fails the prompt with the blocker rather than resuming an adapter on the host.
agentproto config set daemon.sandboxIdleReapAfterMs 600000   # 10 min
agentproto config set daemon.sandboxIdleReapAfterMs 0        # never reap boxes