Configuration reference
The complete okami.yaml schema. Every top-level key below is optional except default_provider and providers. Secrets NEVER go here — use ${ENV} and keep the value i…
Top-level keys
params default_provider string · required Provider used when none is passed. providers map · required Each entry is a provider (see below). memory map Memory backend, embedder and file limits. contracts map Verifiable contracts (e.g. contracts.ui). approvals map mode + always_allow (go/no-go). sandbox map Execution policy for run_shell/processes. voice map STT (Whisper) and TTS (Edge) for audio channels. learning map auto_skill and auto_tune. persona map observe (evolving persona). agents map default + bindings (multi-agent routing). groups list Multi-agent rooms (members + moderator). gateway map auto_resume, max_sessions. mcp map mcp.servers — external MCP servers. hooks map event → list of commands (event hooks). tools map tools.surfaces — per-channel allow/deny of tools.
providers.<id>
Each provider is described agnostically and resolved via LiteLLM at runtime. model is the LiteLLM-format string (e.g. openai/<model>, openai-codex/<model>, claude-subscription/<model>).
params model string Model in LiteLLM format (required). api_base string OpenAI-compat endpoint (local/proxy). api_key_env string Name of the env var with the key (comma-separated allowed). api_key string Literal key — only for a local dummy (e.g. lm-studio). api_keys list Key pool for rotation/failover on rate-limit. auth api_key | oauth_subscription Authentication kind. api_key transport litellm | claude_cli | codex_oauth | minimax_oauth Access transport. litellm tier strong | weak | local | unknown Capability — parameterizes the adaptive scaffold. fallback list Backup providers in a chain if this fails (529/timeout/empty). context_window int Model window in tokens (0 = default per tier). 0 reasoning_effort minimal|low|medium|high Reasoning effort (reasoning models). Swappable via /think. capability.tool_mode json_text|json_constrained|native How the model emits actions. json_text capability.vision bool Model accepts images (multimodal). false native_tools bool Native tool-calling (experimental, opt-in). false models list Alternate ids available on the plan. notes string Free-form note (shows up in doctor).
memory
params backend sqlite-fts5 | holographic | honcho | [list] Active backend; a list becomes layered memory. sqlite-fts5 embedder.enabled bool Enables embeddings (degrades to BM25 if offline). true embedder.api_base / .model string Embedding server and model (OpenAI-compat). holographic.dim int HRR/VSA vector dimension. 1024 honcho.base_url / .api_key string Honcho endpoint/credential (api_key via ${ENV}). files.{soul,voice,persona} int Char limit of the identity files. 6000 files.{agents,user,memory} int Char limit of the core files. 4000
contracts.ui
params library string Declared UI lib (e.g. shadcn, heroui). component_source string Expected import (e.g. @/components/ui). forbid_inline_hex bool Fails inline hex colors. true forbid_raw_css bool Fails raw <style> and inline style={{...}}. true require_component_source bool Requires importing the declared lib. true (if source)
approvals · sandbox
params approvals.mode manual|smart|off|yolo Approval mode (off is fail-closed). manual approvals.always_allow list Auto-approved categories (persisted). sandbox.profile dev|hardened|hardened-strict Posture shortcut. dev sandbox.backend local|docker|auto Execution backend. local sandbox.mode read-only|workspace-write|yolo Mutation policy. workspace-write sandbox.network bool Network allowed (real only in docker; yolo enables). false sandbox.timeout int (s) Wall-clock ceiling per command. 60 sandbox.egress_allow list Outbound host allowlist (filtering proxy). sandbox.require_isolation bool Exposed without Docker → shell DISABLED (doesn't degrade). false
voice · learning · persona
params voice.stt.backend / .model string Local Whisper (tiny…large). voice.tts.enabled / .backend / .voice — TTS: edge (free) | minimax; voice (e.g. pt-BR-AntonioNeural). learning.auto_skill bool Distills a skill from non-trivial tasks (passes the scan). false learning.auto_tune bool Tunes the capability profile from usage stats. false persona.observe bool Enables the evolving persona (VOICE/PERSONA). true