config.example.yaml

# Nerve — Personal AI Assistant Configuration
# Copy to config.yaml and customize. Secrets go in config.local.yaml (gitignored).
#
# Any string value may reference an environment variable — the recommended way
# to keep secrets out of committed/shared config:
#   key: ${MY_VAR}             # required — load fails if MY_VAR is unset
#   key: ${MY_VAR:-default}    # optional — uses default when unset/empty
# Only the braced ${...} form is interpolated; a bare "$" is left untouched
# (so bcrypt hashes / jwt secrets are safe). Use $$ for a literal "$".

# Core
workspace: ~/nerve-workspace    # Path to workspace with SOUL.md, MEMORY.md, etc.
timezone: America/New_York

# Provider — how Nerve connects to Claude (default: anthropic)
# provider:
#   type: bedrock              # "anthropic" or "bedrock"
#   aws_region: us-east-1      # AWS region for Bedrock
#   # aws_profile: ""          # Optional: AWS SSO profile name

# Local proxy (CLIProxyAPI) — optional. Routes Anthropic API calls through
# Claude Code OAuth, and is the Anthropic↔OpenAI translation layer that local
# Ollama models are reached through. Required for the ollama block below.
# proxy:
#   enabled: false
#   port: 8317
#   host: 127.0.0.1

# Local Ollama — expose locally-installed Ollama models as selectable chat
# models in the web composer's model picker. Ollama speaks an OpenAI-compatible
# API, so this requires proxy.enabled: true (the proxy translates the
# Anthropic requests the SDK emits). Models are auto-discovered at runtime
# from the running Ollama server (GET /api/tags) — whatever you've pulled
# locally shows up automatically, no need to list models here.
# ollama:
#   enabled: false
#   host: 127.0.0.1
#   port: 11434

# Agent
agent:
  model: claude-opus-5           # Primary model for conversations
  # Use claude-fable-5 for Anthropic's most capable (Mythos-class) model.
  # Note: ~2x the cost of Opus 5 ($10/$50 per MTok in/out).
  cron_model: claude-sonnet-4-6  # Cheaper model for cron jobs
  title_model: claude-haiku-4-5-20251001  # Session title generation
  # Model-alias remapping for the CLI: short aliases ("opus") used in
  # Agent/Workflow tool model options and skill frontmatter resolve to the
  # mapped ID. Supported: opus, sonnet, haiku, fable. opus → claude-opus-5
  # is the built-in default (not applied on Bedrock); "" unsets an alias.
  # model_aliases:
  #   opus: claude-opus-5
  # Claude models selectable in the web composer's model picker. The
  # configured `model` above is always offered first; entries here extend
  # the list. Unset → the models the Anthropic Models API reports for your
  # credentials (see model_discovery below), falling back to a built-in
  # current-generation list (opus / sonnet / haiku). On Bedrock only models
  # named in config are offered (Bedrock IDs are region-prefixed, so
  # neither discovery nor the bare built-ins would resolve).
  # models:
  #   - claude-opus-5
  #   - claude-sonnet-4-6
  # Ask the Anthropic Models API (GET /v1/models) at startup which models
  # the configured credentials can reach, so a newly released model shows up
  # in the picker without a config edit. Ignored when `models` above is set,
  # on Bedrock, or without an API key. false → always use the built-in list.
  model_discovery: true
  max_turns: 50                  # Max agentic turns per request
  max_concurrent: 32             # Max concurrent agent sessions
  # Keep the appended system prompt byte-identical across sessions so the
  # exact-prefix prompt cache is shared between them: the session id and the
  # pre-recalled memories travel in a <session-context> block at the top of
  # each session's first message instead. false → legacy shape (id + recall
  # inline in the system prompt; every session start re-writes the cache).
  static_system_prompt: true
  background_agent_permissions: true  # Background sub-agents (Agent run_in_background) get the same tool permissions as foreground; false denies their Write/Edit/Bash
  # Agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS). The CLI gates the
  # SendMessage tool behind this flag while the Agent tool advertises it
  # regardless ("use SendMessage with to: '<id>' to continue this agent"), so
  # with it off the model is told to resume sub-agents with a tool that does
  # not exist. On: sub-agents are resumable with their context intact, and
  # teammates can message each other. Teammates stay opt-in per turn and cost
  # a full context window each; the CLI cannot restore in-process teammates
  # when a session's client is recycled (idle timeout, restart, crash retry).
  agent_teams: true
  # First-prompt rewrite — the web UI can refine the opening message of a
  # new chat with a fast model, preview it, and send only after approval.
  prompt_rewrite:
    enabled: true                # Master switch (per-user toggle is in the UI)
    model: ""                    # Empty → falls back to agent.model (chat model)
    max_tokens: 1024
    timeout_seconds: 45
  # For Bedrock, use model IDs like:
  #   model: us.anthropic.claude-opus-5
  #   cron_model: us.anthropic.claude-sonnet-4-6
  #   title_model: us.anthropic.claude-haiku-4-5-20251001-v1:0

# Gateway
gateway:
  host: 0.0.0.0
  port: 8900
  ssl:
    cert: ~/.nerve/certs/cert.pem
    key: ~/.nerve/certs/key.pem

# Channels
telegram:
  enabled: true
  # DM authorization:
  #   pairing — only users in allowed_users may talk to the bot. New users
  #             authorize with a one-time code: run `nerve pair` on the
  #             server, then send the bot `/pair <code>`. Paired IDs are
  #             persisted to config.local.yaml automatically.
  #   open    — anyone can talk to the bot (dangerous: full agent access).
  dm_policy: pairing
  # allowed_users: [123456789]   # numeric Telegram user IDs (or pair instead)
  stream_mode: partial           # "partial" (edit messages) or "full" (wait for complete)

# Quiet hours (local timezone)
quiet_start: "02:00"
quiet_end: "12:00"

# Sync sources
sync:
  telegram:
    enabled: true
    monitored_folders: [Work, Friends]
  gmail:
    enabled: true
    accounts: []                 # Set in config.local.yaml
    schedule: "*/15 * * * *"
  # Plain IMAP mailboxes — for providers the Gmail source can't reach.
  # One source per account. Passwords go in config.local.yaml under
  # sync.imap.passwords, keyed by username. See docs/sources.md for the
  # optional pass that reads mail whose payload is only legible as an image.
  # imap:
  #   enabled: false
  #   accounts:
  #     - host: imap.example.net
  #       username: me@example.net
  #       label: mailbox           # source name becomes imap:mailbox
  #   schedule: "*/30 * * * *"
  github:
    enabled: true
    schedule: "*/15 * * * *"
    # Guardrails (case-insensitive globs; deny wins; non-empty allow is
    # fail-closed). allow_* = allowlist (empty = all pass).
    #   repo_name — the notification's repo full_name ("ClickHouse/nerve").
    #   actors    — every login involved (author, assignees, commenters).
    #   reason    — GitHub's notification reason: mention, author,
    #               review_requested, assign, team_mention, comment,
    #               subscribed, ci_activity, state_change, ...
    #   ci_branch — branch of a CI run (empty for everything else), so this
    #               one is deny-only: an allow list would fail closed and
    #               drop every non-CI notification.
    allow_repos: []                # Example: ["ClickHouse/*", "myorg/myrepo"]
    deny_repos: []
    allow_actors: []
    deny_actors: []
    allow_reasons: []
    deny_reasons: []               # Example: ["comment", "subscribed"] — mute
                                   # follow-up churn on threads you only
                                   # commented on / watch; keep mentions,
                                   # review requests, and your own PRs.
    deny_ci_branches: []           # Example: ["main", "master"] — keep CI
                                   # failures on your own PR branches, drop
                                   # default-branch syncs and scheduled runs.
  github_repos:                    # Monitor a set of repos for NEW issues & PRs
    enabled: false
    schedule: "*/15 * * * *"
    repos: []                      # Required: ["ClickHouse/clickhouse-go", "owner/repo"]
    batch_size: 50

# Memory (memU)
memory:
  recall_model: claude-sonnet-4-6
  # embed_model: text-embedding-3-small  # Only needed with openai_api_key

# Cron — no path keys needed. Cron config lives in <workspace>/config/cron/
# (system.yaml, jobs.yaml, gates/) and is resolved from the workspace, with a
# fallback to the legacy ~/.nerve/cron for un-migrated installs.
#
# Do NOT pin system_file/jobs_file here unless you really mean it: an explicit
# value wins outright, so it disables both the workspace location and the
# fallback, and `nerve init` will keep regenerating a system.yaml nothing reads.
#
# Editing the cron files does not apply itself: run `nerve reload`, or let the
# next workspace sync do it.

# Workflow runs — budget-capped multi-agent jobs (Claude Workflow tool or
# Codex Ultracode) in dedicated tracked sessions. Nerve meters real dollar
# spend, warns at 80% of budget, and kills the run at 100% (scoped to the
# run's own session). Runs do not survive a daemon restart. Enabled by
# default; values below are the defaults. See docs/workflow-runs.md.
# workflows:
#   enabled: true
#   runs_dir: ~/.nerve/workflow-runs  # <runs_dir>/<run-id>/{run.json,events.ndjson,result.md}
#   poll_interval_seconds: 60         # budget monitor cadence (re-meters spend)
#   warn_fraction: 0.8                # one-time warning at this fraction of budget
#   kill_grace_seconds: 30            # graceful stop -> grace -> force kill
#   max_concurrent_runs: 2            # excess runs queue as 'pending'; keep well below agent.max_concurrent
#   allow_unbudgeted: false           # require budget_usd on every run
#
#   # Review loops — deterministic implement→verify cycles built from
#   # workflow runs: an implementer leg works toward a Goal prompt, an
#   # independent verifier leg judges the workspace against Verifier
#   # criteria (structured, evidence-backed verdict), and the server
#   # iterates until the criteria pass or a cap fires. Cross-vendor legs
#   # (Claude implements, Codex verifies) are the default when Codex is
#   # configured. See docs/review-loops.md.
#   review_loop:
#     enabled: true
#     implementer: {engine: claude-workflow, model: "", effort: ""}  # "" = backend default
#     verifier:    {engine: codex-ultracode, model: "", effort: ""}  # cross-vendor default
#     max_iterations: 3                 # per-loop default; hard ceiling 8
#     default_budget_usd: 10.0          # total loop budget (all legs)
#     min_leg_budget_usd: 0.5           # never start a leg with less
#     verifier_reserve_fraction: 0.15   # held back so the last attempt is always verified
#     criteria_adoption: "no"           # no | ask | auto — verifier-proposed criteria policy
#     max_new_criteria_per_iteration: 3 # auto mode adoption caps
#     max_discovered_criteria: 12
#     discovery_grace_rounds: 2         # discovery-only rounds before escalating "scope keeps growing"
#     auto_reissue_implementer: false   # restart recovery: re-run interrupted implementer legs
#     escalation_reproposals: 2         # re-file expired decision cards this many times
#     verifier_sandbox: workspace-write # codex verifier legs (isolation vs test-writes)
#     reconcile_interval_seconds: 600   # card-liveness + loop budget-warn tick

# Backup (optional) — scheduled, verified snapshots of Nerve state into a
# single portable bundle (nerve-backup-<host>-<ts>.tar.zst). Off by default.
# Point target_dir at an external mount or a synced directory — the OFF-BOX
# copy is what protects against a disk failure. The SQLite DBs are snapshotted
# with the online-backup API, so bundles are consistent even while Nerve runs.
# Manual use: `nerve backup` / `nerve restore BUNDLE` (no running server needed).
# backup:
#   enabled: false
#   target_dir: ""              # e.g. /mnt/backup/nerve  (REQUIRED when enabled)
#   interval_hours: 24          # scheduled cadence (an hourly tick fires when due)
#   retention_count: 7          # keep the newest N bundles; prune older ones
#   include_workspace: true     # include the workspace BRAIN (*.md, memory/, scripts/, skills/)
#   workspace_excludes: []      # extra glob patterns to skip, e.g. ["*.png", "drafts"]
#   notify_on_failure: true     # high-priority notify if a scheduled backup fails
#   notify_on_success: false    # low-priority digest line on success

# External MCP server (optional) — expose Nerve's tool registry to
# external MCP clients (Codex, Claude Code, Cursor) over Streamable HTTP.
# Off by default. Authentication reuses the gateway JWT
# (auth.jwt_secret) — present it as `Authorization: Bearer <jwt>` or
# `?token=<jwt>`. Connect a client with the URL "https://<host>:8900/mcp/v1/".
# mcp_endpoint:
#   enabled: false
#   path: /mcp/v1
#   include_hoa: false   # Expose the deprecated houseofagents stub tools externally (default off)

# Observability (optional) — Langfuse tracing for the agent loop and memU.
# Set keys in config.local.yaml. Without keys, the integration is a no-op.
# See docs/observability.md for setup details.
# langfuse:
#   public_key: pk-lf-...        # from your Langfuse project (set in config.local.yaml)
#   secret_key: sk-lf-...        # from your Langfuse project (set in config.local.yaml)
#   host: https://cloud.langfuse.com
#   # redact_patterns:           # optional — strip these regexes from spans
#   #   - "sk-ant-[A-Za-z0-9_\\-]{20,}"