Techcle Wiki

Acp Protocol

5 min read

ACP (Agent Client Protocol) Documentation

Status: TO BE DISCOVERED
OpenCode Version: TBD
Last Updated: 2026-02-12

Overview

This document will contain the technical specification of OpenCode’s Agent Client Protocol (ACP) after discovery phase.

Discovery Checklist

1. Start ACP Server

# Terminal 1: Start server
opencode acp --port 3333 --print-logs --log-level DEBUG
 
# Note:
# - What port does it bind to?
# - What logs appear on startup?
# - Does it require authentication?
# - What's the process lifetime behavior?

2. HTTP Endpoints Discovery

# Try common REST patterns
curl -v http://localhost:3333/
curl -v http://localhost:3333/sessions
curl -v http://localhost:3333/health
curl -v http://localhost:3333/version
curl -v http://localhost:3333/api/sessions
 
# Try creating a session
curl -v -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{
<<<<<<< HEAD
    "project": "/workspace/projects/test",
=======
    "project": "${WORKSPACE_ROOT}/repos/test",
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
    "model": "anthropic/claude-sonnet-4"
  }'
 
# Document:
# - Base URL structure
# - All available endpoints
# - Request/response formats
# - Status codes
# - Error responses

3. WebSocket Discovery

# Install wscat if needed: npm install -g wscat
 
# Try connecting
wscat -c ws://localhost:3333
wscat -c ws://localhost:3333/stream
wscat -c ws://localhost:3333/sessions/<ID>/stream
 
# After connecting, try sending:
# { "type": "ping" }
# { "type": "subscribe", "session_id": "<ID>" }
 
# Document:
# - WebSocket endpoint path(s)
# - Connection handshake
# - Message format (JSON? Protocol Buffers?)
# - Event types (file_changed, message, etc.)
# - Heartbeat/ping-pong mechanism

4. Session Lifecycle

# Create session (via HTTP discovered above)
SESSION_ID=$(curl -s ... | jq -r '.session_id')
 
# Try operations:
# - Send message to session
curl -X POST http://localhost:3333/sessions/$SESSION_ID/messages \
  -H 'Content-Type: application/json' \
  -d '{"content": "List files in the project"}'
 
# - Get session status
curl http://localhost:3333/sessions/$SESSION_ID
 
# - List all sessions
curl http://localhost:3333/sessions
 
# - Terminate session
curl -X DELETE http://localhost:3333/sessions/$SESSION_ID
 
# Document:
# - Full CRUD operations for sessions
# - Message sending mechanics
# - How to check status/progress
# - Session persistence (survive server restart?)

5. opencode web Comparison

# Terminal 2: Try web mode instead
opencode web --port 3334
 
# Then in Terminal 3:
# Try same curl commands against port 3334
# Questions:
# - Does `opencode web` expose same ACP endpoints?
# - Or is ACP only in `opencode acp` mode?
# - Can you use both simultaneously?

6. Authentication & Security

# Check if auth is required
curl http://localhost:3333/sessions
# Does it return 401/403? Or allow unauthenticated access?
 
# Try with Authorization header
curl -H 'Authorization: Bearer fake-token' http://localhost:3333/sessions
 
# Check CORS
curl -H 'Origin: http://example.com' \
     -H 'Access-Control-Request-Method: POST' \
     -X OPTIONS http://localhost:3333/sessions
 
# Document:
# - Auth mechanism (bearer token? API key? none?)
# - CORS policy (what origins allowed?)
# - Rate limiting (if any)

7. Error Handling

# Trigger errors deliberately:
# - Invalid session ID
curl http://localhost:3333/sessions/invalid-id-999
 
# - Malformed request
curl -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d 'not valid json'
 
# - Missing required fields
curl -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
  -d '{}'
 
# Document:
# - Error response format
# - HTTP status codes used
# - Error codes/types
# - Helpful error messages?

Protocol Specification

Base URL

http://<hostname>:<port>/

Default: http://127.0.0.1:<random-port> (determined at startup)

HTTP Endpoints

GET /

Description: (TBD)

Response:

(TBD after discovery)

GET /sessions

Description: List all sessions

Response:

(TBD)

POST /sessions

Description: Create new session

Request:

(TBD)

Response:

(TBD)

GET /sessions/:id

Description: Get session details

Response:

(TBD)

POST /sessions/:id/messages

Description: Send message to session

Request:

(TBD)

Response:

(TBD)

DELETE /sessions/:id

Description: Terminate session

Response:

(TBD)

WebSocket Protocol

Connection

ws://<hostname>:<port>/...

Path: (TBD after discovery)

Message Format

(TBD)

Event Types

agent.message

(TBD)

agent.file_changed

(TBD)

agent.command_run

(TBD)

(More event types TBD)

Authentication

(TBD after discovery)

  • Method: Bearer token? API key? None?
  • Header format: Authorization: ...
  • How to obtain token?
  • Token expiration?

Error Responses

(TBD after discovery)

Standard Error Format

{
  "error": {
    "code": "...",
    "message": "..."
  }
}

Common Errors

  • SESSION_NOT_FOUND: …
  • INVALID_REQUEST: …
  • (More TBD)

Rate Limiting

(TBD after discovery)

  • Limits per endpoint?
  • Rate limit headers?
  • 429 Too Many Requests handling?

Versioning

(TBD after discovery)

  • Is ACP versioned?
  • How to negotiate version?
  • Backward compatibility guarantees?

Examples

Complete Flow Example

(After discovery, add step-by-step example)

# 1. Start server
opencode acp --port 3333
 
# 2. Create session
SESSION_ID=$(curl -s -X POST http://localhost:3333/sessions \
  -H 'Content-Type: application/json' \
<<<<<<< HEAD
  -d '{"project": "/workspace/test", "model": "..."}' \
=======
  -d '{"project": "${WORKSPACE_ROOT}/repos/test", "model": "..."}' \
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
  | jq -r '.session_id')
 
# 3. Connect WebSocket
wscat -c ws://localhost:3333/sessions/$SESSION_ID/stream
 
# 4. Send message
curl -X POST http://localhost:3333/sessions/$SESSION_ID/messages \
  -H 'Content-Type: application/json' \
  -d '{"content": "List files"}'
 
# 5. Observe events on WebSocket
# (events appear here)
 
# 6. Check status
curl http://localhost:3333/sessions/$SESSION_ID
 
# 7. Terminate
curl -X DELETE http://localhost:3333/sessions/$SESSION_ID

Open Questions

  • Does opencode web expose ACP endpoints?
  • How does session persistence work? Disk? Memory only?
  • Can multiple clients connect to same session?
  • What happens if ACP server restarts? Sessions lost?
  • Is there a bulk operations endpoint?
  • How to specify model/agent per session?
  • Permission approval flow: how does it work in ACP?
  • Are there WebHooks for long-running operations?
  • How to paginate session lists?
  • Export/import session format?

Next Steps

  1. Run Discovery: Execute checklist above, document findings
  2. Update This Document: Fill in TBD sections with actual protocol details
  3. Create Test Suite: Automated tests against real ACP server
  4. Build Client Library: Implement protocol in TypeScript/Node.js
  5. Integration: Wire into OpenClaw tool system

References

NOTE: This document is a template. It MUST be filled in during Phase 0 (Discovery) before proceeding with implementation.

Graph View