Run the Agent Client Protocol (ACP) bridge that talks to an Apus Gateway.

apus acp speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket, keeping ACP sessions mapped to Gateway session keys. It is a Gateway-backed ACP bridge, not a full ACP-native editor runtime: it focuses on session routing, prompt delivery, and streaming updates.

If you want an external MCP client to talk directly to Apus channel conversations instead of hosting an ACP harness session, use apus mcp serve instead.

What this is not

apus acp means Apus acts as an ACP server: an IDE or ACP client connects to Apus, and Apus forwards that work into a Gateway session.

This is different from ACP Agents, where Apus runs an external harness such as Codex or Claude Code through acpx.

Quick rule:

• editor/client wants to talk ACP to Apus: use apus acp
• Apus should launch Codex/Claude/Gemini as an ACP harness: use /acp spawn and ACP Agents

Compatibility matrix

Known limitations

• loadSession replays complete ACP event-ledger history only for bridge-created sessions. Older/no-ledger sessions use transcript fallback and do not reconstruct historic tool calls or system notices. Replay history is bounded by session, event, and retained-content limits; the default byte budget is 16 MiB of UTF-8 text plus row overhead. Truncated history also uses transcript fallback. See ACP replay accounting.
• If multiple ACP clients share the same Gateway session key, event and cancel routing are best-effort rather than strictly isolated per client. Prefer the default isolated acp-bridge:<uuid> sessions when you need clean editor-local turns.
• Gateway stop states translate into ACP stop reasons, but that mapping is less expressive than a fully ACP-native runtime.
• Session controls surface a focused subset of Gateway knobs: thought level, tool verbosity, reasoning, usage detail, and elevated actions. Model selection and exec-host controls are not exposed as ACP config options.
• session_info_update and usage_update derive from Gateway session snapshots, not live ACP-native runtime accounting. Usage is approximate, carries no cost data, and is only emitted when the Gateway marks total token data as fresh.
• Tool follow-along data is best-effort: the bridge surfaces file paths that appear in known tool args/results, but does not emit ACP terminals or structured file diffs.
• Exec approval relay is scoped to the active ACP prompt turn; approvals from other Gateway sessions are ignored.

Usage

apus acp

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

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

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

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

# Reset the session key before the first prompt
apus 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.

After a session is established, an unexpected server signal exit makes the client exit with status 1. An explicit exit or quit remains successful when it stops the server by signal. Numeric server exit codes are propagated, including a nonzero code returned during an explicit quit. Closing interactive input, including Ctrl-D at an empty prompt, uses the same client-owned shutdown path; it does not wait for an in-flight response to finish.

apus acp client

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

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

Permission model (client debug mode):

• Auto-approval is allowlist-based and applies only to trusted core tool IDs.
• read auto-approval is scoped to the current working directory (--cwd when set).
• ACP only auto-approves narrow readonly classes: scoped read calls under the active cwd, plus readonly search tools (search, web_search, memory_search). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
• Server-provided toolCall.kind is treated as untrusted metadata, not an authorization source.
• This ACP bridge policy is separate from ACPX harness permissions. If you run Apus through the acpx backend, plugins.entries.acpx.config.permissionMode=approve-all is the break-glass "yolo" switch for that harness session.

Protocol smoke testing

For protocol-level debugging, start a Gateway with isolated state and drive apus acp over stdio with an ACP JSON-RPC client. Cover initialize, session/new, session/list with an absolute cwd, session/resume, session/close, duplicate close, and missing resume.

The proof should include the advertised lifecycle capabilities, a Gateway-backed session row, update notifications, and the Gateway sessions.list log:

{
  "initialize": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "sessionCapabilities": {
        "list": {},
        "resume": {},
        "close": {}
      }
    }
  },
  "listSessions": {
    "sessions": [
      {
        "sessionId": "agent:main:acp-smoke",
        "cwd": "/path/to/workspace",
        "_meta": {
          "sessionKey": "agent:main:acp-smoke",
          "kind": "direct"
        }
      }
    ],
    "nextCursor": null
  },
  "notifications": ["session_info_update", "available_commands_update", "usage_update"],
  "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"]
}

Avoid using apus gateway call sessions.list as the only ACP proof. That CLI path may request a fresh-token operator scope upgrade; ACP bridge correctness is proven by ACP stdio frames plus the Gateway sessions.list log.

How to use this

Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive an Apus 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 apus acp over stdio.

Example config (persisted):

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

Example direct run (no config write):

apus acp --url wss://gateway-host:18789 --token <token>
# preferred for local process safety
apus acp --url wss://gateway-host:18789 --token-file ~/.apus/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:

apus acp --session agent:main:main
apus acp --session agent:design:main
apus 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-bridge:<uuid> session unless you override the key or label.

Per-session mcpServers are not supported in bridge mode. If an ACP client sends them during newSession or loadSession, the bridge returns a clear error instead of silently ignoring them.

If you want ACPX-backed sessions to see Apus plugin tools or selected built-in tools such as cron, enable the gateway-side ACPX MCP bridges instead of trying to pass per-session mcpServers. See ACP Agents and Apus tools MCP bridge.

Use from acpx (Codex, Claude, other ACP clients)

If you want a coding agent such as Codex or Claude Code to talk to your Apus bot over ACP, use acpx with its built-in apus target.

acpx here is the separate acpx CLI from npm, installed on the machine that runs the coding agent. It is not the same thing as the @openclaw/acpx Apus plugin described in ACP Agents, which embeds the ACP runtime in the Gateway and installs no acpx binary.

Typical flow:

1. Install the acpx CLI on the coding agent's machine and run the Gateway, making sure the ACP bridge can reach it.
2. Point acpx apus at apus acp.
3. Target the Apus session key you want the coding agent to use.

Examples:

# One-shot request into your default Apus ACP session
acpx apus exec "Summarize the active Apus session state."

# Persistent named session for follow-up turns
acpx apus sessions ensure --name codex-bridge
acpx apus -s codex-bridge --cwd /path/to/repo \
  "Ask my Apus work agent for recent context relevant to this repo."

If you want acpx apus to target a specific Gateway and session key every time, override the apus agent command in ~/.acpx/config.json:

{
  "agents": {
    "apus": {
      "command": "env APUS_HIDE_BANNER=1 APUS_SUPPRESS_NOTES=1 apus acp --url ws://127.0.0.1:18789 --token-file ~/.apus/gateway.token --session agent:main:main"
    }
  }
}

For a repo-local Apus checkout, use the direct CLI entrypoint instead of the dev runner so the ACP stream stays clean:

env APUS_HIDE_BANNER=1 APUS_SUPPRESS_NOTES=1 node apus.mjs acp ...

This is the easiest way to let Codex, Claude Code, or another ACP-aware client pull contextual information from an Apus agent without scraping a terminal.

Zed editor setup

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

{
  "agent_servers": {
    "Apus ACP": {
      "type": "custom",
      "command": "apus",
      "args": ["acp"],
      "env": {}
    }
  }
}

To target a specific Gateway or agent:

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

In Zed, open the Agent panel and select "Apus ACP" to start a thread.

Session mapping

By default, ACP bridge sessions get an isolated Gateway session key with an acp-bridge: prefix. These normal-model bridge sessions are synthetic and disposable: they are subject to stale-entry pruning and are not treated as protected human conversation surfaces. 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.
• --provenance <off|meta|meta+receipt>: include ACP provenance metadata or receipts.
• --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 (APUS_GATEWAY_TOKEN, APUS_GATEWAY_PASSWORD).
• Gateway auth resolution follows the shared contract used by other Gateway clients:
  • local mode: gateway.auth.* then env (APUS_GATEWAY_*), falling back to gateway.remote.* only when gateway.auth.* is unset (a configured-but-unresolved local SecretRef fails closed instead of silently falling back)
  • remote mode: gateway.remote.* with env/config fallback per remote precedence rules
  • --url is override-safe and does not reuse implicit config/env credentials; pass explicit --token/--password (or file variants)

acp client options

• --cwd <dir>: working directory for the ACP session.
• --server <command>: ACP server command (default: apus).
• --server-args <args...>: extra arguments passed to the ACP server.
• --server-verbose: enable verbose logging on the ACP server.
• --verbose, -v: verbose client logging.
• apus acp client sets APUS_SHELL=acp-client on the spawned bridge process, which can be used for context-specific shell/profile rules.

Related

• CLI reference
• ACP agents