Configuration Reference
Complete walrus.toml reference — daemon config, models, services, MCP servers, agents, tasks, and permissions.
The OpenWalrus daemon is configured via ~/.openwalrus/walrus.toml. This page documents every available field.
Full example
# Daemon agent config
[walrus]
model = "claude"
thinking = false
# Embedding model (optional)
[model]
embedding = "text-embedding-3-small"
# Provider definitions
[model.deepseek]
model = "deepseek-chat"
api_key = "${DEEPSEEK_API_KEY}"
[model.claude]
model = "claude-opus-4-6"
api_key = "${ANTHROPIC_API_KEY}"
api_standard = "anthropic"
[model.gpt-4o]
model = "gpt-4o"
api_key = "${OPENAI_API_KEY}"
# Extensions
[services.search]
kind = "extension"
crate = "walrus-search"
enabled = true
[services.telegram]
kind = "gateway"
crate = "walrus-telegram"
restart = "on_failure"
config = { telegram = { token = "${TELEGRAM_BOT_TOKEN}" } }
# MCP servers
[mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
[mcps.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
# Sub-agents
[agents.researcher]
description = "Research specialist"
model = "claude"
max_iterations = 32
thinking = true
members = ["walrus"]
skills = ["web_search", "file_analysis"]
mcps = ["github"]
# Task concurrency
[tasks]
max_concurrent = 4
viewable_window = 16
task_timeout = 300
# Tool permissions
[permissions]
bash = "ask"
write = "deny"
[permissions.researcher]
bash = "allow"
write = "allow"walrus
The daemon's own agent configuration:
| Field | Type | Description | Default |
|---|---|---|---|
model | string | Default model name (must match a [model.*] key) | — |
thinking | bool | Enable reasoning mode | false |
heartbeat.interval | u64 | Minutes between auto-runs (0 = disabled) | 0 |
heartbeat.prompt | string | Message sent on each tick | — |
model
model (top-level)
| Field | Type | Description |
|---|---|---|
embedding | string? | Default embedding model name |
model.<name>
Each remote provider is a [model.<name>] section:
| Field | Type | Description |
|---|---|---|
model | string | Model identifier sent to the API |
api_key | string? | API key (supports ${ENV_VAR} syntax) |
api_standard | string? | "openai" (default) or "anthropic" |
base_url | string? | Custom API endpoint |
See providers for API standard details and auto-detection.
services.<name>
Managed child processes for extensions:
| 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? | Extension-specific configuration (passed as JSON) | {} |
mcps.<name>
| Field | Type | Description | Default |
|---|---|---|---|
command | string | Command to start the MCP server | Required |
args | string[] | Command arguments | [] |
env | map? | Environment variables for the server process | {} |
agents.<name>
Sub-agent definitions (can also use Markdown files in ~/.openwalrus/agents/):
| Field | Type | Description | Default |
|---|---|---|---|
description | string | Human-readable description | — |
model | string? | Model name | walrus default |
max_iterations | usize | Maximum tool-use rounds | 16 |
thinking | bool | Enable reasoning mode | false |
heartbeat.interval | u64 | Minutes between ticks (0 = disabled) | 0 |
heartbeat.prompt | string | Message sent on each tick | — |
members | string[] | Agents this agent can delegate to | [] |
skills | string[] | Allowed skills (empty = all) | [] |
mcps | string[] | Allowed MCP servers (empty = all) | [] |
See agents for full details.
tasks
Configure agent delegation:
| Field | Type | Description | Default |
|---|---|---|---|
task_timeout | u64 | Per-task timeout in seconds | 300 |
permissions
Control tool access per tool and per agent:
# Global defaults
[permissions]
bash = "ask" # Block and prompt user
write = "deny" # Reject outright
# Per-agent overrides
[permissions.researcher]
bash = "allow"
read = "allow"Three levels: allow (default), ask (block task for user approval), deny (reject with error).
Resolution order: agent override > global default > allow.
Environment variables
API keys and tokens support ${ENV_VAR} syntax. The daemon resolves these from your shell environment at startup.
What's next
- CLI reference — commands and flags
- Configuration guide — getting started with config
- Extensions — extension setup and lifecycle
- Permissions — permission layer details
- Providers — model provider configuration