Configuration basics

GEODE configuration follows one rule. Credentials live in auth.toml, which GEODE manages, or in .env as env vars you set by hand. Behavior lives in config.toml. When the same key exists in several layers, the closer layer wins, and geode config explain shows you which one won.

Files and roles

"Secrets-only .env" is a contract the tools keep. /model no longer writesGEODE_MODEL to .env; it persists toconfig.toml only. Model lines left behind by older releases are auto-removed right after the picker's toml write, with a printed notice (remove_env incore/config/env_io.py). Only the API-key fields are env-only (_TOML_ENV_ONLY_FIELDS in core/config/__init__.py); every other field has a config.toml key. The gateway, for example, is enabled with [gateway] enabled = true in ~/.geode/config.toml, and an exported GEODE_GATEWAY_ENABLED stays a session override.

Extension trust policy

Bundled GEODE features are classified as first-party code. Other filesystem hooks, package LLM adapters, project or personal skills, and MCP servers are first discovered from their existing manifests, then authorized by~/.geode/extension-policy.json. With no policy or no matching stable ID, executable code is not loaded.

{
  "version": 1,
  "extensions": {
    "hook:failure-metrics": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted",
      "capabilities": ["events"]
    },
    "llm-adapter:acme-payg": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted"
    },
    "skill:project-review": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted",
      "capabilities": ["shell"]
    },
    "mcp:filesystem": {
      "enabled": true,
      "trusted": false,
      "execution": "brokered",
      "capabilities": ["stdio"]
    }
  }
}

trusted is an in-process API boundary for code you trust; it is not a sandbox. A brokered MCP server starts with an exact environment and isolated scratch directory only when a supported OS sandbox is available. Otherwise it staysDEGRADED and is not launched. To use another policy path, set GEODE_EXTENSION_POLICY_OVERRIDE to the JSON file. The override is strict, so a missing file or invalid JSON fails startup. Decisions are frozen at startup and appear under extensions in runtime health.

Project trust

A repository can ship .geode/config.toml,.env and .claude/mcp_servers.json. Until you trust the folder, GEODE does not apply project settings that widen what the agent may do: the project .env, project MCP servers and gateway config, and keys such as the sandbox mode, computer use, webhooks, notifications and storage paths. Keys that grant nothing, such as the model choice, and restrictions such as[policy.org] denied_tools apply immediately.

geode config trust              # trust the current folder
geode config trust --list       # list trusted folders
geode config trust PATH --revoke

As in Codex, trust is recorded only in the global~/.geode/config.toml under[projects."path"], and a project's own config.toml is never consulted, so a repository cannot trust itself.hitl.dangerously_skip_permissions andcomputer_use.helper_path are never read from project config, even in a trusted folder. Ignored entries appear in a warning log and in geode config explain.

The resolution ladder

Every Settings field rides the same ladder. Higher wins (LAYERS in core/config/explain.py).

1. os.environ            shell exports. session-scoped manual override
2. global .env           ~/.geode/.env (authoritative secrets)
3. project .env          .env in the cwd (trusted folders only; fills only keys global lacks)
4. project config.toml   .geode/config.toml (capability keys: trusted folders only)
5. global config.toml    ~/.geode/config.toml
6. code default

Secrets (.env) and behavior (config.toml) order global vs project in opposite directions. For .env the global file is higher (authoritative); for config.toml the project file is higher (project tuning). The same key never appears in both layers (secrets-only, behavior-only, C-2), so one ladder is enough. Before v0.99.216 the .env pair was also project-first, but an empty project .env could shadow a real global key, so it was flipped to global-authoritative (the Hermes alignment).

Narrowed to model resolution, the same ladder reads: CLI args > env layer (os.environ plus the .env files) > project toml > global toml > routing default. Because the env layer outranks every toml, a single forgotten .envline masks all future toml edits. That is the classic trap this design removes from the tools and leaves only to deliberate hands.

The GEODE_CONFIG_TOML env var redirects the globalconfig.toml path. The main settings loader,geode config explain, and global /modelreads, writes, and confirmation use the same path resolver. MCP server loading, gateway reads and change watching, and seed role and voter overrides also use this global path. Project-scoped picks still write to .geode/config.toml, and the project TOML continues to override global settings. The geode-eval config migrate-petri-toml preview and--yes write use that same global destination.

geode config explain

The standard diagnosis for "I changed the config but the effective value did not move". For a key it prints a per-layer candidate table, marks exactly one layer asWINNER and every set lower layer asmasked, with file paths, so you see exactly which line to edit or remove.

geode config explain model     # key defaults to model
geode about                    # effective model + one-line mask warning

Always verify against the effective state. The modelgeode about reports is the model that gets called, and the same screen warns when an env layer masks a toml pick. Reading config.toml content is not verification.

Reload semantics

At session boundaries reload_settings_from_disk()re-reads .env, GEODE_* env, and config.toml into a fresh candidate, then validates and prepares it before updating the existing singleton. Field validation, preparation, or routing refresh failures propagate while keeping the previous Settings values. Correct the source and reload again to update the same captured references. The reload also callsreload_routing_constants(), clearing the routing-manifest cache and rebinding the routing constants oncore.config. The honest limit: importers that copied values at module load time still hold boot-time copies. Restart the process to refresh those paths.

The daemon and model env keys

At startup the serve daemon drops behavior (model-pick) env keys from its inherited environment and skips them during.env promotion (load_daemon_env incore/cli/bootstrap.py). This fixes the failure where a model key promoted into the daemon's environment outlived every /model switch. The key list isBEHAVIOR_ENV_KEYS incore/config/env_io.py.

GEODE_MODEL  GEODE_ACT_MODEL  GEODE_JUDGE_MODEL
GEODE_COGNITIVE_REFLECTION_MODEL  GEODE_LEARNING_EXTRACT_MODEL
GEODE_AGENTIC_EFFORT
GEODE_ANTHROPIC_CREDENTIAL_SOURCE  GEODE_OPENAI_CREDENTIAL_SOURCE

To pin the daemon's model via env on purpose, setGEODE_SERVE_KEEP_MODEL_ENV=1. Since C-4 the flag is honored from the process env, the global .env, or, in a trusted folder, the project .env. Promotion precedence is manual exports > global.env > project .env (global is authoritative; the project file only fills keys global lacks); files never clobber pre-existing process env, and empty values never clobber anything.

Failure modes

Next

• config.toml reference. The full key inventory.
• Auth and OAuth. Credential storage and login.
• LLM routing. Where routing.toml is consumed.