Extensions

Walrus Extensions — external processes that extend the daemon with memory, search, messaging, and custom capabilities.

OpenWalrus extends its daemon through extensions — external child processes that communicate via the Walrus Extension Protocol (protobuf over UDS). Official extensions for search and messaging ship alongside the daemon. Third-party extensions use the same protocol.

Extension kinds

Kind	Protocol	Direction	Use case
`extension`	ext.proto (UDS)	Daemon → extension	Search, custom tools
`gateway`	walrus.proto (TCP)	Service → daemon	Gateway (Telegram)

Official extensions

Extension	Crate	Kind	Capabilities
Search	`walrus-search`	extension	Tools
Telegram	`walrus-telegram`	gateway	Telegram bot

Configuration

Each extension is a [services.<name>] section in walrus.toml:

[services.search]
kind = "extension"
crate = "walrus-search"
enabled = true

Field	Type	Description	Default
`kind`	string	`"extension"` or `"gateway"`	`"extension"`
`crate`	string	Cargo package name (used as binary name)	Required
`restart`	string	`"never"`, `"on_failure"`, or `"always"`	`"never"`
`enabled`	bool	Whether to start this extension	`true`
`env`	map?	Environment variables for the child process	`{}`
`config`	table?	Opaque config passed as JSON at handshake	`{}`

Extension lifecycle

Spawn — daemon starts the extension process with socket path or daemon address
Handshake — extension declares its name and capabilities via ExtReady
Configure — daemon sends opaque config JSON, extension acknowledges
Register tools — extension declares tool schemas for agent use
Ready — tools are routed to the extension, lifecycle hooks fire as agents run
Shutdown — daemon sends ExtShutdown, extension exits gracefully

Capabilities

Extensions 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)
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 from the daemon

What's next

Gateway — Telegram setup
Search — meta search engine
Hooks — how in-process hooks and extensions compose
Configuration reference — [services.*] fields