gdmcode

Configuration reference

gdm configuration uses a 7-layer precedence system (highest wins):

CLI flags
  > Environment variables (GDM_* prefix)
    > Team policy (.gdm/team.toml [policy])
      > Team preferences (.gdm/team.toml [preferences])
        > Project config (.gdm/config.toml)
          > User config (~/.config/gdm/config.toml)
            > Built-in defaults

Secrets (API keys, tokens) must be stored in the OS keychain via gdm login. They must not appear in any TOML file.

config.toml reference

Place this file at ~/.config/gdm/config.toml (user-wide) or .gdm/config.toml (project).

[models]

Key Type Default Env var Description
models.primary string "grok-4-0106" GDM_MODELS_PRIMARY Primary model for all tasks
models.fallback string "o3-mini" GDM_MODELS_FALLBACK Fallback model when primary is unavailable
models.grok.scout string (built-in) GDM_MODEL_GROK_SCOUT Override Grok scout-tier model ID
models.grok.coder string (built-in) GDM_MODEL_GROK_CODER Override Grok coder-tier model ID
models.grok.thinker string (built-in) GDM_MODEL_GROK_THINKER Override Grok thinker-tier model ID
models.grok.reasoner string (built-in) GDM_MODEL_GROK_REASONER Override Grok reasoner-tier model ID
models.grok.debate string (built-in) GDM_MODEL_GROK_DEBATE Override Grok debate-tier model ID
models.gemini.* string (built-in) GDM_MODEL_GEMINI_* Same tiers for Gemini
models.codex.* string (built-in) GDM_MODEL_CODEX_* Same tiers for Codex

[budget]

Key Type Default Env var Description
budget.session_limit_usd float (>=0) 10.0 GDM_BUDGET_SESSION_LIMIT_USD Max cost per session in USD; 0 = unlimited
budget.monthly_limit_usd float (>=0) 200.0 GDM_BUDGET_MONTHLY_LIMIT_USD Monthly cap across all sessions in USD

[autonomy]

Key Type Default Env var Description
autonomy.level int (0-5) 2 GDM_AUTONOMY_LEVEL 0 = ask everything, 3 = balanced, 5 = fully autonomous

[audit]

Key Type Default Env var Description
audit.retain_days int (>=1) 90 GDM_AUDIT_RETAIN_DAYS Delete audit entries older than N days

[analytics]

Key Type Default Env var Description
analytics.consent_required bool false GDM_ANALYTICS_CONSENT_REQUIRED Require per-user opt-in before collecting analytics
analytics.roi_estimation bool false GDM_ANALYTICS_ROI_ESTIMATION Enable estimated time-saved reporting
analytics.anonymise bool true GDM_ANALYTICS_ANONYMISE Hash actor IDs before storing (recommended)

[agent]

Key Type Default Env var Description
agent.max_turns int 150 GDM_MAX_TURNS Maximum consecutive no-progress agent rounds before stopping
agent.cost_limit_usd float 10.0 GDM_COST_LIMIT Session cost cap (alias for budget.session_limit_usd)
agent.quiet bool false GDM_QUIET Suppress non-essential startup output

[tools]

Key Type Default Env var Description
tools.timeout_secs int 30 GDM_TOOLS_TIMEOUT Per-tool execution timeout in seconds

[debug]

Key Type Default Env var Description
debug.auto_search_iteration int 3 GDM_DEBUG_AUTO_SEARCH_ITERATION Run web search after this many failed debug iterations; 0 = disabled

[context]

Key Type Default Description
context.whole_codebase string "auto" Load all source files into context: "auto", "always", "never"

[artifacts]

Key Type Default Description
artifacts.auto_detect bool false Automatically detect and surface build artifacts

[debate]

Key Type Default Description
debate.model string "" Override model used for debate/consensus tier; empty = use tier default

[spinner]

Key Type Default Description
spinner.extra_verbs list[string] [] Additional verbs to display in the spinner animation

[fallback]

Key Type Default Env var Description
fallback.provider string null GDM_FALLBACK_PROVIDER Provider to use when primary fails: grok, gemini, codex
fallback.model_id_map table {} — Map provider.tier to model ID for fallback routing

[providers.ollama]

Key Type Default Description
providers.ollama.enabled bool false Enable Ollama local model provider
providers.ollama.base_url string "http://localhost:11434" Ollama server URL
providers.ollama.model string "" Model name to use (e.g. "llama3")
providers.ollama.local_only bool true Block cloud fallback when using Ollama
providers.ollama.allow_cloud_fallback bool false Allow falling back to a cloud provider on error
providers.ollama.allow_external bool false Allow the agent to make external network calls

[providers.vllm]

Key Type Default Description
providers.vllm.enabled bool false Enable vLLM local model provider
providers.vllm.base_url string "http://localhost:8000" vLLM server URL
providers.vllm.model string "" Model name to use

team.toml reference

Place at .gdm/team.toml. Shared via version control. Do not put secrets here.

[preferences] — team defaults (can be overridden by individuals)

Uses the same keys as config.toml (e.g. autonomy.level, models.primary).

[policy] — enforced for all team members (cannot be overridden)

Key Type Default Description
policy.policy_enforced bool false Enable policy enforcement
policy.max_autonomy_level int (0-5) 5 Cap autonomy level for all users
policy.allow_git_push bool true Allow git push operations
policy.allow_network bool true Allow external network tool calls
policy.network_allowlist list[string] [] Allowed hostnames/CIDRs for network tools (empty = allow all)
policy.require_audit_log bool false Refuse to run if audit log is not writable

Environment variables (quick reference)

Variable Description
XAI_API_KEY xAI Grok API key
GEMINI_API_KEY Google Gemini API key
OPENAI_API_KEY OpenAI Codex API key
GDM_PROVIDER Force provider: grok, gemini, codex
GDM_QUIET Set to 1 / true / yes to suppress startup output
GDM_HTTPS_PROXY HTTPS proxy for all outbound API calls
All GDM_* listed above See individual sections