bot/docs/cli/acp.md

summary, read_when, title

summary	read_when	title
Run the ACP bridge for IDE integrations	Setting up ACP-based IDE integrations Debugging ACP session routing to the Gateway	acp

acp

Run the Agent Client Protocol (ACP) bridge that talks to a HanzoBot Gateway.

This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. It keeps ACP sessions mapped to Gateway session keys.

Usage

hanzo-bot acp

# Remote Gateway
hanzo-bot acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file)
hanzo-bot acp --url wss://gateway-host:18789 --token-file ~/.hanzo-bot/gateway.token

# Attach to an existing session key
hanzo-bot acp --session agent:main:main

# Attach by label (must already exist)
hanzo-bot acp --session-label "support inbox"

# Reset the session key before the first prompt
hanzo-bot acp --session agent:main:main --reset-session

ACP client (debug)

Use the built-in ACP client to sanity-check the bridge without an IDE. It spawns the ACP bridge and lets you type prompts interactively.

hanzo-bot acp client

# Point the spawned bridge at a remote Gateway
hanzo-bot acp client --server-args --url wss://gateway-host:18789 --token-file ~/.hanzo-bot/gateway.token

# Override the server command (default: hanzo-bot)
hanzo-bot acp client --server "node" --server-args hanzo-bot.mjs acp --url ws://127.0.0.1:19001

Permission model (client debug mode):

• Auto-approval is allowlist-based and only applies to trusted core tool IDs.
• read auto-approval is scoped to the current working directory (--cwd when set).
• Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval.
• Server-provided toolCall.kind is treated as untrusted metadata (not an authorization source).

How to use this

Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive a HanzoBot Gateway session.

1. Ensure the Gateway is running (local or remote).
2. Configure the Gateway target (config or flags).
3. Point your IDE to run hanzo-bot acp over stdio.

Example config (persisted):

hanzo-bot config set gateway.remote.url wss://gateway-host:18789
hanzo-bot config set gateway.remote.token <token>

Example direct run (no config write):

hanzo-bot acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
hanzo-bot acp --url wss://gateway-host:18789 --token-file ~/.hanzo-bot/gateway.token

Selecting agents

ACP does not pick agents directly. It routes by the Gateway session key.

Use agent-scoped session keys to target a specific agent:

hanzo-bot acp --session agent:main:main
hanzo-bot acp --session agent:design:main
hanzo-bot acp --session agent:qa:bug-123

Each ACP session maps to a single Gateway session key. One agent can have many sessions; ACP defaults to an isolated acp:<uuid> session unless you override the key or label.

Zed editor setup

Add a custom ACP agent in ~/.config/zed/settings.json (or use Zed’s Settings UI):

{
  "agent_servers": {
    "HanzoBot ACP": {
      "type": "custom",
      "command": "hanzo-bot",
      "args": ["acp"],
      "env": {}
    }
  }
}

To target a specific Gateway or agent:

{
  "agent_servers": {
    "HanzoBot ACP": {
      "type": "custom",
      "command": "hanzo-bot",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

In Zed, open the Agent panel and select “HanzoBot ACP” to start a thread.

Session mapping

By default, ACP sessions get an isolated Gateway session key with an acp: prefix. To reuse a known session, pass a session key or label:

• --session <key>: use a specific Gateway session key.
• --session-label <label>: resolve an existing session by label.
• --reset-session: mint a fresh session id for that key (same key, new transcript).

If your ACP client supports metadata, you can override per session:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

Learn more about session keys at /concepts/session.

Options

• --url <url>: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
• --token <token>: Gateway auth token.
• --token-file <path>: read Gateway auth token from file.
• --password <password>: Gateway auth password.
• --password-file <path>: read Gateway auth password from file.
• --session <key>: default session key.
• --session-label <label>: default session label to resolve.
• --require-existing: fail if the session key/label does not exist.
• --reset-session: reset the session key before first use.
• --no-prefix-cwd: do not prefix prompts with the working directory.
• --verbose, -v: verbose logging to stderr.

Security note:

• --token and --password can be visible in local process listings on some systems.
• Prefer --token-file/--password-file or environment variables (BOT_GATEWAY_TOKEN, BOT_GATEWAY_PASSWORD).
• ACP runtime backend child processes receive BOT_SHELL=acp, which can be used for context-specific shell/profile rules.
• hanzo-bot acp client sets BOT_SHELL=acp-client on the spawned bridge process.

acp client options

• --cwd <dir>: working directory for the ACP session.
• --server <command>: ACP server command (default: hanzo-bot).
• --server-args <args...>: extra arguments passed to the ACP server.
• --server-verbose: enable verbose logging on the ACP server.
• --verbose, -v: verbose client logging.