Configuration Reference

This page is the reference for config.yaml, organized under the Three Enriches — settings (simple), configurations (power user), and options (developer). For the conceptual overview, see The Three Enriches.

The source of truth is internal/config/config.go. If anything on this page contradicts the Go types in that file, trust the Go types.

File Location

AI Butler reads ~/.aibutler/config.yaml. You can override the path with the AIBUTLER_CONFIG environment variable. If no config file exists, sensible defaults are used and AI Butler starts in single-user local mode.

Top-Level Structure

settings:         # tier 1 — simple, for everyone
configurations:   # tier 2 — power-user structure
options:          # tier 3 — developer tunables

`settings`

settings:
  language: en                      # UI language (ISO 639-1)
  timezone: Europe/Madrid           # IANA timezone
  notifications: true
  morning_briefing: "07:00"         # time of day, or empty to disable
  active_channels:                  # channels to activate at startup
    - webchat
    - telegram
  model: claude                     # top-level model provider alias
  persona_name: "Butler"
  skills: []                        # skill IDs to load
  agents_enabled: true              # enable specialist agents
  agent_mode: swarm                 # single | multi | swarm | custom | auto
  cost:
    strategy: balanced              # frugal | balanced | quality
    monthly_budget: 25              # USD
  offline_mode: false
  telemetry_enabled: false

`configurations`

`configurations.models`

configurations:
  models:
    primary: claude-sonnet-4-6
    fallback: claude-haiku-4-5

`configurations.channels`

Per-channel toggles. The channel is activated only if it appears in settings.active_channels AND the required credentials are in the vault.

configurations:
  channels:
    telegram:
      enabled: true
      typing_indicators: true
      voice_response: auto          # text | voice | auto | both
    slack:
      enabled: true
      typing_indicators: true
      voice_response: text

`configurations.agents`

configurations:
  agents:
    max_concurrent: 5
    max_depth: 4
    default_subagent_model: claude-haiku-4-5
    routing: classify               # classify | explicit | round-robin
    custom_roles:
      - name: reviewer
        description: "Code review specialist"
        model: claude-opus-4-6
        tools: [file.read, file.search, git.diff, git.log]
        system_prompt: "You are a careful code reviewer..."

`configurations.security.shell`

configurations:
  security:
    shell:
      mode: allowlist               # allowlist | denylist
      allowed:
        - ls
        - cat
        - grep
        - go
        - git

`configurations.cost`

configurations:
  cost:
    alerts: [50, 80, 100]           # % of budget
    alert_channel: telegram
    on_budget_reached: warn         # warn | pause

`configurations.web`

configurations:
  web:
    port: 3377
    bind_address: 0.0.0.0
    max_upload_size_mb: 25

`configurations.mcp` (client)

configurations:
  mcp:
    servers:
      - name: filesystem
        command: ["mcp-server-filesystem", "/home/me"]
      - name: github
        command: ["mcp-server-github"]

`configurations.schedule`

configurations:
  schedule:
    enabled: true

`configurations.iot`

configurations:
  iot:
    adapter: stub                   # "stub" (default) — or "homeassistant" when wired

`configurations.voice`

configurations:
  voice:
    stt_provider: whisper           # "whisper" | "stub"
    tts_provider: stub              # "stub" | "piper"

`configurations.embedding`

configurations:
  embedding:
    provider: ""                    # "" (auto) | openai | ollama | openai_compat
    model: text-embedding-3-small
    base_url: ""                    # only for ollama / openai_compat

`configurations.plugins`

configurations:
  plugins:
    auto_enable: true
    plugin_dir: ""                  # defaults to <data_dir>/plugins

`configurations.a2a`

configurations:
  a2a:
    enabled: false
    port: 8081
    bind_address: 127.0.0.1
    token_hashes:                   # SHA-256 hex hashes of allowed bearer tokens
      - "a1b2c3d4..."

`configurations.mcp_server` (MCP exposure)

configurations:
  mcp_server:
    allowed_capabilities:           # which capabilities are exposed to MCP clients
      - memory.read
      - data.read

`configurations.oauth`

configurations:
  oauth:
    redirect_uri: https://aibutler.example.com/oauth/callback
    gmail:
      client_id: ""
      client_secret: ""
    google_calendar:
      client_id: ""
      client_secret: ""
    github:
      client_id: ""
      client_secret: ""

`configurations.swarm`

configurations:
  swarm:
    enabled: true
    max_depth: 4
    budget_usd: 5.0
    workspace_ttl_hours: 24

`configurations.registry`

configurations:
  registry:
    health_ttl_minutes: 5
    self_register: false

`configurations.hooks`

configurations:
  hooks:
    pre_tool_use:
      - command: "echo blocked >&2 && exit 2"
        tools: ["shell.exec"]
    post_tool_use:
      - command: "gofumpt -w ."
        tools: ["file.edit", "file.write"]

See Hooks for the full reference.

`configurations.permissions`

Role-based permission rules are expressed per-rule. See internal/config/config.go for the PermissionRuleConfig type.

`configurations.bridges`

configurations:
  bridges:
    bridges:                         # yes, nested — the outer key is reserved
      ffmpeg-convert:
        command: "ffmpeg"
        args: ["-i", "{{input}}", "{{output}}", "-y"]
        timeout: 60s
        capabilities: [shell.execute]

See Subprocess Bridges for details.

`configurations.sandbox`

configurations:
  sandbox:
    mode: workspace-only             # off | workspace-only | allow-list
    allow_paths:
      - /home/me/projects
      - /tmp

`configurations.backup.remote`

configurations:
  backup:
    remote:
      provider: s3                   # s3 | http
      endpoint: s3.amazonaws.com
      bucket: my-aibutler-backups
      region: us-east-1
      access_key: ""                 # prefer vault over inline
      secret_key: ""
      encrypt_key: ""                # optional age encryption key

`configurations.skill_synthesis` (beta)

Opt-in self-authored skill proposals. When enabled, completed multi-step work with a verified outcome (a checker tool that ran and passed) is distilled into a staged skill proposal. Proposals never activate themselves — approval is always an explicit human action (aibutler skills approve).

configurations:
  skill_synthesis:
    enabled: false                   # default off
    min_tool_calls: 5                # shorter runs are routine, not procedures
    verify_tools: [code.test, code.lint, code.run]

`configurations.reflection` (beta)

Opt-in idle-time maintenance: a scheduled, deterministic pass — no model call, no tool access — that surfaces contradictions awaiting review, flags stale high-importance facts, checks embedding-index health, and writes a maintenance report you can read. It proposes; it never silently applies anything.

configurations:
  reflection:
    enabled: false                   # default off
    cron: "0 3 * * *"                # nightly at 03:00

`configurations.hooks.verify` (beta)

Shorthand for a post-mutation verification hook: after the listed tools edit files, your checker runs and its real output is fed back into what the model sees — correction driven by compiler/test reality, not self-assessment.

configurations:
  hooks:
    verify:
      command: "go build ./... 2>&1 | head -20"
      tools: [file.write, file.edit]   # default

`configurations.file`

configurations:
  file:
    allow_paths: []                  # extra roots for the file tools (data dir + home are defaults)

`options`

Developer-tier tunables. Defaults are generally fine — only override when you know what you’re doing.

`options.models`

options:
  models:
    temperature: 0.7
    max_tokens: 4096
    request_timeout: 120s
    retry_count: 3

`options.database`

options:
  database:
    busy_timeout: 5000

`options.agents`

options:
  agents:
    max_tool_calls: 50
    subagent_timeout: 5m
    background_timeout: 30m
    background_max: 3
    per_subagent_budget: 0           # 0 = unlimited
    autonomy_level: l1               # l1 | l2 | l3
    parallel_tool_limit: 5
    per_user_agent_limit: 3
    l3_time_bound: 30m
    repeat_call_limit: 3             # beta — Nth identical tool call within 10m gets an advisory instead of executing; 0 = off

`options.prompts`

options:
  prompts:
    max_tier1_tokens: 700
    max_skills_per_turn: 3
    skill_trigger_threshold: 0.5
    truncation_strategy: balanced    # balanced | essential_only
    max_instruction_tokens: 200
    core_memory_selection: scored    # beta — scored (pin/importance/usage/recency) | recency (legacy newest-first)
    max_core_memory_tokens: 350      # beta — token budget for the always-in-context fact set

`options.cost`

options:
  cost:
    cache_ttl: 5m
    expensive_threshold: 10000

`options.typing`

options:
  typing:
    interval_ms: 3000
    timeout_ms: 120000

`options.media`

options:
  media:
    max_upload_size_mb: 20
    max_text_lines: 500

`options.sessions`

options:
  sessions:
    cleanup_interval: 1h
    max_age: 168h                    # 7 days

`options.schedule`

options:
  schedule:
    tick_interval: 60s
    max_concurrent: 3

`options.voice`

options:
  voice:
    max_audio_size_mb: 25
    stt_timeout: 30s

`options.plugins`

options:
  plugins:
    max_plugins: 20
    exec_timeout: 30s
    max_memory_mb: 64

`options.transaction`

options:
  transaction:
    per_transaction_limit: 0         # max USD per transaction (0 = blocked)
    daily_limit: 0                   # max USD daily total (0 = blocked)

Inspecting the Effective Config

aibutler config show

Prints the current effective configuration, grouped by tier. Use this to verify overrides from env vars and command-line flags landed correctly.

The Three Enriches — conceptual overview
BUTLER.md — project-level agent instructions

Configuration Reference

File Location

Top-Level Structure

settings

configurations

configurations.models

configurations.channels

configurations.agents

configurations.security.shell

configurations.cost

configurations.web

configurations.mcp (client)

configurations.schedule

configurations.iot

configurations.voice

configurations.embedding

configurations.plugins

configurations.a2a

configurations.mcp_server (MCP exposure)

configurations.oauth

configurations.swarm

configurations.registry

configurations.hooks

configurations.permissions

configurations.bridges

configurations.sandbox

configurations.backup.remote

configurations.skill_synthesis (beta)

configurations.reflection (beta)

configurations.hooks.verify (beta)

configurations.file

options

options.models

options.database

options.agents

options.prompts

options.cost

options.typing

options.media

options.sessions

options.schedule

options.voice

options.plugins

options.transaction