Configuration reference

modes

Modes & commands

One command, two modes, the same config file:

The complete CLI surface:

file

The config file

JSON, with a top-level bridges array of at least one entry. Each entry is one bridge:

agents.json

{
  "bridges": [
    { "name": "codex",  "port": 3948, "apiKey": "",
      "sandbox": "workspace-write", "approval": "on-request" },
    { "name": "claude", "port": 3949, "apiKey": "" },
    { "name": "pi",     "port": 3950, "apiKey": "" },
    { "name": "gemini", "port": 3951, "apiKey": "" }
  ]
}

This is the shipped starter (agents.example.json, included with both install paths). name must come from the registry: codex, claude, pi, gemini — long-tail agents join by adding a line to agents-registry.mjs, not by loosening validation.

fields

All fields

Fields with illegal values refuse startup and are reported one by one. Anything not in this table is ignored.

codex · sandbox & approval

codex sandbox & approval

Together these two fields decide "what codex may do on its own" and "when it interrupts you". Both are passed to codex verbatim at session start (thread/start's sandbox and approvalPolicy) and enforced by codex itself.

sandbox — the sandbox tier

network only matters under workspace-write: danger-full-access comes with network anyway, and read-only ignores the field.

approval — the approval policy

approve cards

Too many approval cards? The recipe

The mechanism first: the bridge does not decide when to ask — codex raises the request and the bridge forwards it to your client. More cards means your commands don't match the sandbox / network / approval combination.

/bin/bash -lc "curl -L --fail --max-time 15 -s 'https://…' | rg -m 12 '…'"

Three things trigger a card:

• a command writes outside the sandbox (installing deps under read-only, writing logs);
• a command needs network but the tier has none (workspace-write without network: true — one curl is enough);
• the approval policy demands confirmation (untrusted asks about almost everything).

{ "name": "codex", "port": 3948,
  "sandbox": "danger-full-access", "approval": "never" }

{ "name": "codex", "port": 3948,
  "sandbox": "workspace-write", "network": true, "approval": "never" }

for client implementers

Approval wire flow

For client authors: an approval is one request and one answer on the v1 wire. The agent emits an approval event (SSE or WS frame); you render it as a card and answer over HTTP once the user decides:

agent → client (SSE data frame)

{"type":"approval","requestId":"…","tool":"command","command":"…","cwd":"…"}

client → bridge

POST /approvals/<requestId>
{ "choice": "once" | "always" | "deny" }   // → {"ok":true}

once allows this one, always allows later ones like it, deny refuses. Echo the requestId verbatim — it may be a string.

security

Security posture

• Loopback by default. A non-loopback --bind requires an apiKey (Bearer token) on every entry, or startup is refused.
• Host-header allowlist (the DNS-rebinding guard) applies to loopback binds only; remote binds are gated by the token.
• CORS reflects loopback origins only; cross-origin needs the explicit "corsOrigin": "*", paired with apiKey.
• The config holds secrets: the bridge warns when agents.json is group/world-readable — chmod 600 agents.json.
• Plain HTTP: TLS belongs in a reverse proxy (nginx/caddy); the bridge sends X-Accel-Buffering: no so SSE streams unbuffered.

fixed limits

Fixed limits

Deliberate protocol constants, not configurable:

zero-setup

Zero-setup fallback

acp mode resolves config in three steps: explicit --config → an agents.json beside you → the registry's built-in default. The last one is why agent-bridge acp claude runs with nothing configured (what registry-style auto-install invokes): it spawns the registry's default agent command and says so on stderr.