Configuration

Configure OpenWalrus — walrus.toml, directory structure, models, services, and MCP servers.

OpenWalrus is configured via a TOML file at ~/.openwalrus/walrus.toml. The daemon creates a default config on first run.

Directory structure

~/.openwalrus/
├── walrus.toml        # Main configuration
├── walrus.sock        # Unix domain socket
├── walrus.tcp         # TCP port file
├── agents/            # Agent definitions (*.md)
├── skills/            # Skill definitions
└── services/          # Service sockets

Configuration file

Daemon agent

The [walrus] section configures the default agent:

[walrus]
model = "deepseek"
thinking = false

Models

Each provider gets a [model.<name>] section:

[model.deepseek]
model = "deepseek-chat"
api_key = "${DEEPSEEK_API_KEY}"

[model.claude]
model = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"
api_standard = "anthropic"

Two API standards: openai (default) and anthropic. See providers for the full list.

Extensions

Extensions are managed child processes:

[services.telegram]
kind = "gateway"
crate = "walrus-telegram"
restart = "on_failure"
config = { telegram = { token = "..." } }

Two extension kinds: extension (Walrus Extension Protocol over UDS) and gateway (connects back to daemon). See extensions for details.

MCP servers

[mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

See MCP integration for details.

Agents

Define sub-agents in TOML (in addition to Markdown files in agents/):

[agents.researcher]
description = "Research specialist"
model = "claude"
max_iterations = 32
thinking = true
members = ["walrus"]

Environment variables

API keys can use environment variable references in the config:

api_key = "${DEEPSEEK_API_KEY}"

What's next

Extensions — search and gateway setup
Full config reference — every configuration field
CLI reference — all commands and flags

Configuration

On this page