ACP Support

The Agent Communication Protocol (ACP) enables inter-agent communication patterns, allowing opencode to coordinate with other AI agent runtimes. This is useful for multi-agent workflows, delegating subtasks, and integrating opencode into larger automation pipelines.

Starting the ACP Server

Launch the ACP server from the command line:

opencode acp

This starts the server using default settings, listening on stdin/stdout and communicating via newline-delimited JSON (nd-JSON).

Server Options

The ACP server supports several configuration flags:

Option	Default	Description
--cwd	Current directory	Working directory for the server
--port	Auto	TCP port for network mode
--hostname	localhost	Hostname to bind to
--mdns	Disabled	Enable mDNS discovery
--cors	Disabled	CORS headers for browser-based clients

Examples

Run with a custom working directory:

opencode acp --cwd /path/to/project

Run in TCP mode on a specific port:

opencode acp --port 8765

Enable mDNS for automatic discovery:

opencode acp --mdns --port 8765

Allow cross-origin requests from web-based agents:

opencode acp --cors --port 8765

Bind to all network interfaces:

opencode acp --hostname 0.0.0.0 --port 8765

Protocol

ACP communicates using newline-delimited JSON (nd-JSON) over stdin/stdout or TCP. Each line is a complete JSON message.

Message Format

{
  "type": "request",
  "id": "msg-001",
  "method": "execute_task",
  "params": {
    "task": "Review the error handling in src/main.rs",
    "context": {
      "cwd": "/home/user/project"
    }
  }
}

Response Format

{
  "type": "response",
  "id": "msg-001",
  "result": {
    "status": "completed",
    "output": "The error handling in src/main.rs uses proper Result types..."
  }
}

Error Format

{
  "type": "error",
  "id": "msg-001",
  "error": {
    "code": "TASK_FAILED",
    "message": "The specified file does not exist"
  }
}

Event Format

The server can push events to connected clients:

{
  "type": "event",
  "event": "status_update",
  "data": {
    "taskId": "task-42",
    "progress": 0.5,
    "message": "Analyzing dependencies..."
  }
}

Methods

The ACP server supports the following methods:

Method	Description
ping	Health check, returns pong
execute_task	Run a task and return results
cancel_task	Cancel a running task by ID
get_status	Query server status and capacity
list_capabilities	List available agent capabilities

execute_task Parameters

Param	Type	Required	Description
task	string	Yes	The task description
context	object	No	Execution context (cwd, environment)
timeout	number	No	Maximum execution time in seconds
tools	string[]	No	Restrict to specific tool categories

Example: Execute a Task

Request:

{"type":"request","id":"1","method":"execute_task","params":{"task":"Find all TODO comments in the codebase","context":{"cwd":"/repo"},"timeout":30}}

Response:

{"type":"response","id":"1","result":{"status":"completed","output":"Found 12 TODO comments:\n- src/main.rs:45: TODO: implement retry logic\n- src/lib.rs:12: TODO: add input validation\n..."}}

Use Cases

Multi-Agent Coordination

Run multiple opencode instances, each specializing in a different domain:

# Terminal 1: Backend agent
opencode acp --port 9001 --cwd /repo/backend

# Terminal 2: Frontend agent
opencode acp --port 9002 --cwd /repo/frontend

# Terminal 3: Orchestrator
opencode acp --port 9000

An orchestrator agent can delegate backend work to port 9001 and frontend work to port 9002, then synthesize results.

External Agent System Integration

Connect opencode to other ACP-compatible agent runtimes. This enables composing agents from different ecosystems into a unified workflow.

CI/CD Pipeline Integration

Embed opencode ACP in a CI pipeline to perform automated code analysis:

# In CI script
echo '{"type":"request","id":"1","method":"execute_task","params":{"task":"Review this PR diff for bugs"}}' | opencode acp --cwd $WORKSPACE

IDE Plugin Communication

An IDE plugin can communicate with opencode via ACP over a local TCP socket:

// IDE plugin sidecar
const socket = new WebSocket("ws://localhost:8765");
socket.send(JSON.stringify({
  type: "request",
  id: "ide-001",
  method: "execute_task",
  params: { task: "Refactor the selected function" }
}));

mDNS Discovery

When the --mdns flag is enabled, opencode advertises the ACP server on the local network using multicast DNS. Other ACP clients can discover the server automatically without manual address configuration.

opencode acp --mdns --port 8765

Clients on the same network can discover the server by querying for _opencode-acp._tcp.local service type.

Architecture

ACP follows a simple client-server model:

┌─────────────┐         nd-JSON          ┌──────────────┐
│  Agent A    │ ◄──────────────────────► │  Agent B     │
│  (Client)   │     stdin/stdout or TCP  │  (Server)    │
└─────────────┘                          └──────────────┘

• Server — The opencode acp process that listens for requests and executes tasks.
• Client — Any process that connects to the ACP server, sends requests, and receives responses.

Both roles can be opencode instances or any compatible agent runtime.

Troubleshooting

Server Won't Start

• Check that port is not already in use.
• Verify the working directory exists.
• For --mdns, ensure mDNS services are available on your system.

Connection Refused

• Confirm the server is running and listening on the expected port.
• Check firewall rules if using --hostname 0.0.0.0.
• Verify the client and server are on the same network for mDNS.

Task Timeouts

• Increase the timeout parameter for long-running tasks.
• Break complex tasks into smaller subtasks.
• Check system resource usage (CPU, memory).

Security Considerations

• ACP does not implement authentication by default. Use firewalls or SSH tunnels for network-mode deployments.
• The server executes tasks with the permissions of the user who started it.
• For production use, run the ACP server on a dedicated port with restricted access.
• Consider wrapping the ACP protocol with TLS for encrypted communication.
• Validate all incoming requests before processing, especially in multi-tenant environments.