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

Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an DaoCore 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.

`daocore acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
runtime. It focuses on session routing, prompt delivery, and basic streaming
updates.

If you want an external MCP client to talk directly to DaoCore channel
conversations instead of hosting an ACP harness session, use
[`daocore mcp serve`](/cli/mcp) instead.

## What this is not

This page is often confused with ACP harness sessions.

`daocore acp` means:

- DaoCore acts as an ACP server
- an IDE or ACP client connects to DaoCore
- DaoCore forwards that work into a Gateway session

This is different from [ACP Agents](/tools/acp-agents), where DaoCore runs an
external harness such as Codex or Claude Code through `acpx`.

Quick rule:

- editor/client wants to talk ACP to DaoCore: use `daocore acp`
- DaoCore should launch Codex/Claude/Gemini as an ACP harness: use `/acp spawn` and [ACP Agents](/tools/acp-agents)

## Compatibility Matrix

| ACP area                                                              | Status      | Notes                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize`, `newSession`, `prompt`, `cancel`                        | Implemented | Core bridge flow over stdio to Gateway chat/send + abort.                                                                                                                                                                                        |
| `listSessions`, slash commands                                        | Implemented | Session list works against Gateway session state with bounded cursor pagination and `cwd` filtering where Gateway session rows carry workspace metadata; commands are advertised via `available_commands_update`.                                |
| Session lineage metadata                                              | Implemented | Session listings and session info snapshots include DaoCore parent and child lineage in `_meta` so ACP clients can render subagent graphs without private Gateway side channels.                                                                 |
| `resumeSession`, `closeSession`                                       | Implemented | Resume rebinds an ACP session to an existing Gateway session without replaying history. Close cancels active bridge work, resolves pending prompts as cancelled, and releases bridge session state.                                              |
| `loadSession`                                                         | Partial     | Rebinds the ACP session to a Gateway session key and replays ACP event-ledger history for bridge-created sessions. Older/no-ledger sessions fall back to stored user/assistant text.                                                             |
| Prompt content (`text`, embedded `resource`, images)                  | Partial     | Text/resources are flattened into chat input; images become Gateway attachments.                                                                                                                                                                 |
| Session modes                                                         | Partial     | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. |
| Session info and usage updates                                        | Partial     | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh.                                        |
| Tool streaming                                                        | Partial     | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed.                        |
| Exec approvals                                                        | Partial     | Gateway exec approval prompts during active ACP prompt turns are relayed to the ACP client with `session/request_permission`.                                                                                                                    |
| Per-session MCP servers (`mcpServers`)                                | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the DaoCore gateway or agent instead.                                                                                                                                      |
| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods.                                                                                                                                                                                          |
| Client terminal methods (`terminal/*`)                                | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls.                                                                                                                                                       |
| Session plans / thought streaming                                     | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates.                                                                                                                                                         |

## Known Limitations

- `loadSession` can replay complete ACP event-ledger history only for
  bridge-created sessions. Older/no-ledger sessions still use transcript
  fallback and do not reconstruct historic tool calls or system notices.
- 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:<uuid>` sessions when you need clean editor-local
  turns.
- Gateway stop states are translated into ACP stop reasons, but that mapping is
  less expressive than a fully ACP-native runtime.
- Initial session controls currently 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 yet exposed as ACP
  config options.
- `session_info_update` and `usage_update` are derived 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 can surface file paths that
  appear in known tool args/results, but it does not yet 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

```bash
daocore acp

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

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

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

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

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

```bash
daocore acp client

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

# Override the server command (default: daocore)
daocore acp client --server "node" --server-args daocore.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).
- 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 DaoCore 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
`daocore 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:

```json
{
  "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 `daocore 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 DaoCore 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 `daocore acp` over stdio.

Example config (persisted):

```bash
daocore config set gateway.remote.url wss://gateway-host:18789
daocore config set gateway.remote.token <token>
```

Example direct run (no config write):

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

```bash
daocore acp --session agent:main:main
daocore acp --session agent:design:main
daocore 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.

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 DaoCore 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](/tools/acp-agents-setup#plugin-tools-mcp-bridge) and
[DaoCore tools MCP bridge](/tools/acp-agents-setup#daocore-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
DaoCore bot over ACP, use `acpx` with its built-in `daocore` target.

Typical flow:

1. Run the Gateway and make sure the ACP bridge can reach it.
2. Point `acpx daocore` at `daocore acp`.
3. Target the DaoCore session key you want the coding agent to use.

Examples:

```bash
# One-shot request into your default DaoCore ACP session
acpx daocore exec "Summarize the active DaoCore session state."

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

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

```json
{
  "agents": {
    "daocore": {
      "command": "env DAOCORE_HIDE_BANNER=1 DAOCORE_SUPPRESS_NOTES=1 daocore acp --url ws://127.0.0.1:18789 --token-file ~/.daocore/gateway.token --session agent:main:main"
    }
  }
}
```

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

```bash
env DAOCORE_HIDE_BANNER=1 DAOCORE_SUPPRESS_NOTES=1 node daocore.mjs acp ...
```

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

## Zed editor setup

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

```json
{
  "agent_servers": {
    "DaoCore ACP": {
      "type": "custom",
      "command": "daocore",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

To target a specific Gateway or agent:

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

In Zed, open the Agent panel and select "DaoCore 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:

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

Learn more about session keys at [/concepts/session](/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 (`DAOCORE_GATEWAY_TOKEN`, `DAOCORE_GATEWAY_PASSWORD`).
- Gateway auth resolution follows the shared contract used by other Gateway clients:
  - local mode: env (`DAOCORE_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
  - 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 runtime backend child processes receive `DAOCORE_SHELL=acp`, which can be used for context-specific shell/profile rules.
- `daocore acp client` sets `DAOCORE_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: `daocore`).
- `--server-args <args...>`: extra arguments passed to the ACP server.
- `--server-verbose`: enable verbose logging on the ACP server.
- `--verbose, -v`: verbose client logging.

## Related

- [CLI reference](/cli)
- [ACP agents](/tools/acp-agents)
