OpenWalrusWHS Services
Walrus Hook Services — external processes that extend the daemon with memory, search, messaging, and custom capabilities.
OpenWalrus extends its daemon through WHS (Walrus Hook Services) — external child processes that communicate via protobuf. Official services for memory, search, and messaging ship alongside the daemon. Third-party services use the same protocol.
Service kinds
| Kind | Protocol | Direction | Use case |
|---|---|---|---|
hook | whs.proto (UDS) | Daemon → service | Memory, search, custom tools |
client | walrus.proto (TCP) | Service → daemon | Gateway (Telegram, Discord) |
process | None | Managed subprocess | Arbitrary scripts |
Official services
| Service | Binary | Kind | Capabilities |
|---|---|---|---|
| Memory | walrus-memory | hook | Tools, BuildAgent, Compact, EventObserver |
| Search | walrus-search | hook | Tools |
| Gateway | wgateway | client | Telegram, Discord |
Configuration
Each service is a [services.<name>] section in walrus.toml:
[services.memory]
kind = "hook"
command = "walrus-memory"
enabled = true
config = { entities = ["project"], connections = 30 }| Field | Type | Description | Default |
|---|---|---|---|
kind | string | "hook", "client", or "process" | Required |
command | string | Binary to spawn | Required |
args | string[] | Command arguments | [] |
enabled | bool | Whether to start this service | true |
config | table? | Opaque config passed as JSON at handshake | {} |
Service lifecycle
- Spawn — daemon starts the service process with socket path or daemon address
- Handshake — service declares its name and capabilities via
WhsReady - Configure — daemon sends opaque config JSON, service acknowledges
- Register tools — service declares tool schemas for agent use
- Ready — tools are routed to the service, lifecycle hooks fire as agents run
- Shutdown — daemon sends
WhsShutdown, service exits gracefully
Capabilities
Services declare what they can do at handshake:
| Capability | Description |
|---|---|
| Tools | Provides tool schemas that agents can call |
| BuildAgent | Enriches agent config at creation (inject system prompt, override tools) |
| BeforeRun | Injects context before each agent execution |
| Compact | Enhances context compaction prompts |
| EventObserver | Observes agent lifecycle events (text deltas, tool calls, completions) |
| Query | Responds to structured queries from the daemon |
What's next
- Gateway — Telegram and Discord setup
- Memory — graph-based persistent memory
- Search — meta search engine
- Hooks — how in-process hooks and WHS services compose
- Configuration reference —
[services.*]fields