Configuration Guide

How to configure Soothe — YAML settings, environment variables, and the design decisions behind them.

Configuration Philosophy

Soothe is built around progressive disclosure: a minimal config is enough to run, and advanced knobs only appear when you need them. Three layers stack on top of sane Pydantic-model defaults:

  1. YAML file — the source of truth for structured, version-controllable config.
  2. Environment variables — secrets and per-deployment overrides. Two distinct mechanisms: SOOTHE_* vars map onto config fields, while ${VAR} interpolation injects secrets into the YAML.
  3. CLI arguments — one-off runtime overrides (highest priority).

Priority (highest wins): CLI args > SOOTHE_* env vars > YAML file > built-in defaults.

This layering means you should keep structure in YAML and secrets/ephemeral values in the environment. Never hardcode API keys in config files — use ${VAR} interpolation (see Environment Variables).

File Discovery Order

Agent config uses a split layout:

File Role
nano.yml Providers, router, tools, persistence, security (nano-owned)
soothe.yml Optional host overlay (agent.loop, autopilot, cron, skillify)
daemon.yml Daemon transports / pools (separate model)

Soothe resolves the agent base file in this order:

  1. --config PATH / daemon --soothe-config — explicit path (typically nano.yml)
  2. SOOTHE_DAEMON_SOOTHE_CONFIG_PATH — daemon env override
  3. ~/.soothe/config/nano.yml — default user directory (compose sibling soothe.yml when present)
  4. config/develop/nano.yml — repository development default
  5. Built-in SootheConfig Pydantic defaults

When the path basename is nano.yml and soothe.yml sits beside it, both are composed. A single-file load accepts nano-owned keys only; host keys must live in soothe.yml.

Minimal Working Config

Zero-config (no file):

export OPENAI_API_KEY=sk-...
soothed start && soothe "Analyze this codebase"

Minimal nano.yml (multi-model routing or non-env secrets):

providers:
  - name: openai
    api_key: ${OPENAI_API_KEY}
    models: [gpt-4o-mini]

router_profiles:
  - name: default
    router:
      default: openai:gpt-4o-mini

active_router_profile: default

embedding_profile:
  - model_role: openai:text-embedding-3-small
    embedding_dims: 1536

Top-level router: was removed — use router_profiles + active_router_profile. Env-only model changes: SOOTHE_ROUTER_PROFILES (JSON) or SOOTHE_ACTIVE_ROUTER_PROFILE; see Environment Variables.

Templates ship as config/templates/nano.yml (nano-owned) and config/templates/soothe.yml (host overlay) — copy them rather than writing from scratch.

Documentation Map

Article What you’ll learn
Common Patterns Real-world recipes and the reasoning behind each one
Environment Variables SOOTHE_* mapping, ${VAR} interpolation gotchas, secret hygiene
Provider Setup Choosing LLM/embedding providers, model routing, persistence & vector stores
YAML Reference Condensed schema quick-reference (full schema lives in source)
Autonomous Mode 24/7 self-running agent tuning
Daemon Setup Multi-transport server configuration
Security Sandboxing, path policies, approval flows

Method Comparison

Method Best for Mutability
YAML file Complete, version-controlled config Low
Env vars Secrets, CI/CD, per-host overrides Medium
CLI args One-off overrides, testing High

Where the Schema Lives

The full, authoritative schema is defined in Pydantic models — not in these docs. When in doubt about a field’s type, default, or constraints, read the source:

  • packages/soothe/src/soothe/config/models.py — all nested config models (ModelProviderConfig, AgentConfig, PersistenceConfig, SecurityConfig, etc.)
  • packages/soothe/src/soothe/config/settings.py — top-level SootheConfig (env prefix, YAML loading, model validators)
  • packages/soothe/src/soothe/config/env.py — ${VAR} interpolation implementation

These wiki articles capture knowledge — design intent, decision guides, and pitfalls — that the source alone doesn’t surface. Treat them as a companion to, not a replacement for, the schema.

Next Steps

Table of contents