OpenWalrusProtocol
The OpenWalrus wire protocols — walrus.proto for clients, ext.proto for extensions, dual UDS and TCP transport.
OpenWalrus uses two protobuf protocols over two transports. Clients (CLI, gateway) speak walrus.proto. Extensions (memory, search) speak ext.proto.
Two protocols
walrus.proto (client-daemon)
Used by walrus attach, the gateway service, and custom clients:
- Send chat messages to agents
- Stream responses (text deltas, tool calls, completions)
- Manage sessions, config, and agent state
ext.proto (daemon-extension)
Used by extensions (walrus-search, custom extensions):
- Capability handshake at startup
- Tool schema registration
- Tool call dispatch and results
- Lifecycle callbacks (BuildAgent, BeforeRun, Compact, EventObserver, AfterRun, Infer, AfterCompact)
Transport
Unix domain socket
The daemon listens on ~/.openwalrus/walrus.sock. The CLI connects to this socket by default:
walrus attach ──→ walrus.sock ──→ walrus daemonOverride the socket path:
walrus --socket /path/to/custom.sock attachTCP
The daemon also listens on TCP (localhost by default). The port is written to ~/.openwalrus/walrus.tcp:
walrus attach --tcpTCP is used by the gateway service and enables remote connections.
Extension kinds
| Kind | Protocol | Direction | Example |
|---|---|---|---|
extension | ext.proto (UDS) | Daemon → extension | walrus-search |
gateway | walrus.proto (TCP) | Service → daemon | walrus-telegram |
Capabilities handshake
Extensions declare capabilities at startup via ExtReady:
| Capability | Description |
|---|---|
| Tools | Provides tool schemas that agents can call |
| BuildAgent | Enriches agent config at creation |
| BeforeRun | Injects context before each agent execution |
| Compact | Enhances context compaction prompts |
| EventObserver | Observes agent lifecycle events |
| AfterRun | Runs after each agent execution completes |
| Infer | Requests LLM inference from the daemon |
| AfterCompact | Runs after context compaction completes |
| Query | Responds to structured queries |
Wire format
Both protocols use length-prefixed protobuf 3 frames over the transport. The walrus-socket and walrus-tcp crates handle framing and codec.
Building on the protocol
Connect directly 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
- Extensions — extension architecture and lifecycle
- Hooks — how hooks compose with extensions