ACP (Agent Client Protocol)

ACP lets external tools interact with the CTOR agent over the Agent Client Protocol. You can use tools like acpx, OpenClaw, and Agmente to send prompts, manage sessions, and orchestrate agents — all powered by the same agent, settings, and MCP tools as the desktop GUI.

This page covers external tools connecting into CTOR’s built-in agent. For the reverse — CTOR driving Claude Code, Codex, Pi, or Cursor Agent as the agent behind a chat — see CLI Agents. A chat backed by a CLI agent can’t be driven over this bridge; see Using both ACP features together.

How it works

The desktop app runs a Unix socket server inside the Electron main process. The bridge CLI (bricks desktop-acp-bridge) pipes ACP JSON-RPC messages between stdin/stdout and the socket, so any ACP client can connect.

ACP client (acpx, OpenClaw, etc.)
  └─ spawns ─▶ bricks desktop-acp-bridge
                  └─ connects ─▶ Unix socket (~/.bricks-project-desktop/acp.sock)
                                    └─ CTOR (shared agent)

Because the socket server runs inside the app, ACP sessions share everything with the GUI:

Sessions — conversations created via ACP appear in the sidebar and vice versa
Settings — API keys, default model, and provider config come from the app
MCP tools — .mcp.json tools configured in the project are available
Skills — global and project skills are loaded

Session APIs

In addition to session/new and session/prompt, the bridge supports:

session/list — enumerate sessions on disk, filterable by project cwd
session/load and session/resume — reopen an existing session and stream the full tool-call and message timeline so the client can rebuild state after a refresh or restart
session/set_mode — switch the thinking level (off, minimal, low, medium, high, xhigh, max)
session/set_model and session/set_config_option — change the model mid-session using the same provider::name identifiers the desktop GUI exposes

While a session is active, every connected client receives the same event stream — prompts started from the GUI are mirrored to ACP clients in real time, and ACP prompts appear in the GUI as they stream.

Enable ACP

ACP is disabled by default. To enable it:

Open Settings (gear icon in the sidebar)
Go to Agent
Toggle Enable ACP

The socket server starts immediately — no app restart needed. A green ACP indicator appears in the sidebar footer when ACP is active. Click it to open Settings.

Bash commands run without approval in ACP mode (headless). Use acpx --deny-all to override this if needed.

Prerequisites

CTOR is running with ACP enabled
BRICKS CLI is installed (bun add -g @fugood/bricks-cli)
The working directory is a BRICKS project (contains application.json)

Verify the connection

Test that the bridge can reach the desktop app:

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{},"clientInfo":{"name":"test"}}}' \
  | bricks desktop-acp-bridge

If you see Cannot connect to CTOR, make sure the app is running and ACP is enabled in Settings.

Use with acpx

acpx is a headless CLI client for the Agent Client Protocol. It manages sessions, queues prompts, and streams agent output.

Install acpx

npm install -g acpx

Basic usage

# Create a session in the current project
acpx --agent 'bricks desktop-acp-bridge' sessions new

# Send a prompt
acpx --agent 'bricks desktop-acp-bridge' "list all files and summarize the project"

# Auto-approve all tool calls
acpx --agent 'bricks desktop-acp-bridge' --approve-all "fix the linting errors"

# Quiet mode (final output only)
acpx --agent 'bricks desktop-acp-bridge' --format quiet "what does this project do?"

# JSON output for automation
acpx --agent 'bricks desktop-acp-bridge' --format json "run the tests"

Persistent config

Add the agent to ~/.acpx/config.json to avoid repeating --agent:

{
  "agents": {
    "bricks": {
      "command": "bricks desktop-acp-bridge"
    }
  }
}

Then use the short form:

acpx bricks sessions new
acpx bricks "refactor the auth module"
acpx bricks sessions list
acpx bricks sessions close

Use with OpenClaw

OpenClaw supports ACP via acpx. With the bricks agent configured in ~/.acpx/config.json (see above), OpenClaw can connect to the desktop app’s agent for multi-agent orchestration.

WebSocket bridge

For ACP clients that speak WebSocket instead of stdio — including browser-based clients and the Agmente iOS app — run the bridge in --ws mode. Each WebSocket client opens its own dedicated connection to the ACP Unix socket; one WebSocket text frame equals one JSON-RPC message.

# Expose on the LAN (default) with a required token — recommended
bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"

# Token can also come from the environment
BRICKS_DESKTOP_ACP_BRIDGE_TOKEN="$ACP_TOKEN" bricks desktop-acp-bridge --ws

# Restrict to localhost only
bricks desktop-acp-bridge --ws --host 127.0.0.1 --port 8765

The default bind host is 0.0.0.0 — --ws is intended for LAN exposure. Always set --auth-token and only run on trusted networks. Without a token, any client reachable on the bound interface can connect, and the bridge prints a warning at startup.

Connect from a browser-style client by including the token on the upgrade request:

const ws = new WebSocket('ws://127.0.0.1:8765', [], {
  headers: { Authorization: `Bearer ${token}` },
})
ws.onmessage = (e) => console.log('from acp:', e.data)
ws.send(JSON.stringify({ jsonrpc: '2.0', id: 0, method: 'initialize', params: { /* ... */ } }))

Use with Agmente

Agmente is an iOS ACP client that lets you talk to the CTOR agent from your iPhone or iPad. It connects over WebSocket, so use the WebSocket bridge above to expose the ACP socket on the LAN:

bricks desktop-acp-bridge --ws --port 8765 --auth-token "$ACP_TOKEN"

In Agmente, point the agent connection at ws://<your-mac-ip>:8765 and supply the token. The phone and the Mac running CTOR must be on the same network — or reachable via VPN or a tunnel such as Tailscale. Once connected, Agmente uses the session APIs above to list past sessions, resume them, and switch model or thinking level on the fly. Prompts you send from Agmente also stream into the desktop GUI, and vice versa.

Copy project path

Use Actions (top-right dropdown) > Copy Project Path to quickly copy the current project’s path for use with external tools.

Data

Item	Location
Socket file	`~/.bricks-project-desktop/acp.sock`

Set the BRICKS_PROJECT_DESKTOP_DATA_DIR environment variable to change the socket location along with all other app data.

Getting started

Working with projects

Ship your app

Reference

Changelog

ACP (Agent Client Protocol)

How it works

Session APIs

Enable ACP

Prerequisites

Verify the connection

Use with acpx

Install acpx

Basic usage

Persistent config

Use with OpenClaw

WebSocket bridge

Use with Agmente

Copy project path

Data

​How it works

​Session APIs

​Enable ACP

​Prerequisites

​Verify the connection

​Use with acpx

​Install acpx

​Basic usage

​Persistent config

​Use with OpenClaw

​WebSocket bridge

​Use with Agmente

​Copy project path

​Data

How it works

Session APIs

Enable ACP

Prerequisites

Verify the connection

Use with acpx

Install acpx

Basic usage

Persistent config

Use with OpenClaw

WebSocket bridge

Use with Agmente

Copy project path

Data