Skip to content

3.5. ACP Server

The Agent Communication Protocol (ACP) server lets Backend.AI GO act as a first-class ACP agent. ACP clients — such as the Zed editor — can connect to it via stdio and hand off tasks to your locally-running models and Cowork agent.

What is ACP?

ACP (Agent Communication Protocol) is an open standard for composing AI agents. Clients that speak ACP can delegate prompts and tool invocations to any compliant agent without custom integration code for each one.

Backend.AI GO implements the ACP server side: it receives requests from an ACP client, routes them through Cowork's reasoning loop (with your configured tools and permissions), and returns responses in the ACP envelope.

When to use the ACP server

  • You use the Zed editor and want it to use your local model instead of a cloud service.
  • You are building an ACP-aware application and want to test it against a local agent.
  • You want to offload agent tasks from a remote orchestrator to a local Backend.AI GO instance.

Enabling the ACP server

  1. Open Settings → ACP.
  2. Toggle Enable ACP Server on.
  3. (Optional) Select an Agent Profile — the profile determines the system prompt and the default permission policy for incoming ACP sessions.
  4. (Optional) Set a Default Model that ACP sessions will use when the client does not specify one.
  5. Click Start.

The status badge changes from Stopped to Running once the server is ready.

Profile selection

Choosing a profile is recommended. Without a profile, ACP sessions use the global ACP permission settings, which default to ask for most tool kinds. A profile lets you pre-approve the tools an ACP client is expected to call and avoids unnecessary permission prompts.

How ACP sessions work

When the ACP server is running it starts a continuum-router subprocess in --mode stdio. Each connecting ACP client gets its own session. Sessions are identified by a unique ID and share the permission configuration generated from the active profile (or from the ACP permission settings if no profile is selected).

Sessions are tracked in the Session Monitor section of Settings → ACP. You can see:

  • How many concurrent sessions are active.
  • Each session's ID, connected client name/version, creation time, last-activity time, prompt count, and tool-call count.

Permission model

The ACP permission model mirrors Cowork's tool-permission system. The relevant configuration keys are:

Key Type Description
default_policy ask | allow_all | allow_read Fallback policy when no kind or per-tool rule matches
auto_allow_kinds list of kind strings Tool kinds that run without a prompt (e.g. read, search, think)
always_ask_kinds list of kind strings Tool kinds that always require approval (e.g. edit, delete, execute)
tool_overrides map of tool name → policy Per-tool overrides; take precedence over kind-based rules

Policies resolve in this order (highest priority first):

  1. Per-tool override (from Settings → ACP → Permissions or from the selected profile).
  2. Kind-based restrictive policy (always_ask_kinds — checked first to prevent accidental bypass).
  3. Kind-based permissive policy (auto_allow_kinds).
  4. default_policy.

When a profile is active, its tool permission overrides are projected into the tool_overrides map so that the profile's intent is respected for every ACP session.

The acp-config.yaml file

The ACP server does not read a hand-authored YAML file. Instead, Backend.AI GO auto-generates acp-config.yaml at <app_data_dir>/acp-config.yaml when you click Start (if the file does not already exist). The generated file captures:

  • The resolved default_policy, auto_allow_kinds, and always_ask_kinds from your settings.
  • Any per-tool overrides derived from the selected profile.

You do not need to edit this file manually. When the file already exists, changes to ACP settings or the active profile take effect on the next Start (existing config is not auto-overwritten — restart after changing permissions to regenerate).

Default app data directory

Platform Path
macOS ~/Library/Application Support/ai.backend.go/
Windows %APPDATA%\ai.backend.go\
Linux ~/.local/share/ai.backend.go/

Session limits

Setting Range Default Description
Max concurrent sessions 1–100 10 Maximum number of simultaneous ACP sessions
Idle timeout 1–1 440 min 60 min Session is closed after this period without activity

Stopping the ACP server

Click Stop in Settings → ACP, or toggle Enable ACP Server off. Active sessions are terminated gracefully before the subprocess exits.

REST / headless usage

The ACP lifecycle is also available via the Management API for headless deployments:

Method Endpoint Description
GET /api/v1/acp/status Current server state and session count
POST /api/v1/acp/start Start the ACP server
POST /api/v1/acp/stop Stop the ACP server
POST /api/v1/acp/restart Stop then start
GET /api/v1/acp/settings Read current ACP settings
PUT /api/v1/acp/settings Update ACP settings
GET /api/v1/acp/sessions List active sessions

Authentication follows the same API-key rules as all other Management API endpoints. See API Server for details.

Troubleshooting

"ACP config file not found"

Symptom: Clicking Start shows the error ACP config file not found: <path>/acp-config.yaml.

Cause: Backend.AI GO generates acp-config.yaml automatically when you click Start. If the file cannot be written (for example, insufficient disk space or a read-only app data directory), the server cannot start.

Resolution:

  1. Go to Settings → ACP.
  2. Click Start — the config file is generated automatically on the first Start.
  3. If the error persists, verify that Backend.AI GO has write access to its app data directory (see Default app data directory above).

ACP server starts but clients cannot connect

  • Confirm the ACP server status badge shows Running in Settings → ACP.
  • Verify that your ACP client is configured to use the correct stdio command and arguments.
  • Check Settings → ACP → Session Monitor to see whether a session was created.
  • Review Backend.AI GO logs for startup errors from the continuum-router subprocess.

Server crashes immediately after start

  • Open Settings → ACP and look at the error message below the Start/Stop button.
  • Confirm that the continuum-router binary is present: run Setup → Check dependencies (or re-run the installer).
  • Check disk space in the app data directory — the YAML file must be writable.