Connecting a backend

This guide walks through adding an ACP backend to simse, verifying the connection, and configuring timeout settings. Examples use TUI slash commands — for headless mode, see the commands reference.

Prerequisites

• simse installed and in your PATH
• An ACP-compatible backend available as a local command (e.g., npx @anthropic-ai/claude-code)
• Any required API keys or credentials for the backend

Add a backend

Add a backend entry to ~/.config/simse/acp.json (macOS / Linux) or %APPDATA%\simse\acp.json (Windows):

{
  "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"
}

The name field sets a unique identifier for this server. You will use this name to reference the backend in other configuration and commands. The command and args fields define the local subprocess that simse spawns to communicate with the backend.

Verify the server

After adding a server, restart simse and verify it is reachable with /status in the TUI. A healthy server shows as "connected." If a server is unreachable, the status shows the error.

Configuration via acp.json

Servers are configured in ~/.config/simse/acp.json (macOS / Linux) or %APPDATA%\simse\acp.json (Windows):

{
  "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"
}

Changes to acp.json take effect on the next simse startup.

Timeout configuration

Setting	Default	Description
timeoutMs	60000 (60s)	Maximum time to wait for a response to any request

Increase timeouts for servers that are slow to respond in acp.json:

{
  "servers": [
    {
      "name": "anthropic",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/claude-code"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." },
      "timeoutMs": 120000
    }
  ]
}

Update a server

Edit the server entry in acp.json to update the command, args, environment, or other settings. Restart simse for changes to take effect.

Remove a server

Delete the server entry from the servers array in acp.json and restart simse. Existing sessions that used this server are unaffected -- their conversation history and context in the adaptive store remain intact.

Set a default server

When multiple servers are configured, set a default in acp.json:

{
  "defaultServer": "anthropic"
}

New sessions use the default server unless you switch to another configured server with /server in the TUI.