config.example.yaml

# agent-vivy example configuration.
# Copy to config.yaml for local use. NEVER put real secrets here —
# provider keys are read from environment variables at request time (D-010).
#
# Default data root (when nothing below is set): the OS user home, e.g.
#   ~/.vivy  (Windows %USERPROFILE%\.vivy, override with VIVY_USER_HOME)
# holding workspace/, skills/, settings.yaml and vivy.db — one per user,
# diva-style. Everything written here is explicit and wins over that root.

server:
  # Local HTTP bootstrap + WebSocket JSON-RPC listen address for the UI.
  # 0.0.0.0 is valid only when allowed_origins is empty (container listen).
  addr: "127.0.0.1:8787"
  # Exact loopback origins for a separately hosted UI. Keep empty for the
  # default embedded same-origin UI.
  allowed_origins: []

storage:
  # sqlite is the default one-click Journal. postgres is the only optional
  # server backend (DSN from dsn_env, never inlined here).
  backend: sqlite
  # Empty = derive from sqlite.path (sqlite) or the user data root
  # (postgres). Settings live at <data_dir>/settings.yaml.
  data_dir: ""
  sqlite:
    # Empty default: <user data root>/vivy.db under the OS user home.
    path: "data/vivy.db"
  postgres:
    dsn_env: VIVY_POSTGRES_DSN

providers:
  # Pre-baked bundle to activate. V0 ships exactly two bundles:
  # openai (OpenAI-compatible) and anthropic (D-018, D-023).
  active: openai
  # Directory holding the pre-baked bundle YAML files (A2 fixtures).
  bundle_dir: fixtures/provider
  openai:
    # Secret is read from this environment variable, never persisted.
    env_key: OPENAI_API_KEY
    default_model: gpt-4o-mini
  anthropic:
    env_key: ANTHROPIC_API_KEY
    default_model: claude-sonnet-4-5

runtime:
  # Max buffered stream chunks / event payload size bounds (NFR: bounded).
  stream_buffer: 256
  max_event_payload_bytes: 65536
  # Bounds the transient current-session context sent to the model.
  max_context_bytes: 262144
  max_history_messages: 64
  max_tool_result_bytes: 32768
  # Shared run-tree circuit breakers. Resumed work spends the same budget.
  max_run_events: 512
  max_model_calls: 32
  max_run_tool_calls: 64
  max_run_retries: 3
  # Default: <user data root>/workspace (under the OS user home). One
  # private sandbox directory per background run lives under this root.
  workspace_root: data/workspaces
  # Trusted local Skill packages. Skill text is still treated as untrusted data.
  # Default: <user data root>/skills.
  skills_root: data/skills
  # Skill marketplace base URL (skills.sh directory: search/featured/install).
  # Installed packages land in skills_root and pass the same loader guards.
  # Default: https://skills.sh; env VIVY_SKILLS_MARKETPLACE_URL overrides.
  skills_marketplace_url: https://skills.sh
  # Explicit host surface for read-only http_request; add public hosts deliberately.
  http_allowed_hosts:
    - localhost
    - 127.0.0.1
    - ::1
  http_max_response_bytes: 1048576
  # Streamable HTTP MCP servers; credentials are env references only.
  # This is the production default. The UI writes an overlay to the operator
  # settings document (settings.yaml mcp_servers). A saved overlay, including
  # an empty list, replaces this default on the next launch and immediately
  # via settings/mcp*.
  mcp_servers: []
  # Executable allowlist for execute/commandline. Extend per project, e.g.:
  #   - node / pnpm   (frontend builds, pnpm test)
  #   - python / uv   (scripts, test suites)
  #   - just          (justfile task runner)
  # Each entry is an executable basename (no paths, no shell syntax).
  execute_allowed_commands:
    - go
    - git
    - rg
  # Ceiling for one execute/commandline run in seconds (requests above it are
  # clamped). 30s is too short for real work such as `go test ./...` or
  # `git clone`; raise it for heavyweight commands. Hard cap: 600 (10m).
  execute_max_timeout_seconds: 30
  # Context compression (Eino native reduction + summarization middlewares).
  # Triggers when one run's feed exceeds
  #   min(max_tokens * trigger_percent / 100, max_context_bytes/4 tokens).
  # Settings → 通用 → 上下文压缩 overrides these per user via settings.yaml.
  compaction:
    enabled: true
    # Model context window cap used for the trigger and the UI meter.
    # 0 = use the provider model's ContextWindow, else a 128000 fallback.
    max_tokens: 0
    # Percentage of max_tokens at which compression triggers (1-100).
    trigger_percent: 80
    # How many most-recent tool-call rounds the deterministic reduction
    # layer retains verbatim.
    keep_recent: 12
  # Cron controls the scheduled-job scheduler behind the UI CRON panel.
  # Jobs fire agent turns in their own dedicated session; while disabled
  # the stored jobs simply never run.
  cron:
    # Turn the scheduler on. Defaults to true.
    enabled: true
  # Sandbox controls the file-effect policy boundary (D-021).
  # Mirrors the DeepSeek Harness three-tier permission model.
  sandbox:
    # Initial sandbox mode for new sessions:
    #   read_only           - deny all writes, only allow reads in workspace
    #   workspace_write     - allow reads/writes within workspace root (default)
    #   danger_full_access  - bypass all sandbox restrictions (use with caution)
    default_mode: workspace_write
    # Optional override for sandbox workspace root (defaults to workspace_root above).
    workspace_root: ""
    # Approval behavior for effectful tools under different policies.
    approval:
      # Default approval policy:
      #   ask   - require user approval for every effectful tool (default)
      #   never - deny all effectful tools without asking
      #   auto  - auto-approve readonly/whitelisted tools, ask for others
      default_policy: ask
      # Timeout in seconds before pending approvals are auto-expired and denied.
      # Set to 0 to disable timeout (approvals expire based on expiration field only).
      timeout_seconds: 300
      # Tools that are auto-approved under the "auto" policy (typically readonly tools).
      auto_approve_tools:
        - list_dir
        - read_file
        - search_files
        - list_notes
        - read_note
        - skills_list
        - skill_view
        - network_search
    # Network access restrictions for HTTP requests.
    network:
      # Whitelist of allowed domains. Empty means no domain restriction.
      allowed_domains: []
      # Block RFC1918 private IP ranges when true.
      deny_private_ips: true

tools:
  # Read-only tools auto-execute. Mutations and Skill management are always
  # routed through the durable approval/HITL flow.
  # echo_info stays registered (verification tool for tests) but is not
  # enabled by default; add it back explicitly if you need the probe.
  enabled:
    - write_note       # effectful, approval-gated
    - list_notes
    - read_note
    - ask_user         # user-input suspension, distinct from approval
    - list_dir         # read-only workspace tree exploration
    - read_file
    - search_files
    - write_file
    - patch
    - http_request  # GET/HEAD only; host allowlist and credential policy apply
    - mcp_list_tools
    - mcp_call       # always approval-gated with server/tool provenance
    - sequential_thinking
    - execute        # workspace-only, allowlisted process, always approval-gated
    - commandline    # argv-oriented alias with the same policy
    - skills_list
    - skill_view
    - skill_manage
    - task_create
    - task_get
    - task_update
    - task_list
    - network_search  # API-backed text search; remote results are untrusted
    - tool_search
# Preferred network_search provider when the model does not name one.
  # bing/google/searxng need their environment keys
  # (BING_SEARCH_API_KEY / GOOGLE_SEARCH_API_KEY+GOOGLE_SEARCH_CX /
  # SEARXNG_SEARCH_URL); duckduckgo and wikipedia work without keys.
  # Leave empty for automatic: the first usable provider wins, degrading to
  # the keyless duckduckgo/wikipedia providers. This field stores no secrets.
  # Also settable from the Settings UI.
  network_search:
    provider: ""  # one of: bing | google | duckduckgo | searxng | wikipedia | ""
  approval:
    expiration: 5m

logging:
  # Kernel log output (docs/architecture/LOGGING.md). VIVY_LOG_LEVEL and
  # VIVY_LOG_FORMAT override level/format for one launch.
  level: info          # debug | info | warn | error
  format: json         # json | text
  # Empty = <data_dir>/logs. Rotated files are vivy.log.YYYY-MM-DD.
  dir: ""
  # Startup sweep deletes vivy.log* files older than this many days.
  # 0 keeps every file.
  retention_days: 30
  # Mirror log lines to the console in addition to the file.
  stdout: true