Protocol

OpenWalrus uses a Unix domain socket for communication between the CLI and the daemon.

Transport

The daemon listens on a Unix socket at ~/.openwalrus/walrus.sock. The CLI connects to this socket to send messages and receive streaming responses.

walrus attach ──→ walrus.sock ──→ walrus daemon

You can override the socket path:

walrus --socket /path/to/custom.sock attach

Protocol version

Current version: 0.1

Client/Server traits

The protocol defines two traits:

Client

Used by walrus attach and other CLI commands:

• Send chat messages to agents
• Stream responses (text deltas, tool calls, completions)
• Request agent information

Server

Implemented by the daemon:

• Accept incoming connections
• Route messages to the event loop
• Stream agent events back to the client

Wire format

Messages are serialized using the codec in walrus-socket. The connection uses a framed protocol over the Unix socket with length-prefixed messages.

Connection pool

WalrusClient maintains a connection pool for efficient communication. Multiple CLI sessions can connect to the same daemon simultaneously.

Building on the protocol

If you're building a custom frontend for OpenWalrus, you can connect directly to the Unix socket using the walrus-socket crate:

use walrus_socket::WalrusClient;

let client = WalrusClient::connect("/path/to/walrus.sock").await?;

What's next

• CLI reference — commands that use the protocol
• Event loop — how the daemon processes messages
• Runtime — agent management on the server side