Agent Control Protocol (ACP)
ACP is the underlying protocol the Vyre CLI uses to communicate with the Vyre daemon. Use it to build custom integrations, IDE plugins, or automation tools that control Agent programmatically.
Protocol overview
ACP is a bidirectional JSON-over-WebSocket protocol. The Vyre daemon listens on a local socket (typically ~/.vyre/daemon.sock) and accepts ACP connections from local clients.
Most developers won't need to use ACP directly. Use the CLI or SDK instead. ACP is for tool builders who need the lowest-level access.
Local socket
The daemon exposes ACP over a Unix domain socket, not a network port. Communication stays on your machine.
JSON messages
All messages are newline-delimited JSON. Simple to implement in any language.
Bidirectional
Clients can send commands to the daemon and receive streaming events — agent progress, tool calls, errors.
Multiplexed
A single ACP connection can control multiple agent sessions simultaneously via session IDs.
Connecting to ACP
import socket
import json
# Connect to the daemon socket
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect('/Users/you/.vyre/daemon.sock')
# Authenticate
sock.sendall(json.dumps({
"type": "auth",
"token": "your-api-token"
}).encode() + b'\n')
response = json.loads(sock.recv(4096))
# {"type": "auth_ok", "version": "2.4.1"}Message types
Client → Daemon
// Start a new agent session
{"type": "agent.start", "session_id": "abc123", "task": "Refactor auth module", "model": "claude-sonnet-4-5"}
// Send a follow-up message to a running session
{"type": "agent.message", "session_id": "abc123", "content": "Also add rate limiting"}
// Stop a session
{"type": "agent.stop", "session_id": "abc123"}Daemon → Client
// Session started
{"type": "agent.started", "session_id": "abc123"}
// Tool called (streaming)
{"type": "agent.tool_call", "session_id": "abc123", "tool": "read_file", "input": {"path": "src/auth.ts"}}
// Tool result
{"type": "agent.tool_result", "session_id": "abc123", "tool": "read_file", "output": "...file content..."}
// Agent message (streaming text)
{"type": "agent.text", "session_id": "abc123", "delta": "I found the issue in line 42..."}
// Session complete
{"type": "agent.done", "session_id": "abc123", "success": true}Code examples
TypeScript client
import net from 'net';
const client = net.createConnection('/Users/you/.vyre/daemon.sock');
client.on('connect', () => {
// Authenticate
client.write(JSON.stringify({ type: 'auth', token: process.env.VYRE_TOKEN }) + '\n');
});
client.on('data', (data) => {
const lines = data.toString().split('\n').filter(Boolean);
for (const line of lines) {
const msg = JSON.parse(line);
if (msg.type === 'auth_ok') {
// Start an agent session
client.write(JSON.stringify({
type: 'agent.start',
session_id: 'my-session',
task: 'Review this PR and post inline comments'
}) + '\n');
}
if (msg.type === 'agent.done') {
console.log('Agent finished!');
client.end();
}
}
});