Configuration Reference

Complete documentation for every config.yaml field

This document describes every configuration field in config.yaml. All settings have sensible defaults — you only need to override what you want to change.

Configuration loading order (each overrides the previous):

1. /etc/dolphin/config.yaml — system-wide
2. ~/.dolphin/config.yaml — per-user
3. .dolphin/config.yaml — per-project
4. -c <file> flag — explicit override
5. DZ_* environment variables

Tip: Use dolphin init to generate a commented default config file, or copy docs/en/config.example.yaml to .dolphin/config.yaml and edit.

LLM (llm)

Controls the LLM provider, model selection, and generation parameters.

Single-Provider Fields (Legacy)

These fields are used when providers is empty. They can also be set via DZ_LLM_* environment variables.

Multi-Provider (llm.providers)

When providers is configured, startup tries each entry in order with a health check and uses the first that responds. If a provider has an empty api_key, it inherits from llm.api_key (or DZ_LLM_API_KEY). Similarly, empty max_tokens inherits from llm.max_tokens.

llm:
  providers:
    - name: claude
      type: anthropic
      api_key: ""
      base_url: https://api.anthropic.com/v1
      model: claude-sonnet-4-6
    - name: deepseek
      type: openai
      api_key: ""
      base_url: https://api.deepseek.com/v1
      model: deepseek-v4-flash

Sessions (session)

Controls session persistence, auto-checkpoint, and cleanup.

MCP Tools (mcp)

Configures the Model Context Protocol tools available to the agent.

Shell (mcp.shell)

Executes shell commands.

CDP Browser (mcp.cdp)

Chrome DevTools Protocol — browser automation.

Email MCP (mcp.email)

Email send/search/fetch tool (requires transport.email to be configured separately).

Webhook MCP (mcp.webhook)

HTTP webhook tool for sending requests to external services.

mcp:
  webhook:
    targets:
      my_bot:
        url: "https://hooks.example.com/webhook"
        method: POST
        headers: {Authorization: "Bearer my-token"}

External MCP Servers (mcp.servers)

Connect to external MCP servers. Each key is a server name.

mcp:
  servers:
    my-server:
      type: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
    remote-server:
      type: sse
      url: "https://mcp.example.com/sse"
      headers: {Authorization: "Bearer token"}

MCP Repos (mcp.repos)

Agent Pool (agent_pool)

Controls concurrent sub-agent execution.

Skills (skills)

Manages skill files that teach the agent new capabilities.

Transports (transport)

Controls how the agent communicates: local terminal, SSH, MQTT, or email.

Stdio (transport.stdio)

Local terminal I/O.

SSH (transport.ssh)

Remote shell access.

MQTT (transport.mqtt)

MQTT messaging transport.

Email (transport.email)

Email transport — receives instructions and sends responses via SMTP/IMAP.

Crontab (crontab)

Scheduled task management.

Diary (diary)

Aggregates session summaries into a hierarchical diary (day → week → month → year).

Plugins (plugins)

Dolphin has two extension systems:

• Hook (sync) — intercepts the agent loop at specific points. At abortable points, returning an error aborts the flow.
• Event (async) — subscribes to notifications dispatched in the background. Delivered via webhook (HTTP POST) or JSONL log.

Both can be driven by script plugins in the plugins directory.

Available event types: session:created, session:ended, user:message, llm:response, tool:called, tool:completed, compression, error, heartbeat, agent:dispatched, agent:completed, skill:loaded.

Available hook points († = abortable): session:start, session:end, user:input†, llm:before†, llm:after, tool:before†, tool:after, response:before, error.

Each hook script receives the context as JSON on stdin and may return a modified JSON object on stdout.

# Example: audit all user input
plugins:
  dir: ~/.dolphin/plugins/
  webhook_url: "https://hooks.example.com/dolphin"
  webhook_events: ["tool:called", "tool:completed"]
  heartbeat_turns: 5

Observability

Pprof (pprof)

Go pprof profiling endpoints. For debugging performance issues.

Metrics (metrics)

Prometheus-style metrics endpoint.

Environment Variables

All settings can be overridden via DZ_-prefixed environment variables at runtime.

Restrictive Mode

Run dolphin init --restrictive to generate a security-hardened config:

• Shell: only allowlisted commands (ls, cat, grep, find, pwd, date, echo, head, tail, wc, sort, whoami, uname)
• CDP browser automation: disabled
• Webhook tool: disabled
• Log level: warn (reduces secret leakage in logs)
• Plugins: disabled