Config

Gaia reads ~/.gaia/gaia.yaml (hot-reloaded). Secrets live in ~/.gaia/.env, never here. Inspect/edit with gaia config get|set|edit. The full commented default, generated from the schema:

# gaia.yaml — gaia runtime config (non-secret, hot-reloaded).
# Edit and save; changes are picked up without a restart.
# Secrets (tokens, api keys) belong in env / .env, NOT here.

llm:
  # LLM provider: gemini (GEMINI_API_KEY) or openai (needs the 'llm' dep group). Other litellm providers also work. Keys live in env.
  provider: gemini
  # Model id, e.g. gemini-2.5-flash or gpt-4o.
  model: gemini-2.0-flash
  # Reasoning effort for thinking-capable models: minimal|low|medium|high (blank = provider default). Mapped per provider — OpenAI/Anthropic via litellm reasoning_effort, ChatGPT-OAuth via reasoning.effort, Gemini via thinking budget. Change it from chat with /effort.
  effort: ""
  # OpenAI-specific settings (e.g. use_oauth).
  openai:
    # Sign in with ChatGPT (run 'gaia model') and use the subscription, instead of an OPENAI_API_KEY.
    use_oauth: false
# Channel-qualified sender ids seeded as admins, e.g. 'whatsapp:972...@s.whatsapp.net' or 'telegram:12345'. Each is ensured to map to an admin user on startup; everyone else is learned at first contact.
admin: []
connectors:
  whatsapp:
    # Run the WhatsApp connector.
    enabled: false
    group_trigger:
      # Master switch for group chats; false = ignore all group messages.
      respond_in_groups: true
      # Only respond in groups when Gaia is @mentioned or replied to.
      mention_only: true
    # Look active while working: blue-tick the message and show the 'typing…' (or 'recording audio…') indicator for the turn.
    show_active: true
    # Role for a first-seen sender (admin/user/guest). 'guest' is gated until an admin approves; seed admins via the top-level 'admin' list.
    default_role: guest
  cli:
    # Run the local terminal chat; foreground-exclusive.
    enabled: false
    # Role for the local operator.
    default_role: admin
  telegram:
    # Run the Telegram connector.
    enabled: false
    # Bot token; set via env GAIA_TELEGRAM_BOT_TOKEN, not here.
    token: null
    # Role for a first-seen sender (admin/user/guest). 'guest' is gated until an admin approves; seed admins via the top-level 'admin' list.
    default_role: guest
memory:
  # Run long-term memory (mem0). Off = session-only, no cross-session recall.
  enabled: true
  # Grow long-term memory automatically; off = remember-tool only. When a chat goes idle (sessions.idle_consolidate_minutes) gaia distils its important facts into mem0 — like a person processing a conversation after it ends.
  auto_ingest: true
  # Override what long-term memory extracts (mem0 custom_instructions); empty = the built-in default (durable user facts only, no assistant action logs).
  extraction_instructions: ""
  # How many memories load_memory returns per search.
  recall_limit: 5
  # At session start, distil the user's facts + recent projects into a profile baked into the prompt (always-on recall); off = the agent must call load_memory to recall anything.
  preload: true
  # Max bullet points the session-start profile keeps (importance-ranked).
  preload_limit: 20
  # Fact-extraction model. e.g. provider: openai, model: gpt-4o-mini.
  llm:
    # mem0 provider id. Verified today: gemini (llm + embedder) and chroma (vector store). Others are passed through to mem0 but UNVERIFIED — LLM: openai/anthropic/minimax/litellm/ollama; embedder: openai/vertexai/fastembed/ollama (Anthropic has no embeddings); store: pgvector/qdrant/pinecone/…
    provider: gemini
  # Vectoriser. e.g. provider: fastembed (local, no key) or openai.
  embedder:
    # mem0 provider id. Verified today: gemini (llm + embedder) and chroma (vector store). Others are passed through to mem0 but UNVERIFIED — LLM: openai/anthropic/minimax/litellm/ollama; embedder: openai/vertexai/fastembed/ollama (Anthropic has no embeddings); store: pgvector/qdrant/pinecone/…
    provider: gemini
  # Store. chroma (embedded, default) or e.g. provider: pgvector, host, port.
  vector_store:
    # mem0 provider id. Verified today: gemini (llm + embedder) and chroma (vector store). Others are passed through to mem0 but UNVERIFIED — LLM: openai/anthropic/minimax/litellm/ollama; embedder: openai/vertexai/fastembed/ollama (Anthropic has no embeddings); store: pgvector/qdrant/pinecone/…
    provider: chroma
mcp:
  # MCP servers to attach. Empty = no MCP (needs the 'mcp' dep group when set).
  servers: []
browser:
  # Browser backend: 'native' (default — gaia's built-in browser_* tools driving the Camoufox engine) or 'mcp' (opt-in Microsoft playwright-mcp via bunx; needs bun on PATH and falls back to 'native' when the runtime is missing).
  backend: native
  # Executable that runs playwright-mcp (mcp backend only). Default 'bunx' (bun). Must be on PATH or the backend falls back to native.
  runtime: bunx
  # The playwright-mcp package spec passed to the runtime.
  package: "@playwright/mcp@latest"
  # mcp backend: run the browser headless.
  headless: true
  # mcp backend: keep the browser profile in memory (no on-disk profile).
  isolated: true
  # mcp backend: which engine playwright-mcp drives (chromium/chrome/firefox/webkit/msedge). 'chromium' is downloaded by `playwright install`; 'chrome' needs system Google Chrome (no ARM64 Linux build).
  browser: chromium
  # mcp backend: restrict navigation to these origins (semicolon-joined and passed to --allowed-origins). Empty = no restriction (note: COARSER than the native SSRF guard).
  allowed_origins: []
  # mcp backend: only load these playwright-mcp tool names; empty = all (~25-60). Trim to keep the model's tool list lean.
  tool_filter: []
  # native backend: which browser engine to drive. 'camoufox' (default) is an anti-detect Firefox that beats many bot walls (needs its Firefox build, fetched by `gaia update` / `python -m camoufox fetch`); 'chromium' is the plain Playwright build.
  engine: camoufox
  # camoufox engine: human-like cursor movement (anti-detection).
  humanize: true
  # camoufox engine: locale, e.g. 'en-US' (empty = Camoufox default).
  locale: ""
  # camoufox engine: OS to spoof in the fingerprint (empty = random).
  os: ""
  # camoufox engine: match geolocation/timezone to the (proxy) IP.
  geoip: false
  # camoufox engine: skip downloading images (faster, less data).
  block_images: false
cron:
  # Run the cron scheduler inside the daemon (gaia serve/start).
  enabled: true
  # Fallback delivery target for jobs created without a chat (e.g. via the CLI).
  deliver:
    # Connector for cron replies (telegram/whatsapp); empty = log only.
    channel: ""
    # Chat id on that connector (telegram chat id / whatsapp user@server).
    chat: ""
missions:
  # Run the mission dispatcher inside the daemon — it executes board tasks (filed via task_create) on souls and pushes results.
  enabled: true
  # How many board tasks run at once — each runs on one soul, so this is the cap on simultaneously-busy souls/agents. Extra ready tasks wait their turn.
  max_concurrent: 3
  # How often the dispatcher polls the board for ready tasks.
  poll_seconds: 2.0
  # Max subtask nesting depth on the board (a soul filing a subtask deeper than this is refused) — the runaway-nesting brake.
  max_depth: 3
  # Max tasks a single mission may ever file (incl. done/failed). Hitting it pauses the mission and asks you before more work is created.
  max_tasks: 20
  # Wall-clock budget per mission in hours; 0 = unbounded. Past it the mission pauses and asks you.
  max_hours: 0.0
  # Max nesting depth for synchronous consult_soul calls (soul asks a soul a question) — bounds in-turn recursion.
  consult_depth: 2
  # Action classes that require human approval before a task runs (e.g. spend, book, send_as_me, destructive). A gated task parks in awaiting_approval and pushes you an 'approve?' — release with /task approve <id>.
  approval_classes: []
analysis:
  # Run the self-improve loop in the daemon — periodically analyze usage and apply new/refined skills, souls, and memories. Off by default (opt-in).
  enabled: false
  # How often the improve cycle runs (hours).
  interval_hours: 24.0
  # How many days of usage each cycle analyzes.
  window_days: 7
  # Apply proposals automatically. (A HITL review mode is a follow-up.)
  autonomous: true
monitor:
  # Run the self-monitoring loop in the daemon — periodically read the error logs, judge what's a real problem, and report it. Off by default (opt-in).
  enabled: false
  # How often the monitor cycle runs (hours). Also the per-signature report cooldown (the same error is reported at most once per cycle).
  interval_hours: 24.0
  # How many hours of error logs each cycle analyzes.
  window_hours: 24
  # DM the admin about new findings (turn off for issues-only).
  notify: true
  github:
    # File a GitHub issue for file_issue findings. Needs GITHUB_TOKEN; falls back to notify-only if the token is missing.
    create_issues: false
    # Target repo 'owner/name' (e.g. 'Sho0pi/gaia'). Required to file.
    repo: ""
    # Label put on filed issues (also used to find dupes).
    label: gaia-monitor
voice:
  # Transcribe inbound voice messages and answer them like text (needs the 'voice' dep group; ignored when faster-whisper isn't installed).
  enabled: true
  # faster-whisper model size: tiny/base/small/medium/large-v3. Bigger = better transcripts, slower + more RAM. Weights download on first use.
  model: base
  # Force a transcription language (e.g. 'en', 'he'); empty = auto-detect.
  language: null
  # Where to run the model: 'cpu' (anywhere) or 'cuda' (NVIDIA GPU).
  device: cpu
  # Weight quantisation: 'int8' (smallest/fastest on CPU); GPUs usually pair device 'cuda' with 'float16'.
  compute_type: int8
sessions:
  # How many recent conversation turns gaia replays to the model each message. The whole conversation is kept on disk; older turns come back via long-term memory. Lower = fewer tokens per message, shorter verbatim memory.
  window_turns: 30
  # After a conversation is idle this long, gaia distils its important facts into long-term memory and clears the session (a fresh, memory-informed start next time).
  idle_consolidate_minutes: 30.0
logging:
  # Root log level (DEBUG/INFO/WARNING/ERROR).
  level: INFO
  # Rotate a log file once it exceeds this size.
  max_size_mb: 5
  # How many rotated files to keep.
  backup_count: 5
# Fallback voice for agents (human/caveman/ai).
default_communication_style: human
# Skills folder; empty = the default under the home dir.
skills_dir: null
# Skill index urls (json manifests of {name, description, source}) that 'skill search' / Gaia search for installable skills; empty = web-search fallback only.
skill_index: []
# Per-agent bindings; the root orchestrator uses key 'gaia'.
agents: {}
# Per-role ACL overrides keyed by role (admin/user/guest), e.g. user.capabilities: [web, memory]. Empty = built-in defaults.
roles: {}
# Per-tool settings keyed by tool id (e.g. web_search.engine: duckduckgo). Every tool is attached to agents by default; disable one with enabled: false.
tools: {}
# Delegated-soul settings (e.g. timeout_seconds).
souls:
  # Max seconds a delegated soul may run before the delegation is abandoned.
  timeout_seconds: 300.0
  # Keep a soul's session warm between delegations so it resumes (instead of re-reading its workspace each time); evict it after this many minutes idle.
  session_idle_minutes: 30.0
# Per-command settings keyed by command name (e.g. forget.enabled: false). Every command is on by default.
commands: {}