ACP backends

simse connects to AI backends through ACP (Agent Client Protocol), an open protocol that standardizes how AI assistants communicate with backend models. Instead of hardcoding connections to specific vendors, simse speaks a protocol. Any backend that implements ACP v1 works immediately.

ACP handles the full session lifecycle: creating sessions, sending prompts, streaming responses, managing permissions for tool execution, and reporting tool call progress. When you switch backends, your context, tools, and session history remain intact.

Key concepts

Session lifecycle

ACP defines a clear session lifecycle:

1. session/new — Creates a new session on the backend. Returns a sessionId used for all subsequent calls.
2. session/prompt — Sends a message to the backend. The backend processes it and responds.
3. session/update — Streamed notifications from the backend during response generation. Contains partial content, tool call updates, and permission requests.

Permission flow

When the backend wants to execute a tool action, it sends a session/request_permission message. simse presents the request to the user (or auto-responds based on the configured permission mode) and replies with one of:

• allow_once — Permit this specific action
• allow_always — Permit this action type for the rest of the session
• reject_once — Deny this specific action
• reject_always — Deny this action type for the rest of the session

Tool call tracking

Tool calls follow their own lifecycle within a session:

1. tool_call — The backend requests a tool invocation. simse executes it.
2. tool_call_update with status in_progress — Execution is underway.
3. tool_call_update with status completed — Execution finished, result returned to the backend.

Timeout defaults

Timeout	Default	Config key
Request timeout	60 seconds	timeoutMs

Configurable per server in acp.json.

Protocol details

• Protocol version: 1
• Field naming: camelCase throughout (sessionId, stopReason, agentInfo)
• Transport: Local subprocess (stdio)

Backend compatibility

Any backend that implements ACP v1 works with simse. This includes:

• Self-hosted inference servers with ACP support
• Hosted API providers that support ACP
• Custom backends you build for your own models

The ACP specification is available at agentclientprotocol.com.

Adding a server

{
  "servers": [
    {
      "name": "anthropic",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-code"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." },
      "defaultAgent": "claude-sonnet-4-6",
      "timeoutMs": 60000
    }
  ],
  "defaultServer": "anthropic",
  "defaultAgent": "claude-sonnet-4-6"
}

See the Connecting a backend guide for the full setup process.