ACP servers

Agent Client Protocol gives an editor, terminal client, or another agent a common way to start sessions, send prompts, stream updates, and handle permission requests.

An ACP server exposes an agent to a client. BitRouter integrates with these servers through agent adapters in two directions:

• bro code and bro run act as ACP clients that drive an agent adapter.
• bro acp serve <agent> exposes a BitRouter-managed adapter over protocol-pure stdio to another ACP client.

The current open-source surface is local and stdio-based. It is not a cross-host agent registry or a durable fleet control plane.

Choose an ACP server

BitRouter ships a catalog of maintained adapters, including Claude and Codex. The CLI identifies these servers as agents, so discovery and configuration use bro agents and the agents: policy field. A catalog id does not need an agents: entry.

bro agents list
bro agents check codex
bro agents inspect codex

• list shows the bundled catalog and configured agents; --remote also reads the public ACP registry.
• check starts an adapter and verifies initialization and routing.
• inspect opens a fresh session and reports the commands advertised by the agent.

For an agent outside the bundled catalog, generate a configuration stub and review it before adding it to the bitrouter.yaml router policy:

bro agents scaffold <id>

You can also declare a local stdio agent directly:

agents:
  house-agent:
    name: house-agent
    transport:
      type: stdio
      command: ./bin/our-acp-agent
      args: ["--profile", "review"]
      env:
        RUST_LOG: warn

The child inherits the ambient environment; env adds or overrides entries for that process. Agent names must be non-empty and cannot contain /.

Serve an adapter to an ACP client

An ACP-capable editor or parent process can launch BitRouter as its agent command:

bro acp serve codex

The client owns the stdio connection and initializes first. One connection may carry multiple harness-native sessions. Standard output is reserved for ACP JSON-RPC; diagnostics go to standard error.

Run one headless turn

bro run opens one ACP session and sends a prompt without an interactive terminal:

bro run codex "Summarize this repository"

See Headless for prompt input, output formats, tool approval policies, and result validation.

Routing and session ownership

Supported adapters route model traffic through the local daemon by default, inheriting its provider selection, fallback, policy, and metering. Use --direct to keep an adapter on its own credentials, or --base-url to target an explicit gateway.

Session identity and history remain owned by the harness:

• --load <id> asks the harness to replay a native session.
• --resume <id> continues a native session without replay.
• BitRouter does not create a parallel durable session catalog.

Optional acp_recording configuration can mirror observable ACP content into the local BitRouter database for inspection. A recording is an audit copy, not the source of truth for the agent's session.