Configuration
Every setting Gantry reads, its default and the tiers that can set it, and the GANTRY_* environment variables it binds.
The settings
Configuration settings — 31 rows exported from
src/engine/config_schema.rs
| setting | default | what it does | how it is read |
|---|---|---|---|
| [harness].default | startup fallback | Default agent harness for roles that do not name a more specific harness. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by run-wide CLI → global config file → startup fallback environment — no environment tier, by design global config file may set it |
| [harness].plan | startup fallback | Harness preference for planning work. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by per-role CLI → run-wide CLI → remembered run selection → project harness.toml → global config file → startup fallback environment — no environment tier, by design global config file may set it |
| [harness].build | startup fallback | Harness preference for build work. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by per-role CLI → run-wide CLI → remembered run selection → project harness.toml → global config file → startup fallback environment — no environment tier, by design global config file may set it |
| [harness].review | startup fallback | Harness preference for review work. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by per-role CLI → run-wide CLI → remembered run selection → project harness.toml → global config file → startup fallback environment — no environment tier, by design global config file may set it |
| [harness].util | startup fallback | Harness preference for utility work. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by per-role CLI → run-wide CLI → remembered run selection → project harness.toml → global config file → startup fallback environment — no environment tier, by design global config file may set it |
| [model].plan | unset | Model pin for planning work after the harness is selected. | kind string accepts — validated as non-blank string set by global config file environment — global config file may set it |
| [model].build | unset | Model pin for build work after the harness is selected. | kind string accepts — validated as non-blank string set by global config file environment — global config file may set it |
| [model].review | unset | Model pin for review work after the harness is selected. | kind string accepts — validated as non-blank string set by global config file environment — global config file may set it |
| [model].util | unset | Model pin for utility work after the harness is selected. | kind string accepts — validated as non-blank string set by global config file environment — global config file may set it |
| [harness.<id>].bin | harness default | Path to the registered harness CLI binary. | kind path accepts — validated as path set by environment → global config file → built-in default environment GANTRY_<HARNESS>_BIN, one per registered harness — also GANTRY_CLAUDE global config file may set it |
| [harness.<id>].model | defer to selected harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. | kind string accepts — validated as non-blank string set by environment → global config file → model deferral environment GANTRY_<HARNESS>_MODEL, one per registered harness — also GANTRY_MODEL global config file may set it |
| [harness.<id>].small_model | harness default | Small-model pin for a registered harness's utility calls. | kind string accepts — validated as non-blank string set by environment → global config file → built-in default environment GANTRY_<HARNESS>_SMALL_MODEL, one per registered harness — also GANTRY_COMMIT_MODEL global config file may set it |
| [harness.<id>].args | [] | Extra arguments appended to a registered harness invocation. | kind string list accepts — validated as string list set by environment → global config file → built-in default environment GANTRY_<HARNESS>_ARGS, one per registered harness global config file may set it |
| [assistant].harness | codex | Harness used by the conversational Gantry Assistant. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by assistant CLI → remembered run selection → project harness.toml → global config file → run harness → built-in default environment — no environment tier, by design global config file may set it |
| [assistant].model | defer to selected harness | Model pin for the conversational Gantry Assistant; unset defers to the selected harness. | kind string accepts — validated as non-blank string set by environment → project harness.toml → global config file → model deferral environment GANTRY_ASSISTANT_MODEL global config file may set it |
| [effort].plan | high | Reasoning effort passed to the selected harness. | kind closed enum accepts low · medium · high validated as closed enum set by task front matter → environment → global config file → built-in default environment GANTRY_PLAN_EFFORT global config file may set it |
| [effort].build | medium | Reasoning effort passed to the selected harness. | kind closed enum accepts low · medium · high validated as closed enum set by task front matter → environment → global config file → built-in default environment GANTRY_EFFORT global config file may set it |
| [effort].review | medium | Reasoning effort passed to the selected harness. | kind closed enum accepts low · medium · high validated as closed enum set by task front matter → environment → global config file → built-in default environment GANTRY_EFFORT global config file may set it |
| [effort].util | medium | Reasoning effort passed to the selected harness. | kind closed enum accepts low · medium · high validated as closed enum set by task front matter → environment → global config file → built-in default environment GANTRY_EFFORT global config file may set it |
| [retry].transient_delays | [0, 600, 3600] | Backoff seconds between retry attempts for transient agent failures. | kind seconds list accepts — validated as seconds list set by environment → global config file → built-in default environment GANTRY_RETRY_DELAYS global config file may set it |
| [retry].usage_reset_max_retries | 3 | Maximum usage-limit reset waits Gantry honours before giving up. | kind count accepts — validated as count set by environment → global config file → built-in default environment GANTRY_USAGE_RESET_MAX_RETRIES global config file may set it |
| [gate].timeout_secs | 14400 | Wall-clock seconds a gate command or a pattern `command` step may run before Gantry terminates it. | kind seconds accepts — validated as seconds set by environment → global config file → built-in default environment GANTRY_GATE_TIMEOUT_SECS global config file may set it |
| [sandbox].mode | auto | Whether Gantry's built-in process fence is best-effort, required, or disabled. | kind closed enum accepts auto · 0 · off · false · no · none · 1 · on · true · require · required validated as closed enum set by environment → global config file → built-in default environment GANTRY_SANDBOX global config file may set it |
| [sandbox].command | unset | Per-agent wrapper command used verbatim instead of Gantry's built-in process fence. | kind string list accepts — validated as string list set by environment → global config file environment GANTRY_SANDBOX_CMD global config file may set it |
| [stats].scan_roots | unset | Filesystem roots Gantry scans for project registries when building fleet statistics; unset scans the user's home directory. | kind string list accepts — validated as string list set by global config file environment — global config file may set it |
| [stats].context_target_tokens | 150000 | Peak-context threshold fleet statistics count sessions at or below; a sixth of it is the histogram bin width. | kind count accepts — validated as count set by global config file → built-in default environment — global config file may set it |
| [stats].context_split_tokens | 300000 | Peak-context threshold fleet statistics count sessions above separately, and the histogram's overflow boundary. | kind count accepts — validated as count set by global config file → built-in default environment — global config file may set it |
| [ui].window_title | auto | Whether Gantry updates the terminal window title while a run is active. | kind closed enum accepts auto · 0 · off · false · no · none · 1 · on · true · yes · require validated as closed enum set by environment → global config file → built-in default environment GANTRY_WINDOW_TITLE global config file may set it |
| [ui].external_agent | auto | Whether blocker investigation agents open in another terminal window or use the inline suspended session. | kind closed enum accepts auto · window · inline validated as closed enum set by environment → global config file → built-in default environment GANTRY_EXTERNAL_AGENT global config file may set it |
| [ui].terminal_command | [] | Terminal command argv the investigation agent launch is appended to; it wins before every probed launch tier. | kind string list accepts — validated as string list set by environment → global config file → built-in default environment GANTRY_TERMINAL_COMMAND global config file may set it |
| [ui].tui_animation | on | Whether the TUI animates; an off value selects reduced motion. | kind closed enum accepts auto · 0 · off · false · no · none · 1 · on · true · yes validated as closed enum set by environment → global config file → built-in default environment GANTRY_TUI_ANIMATE global config file may set it |
The environment variables
Environment variables — 37 rows exported from
src/engine/reference_dataset.rs
| variable | where it comes from | what it does |
|---|---|---|
| GANTRY_CLAUDE_BIN | harness.bin · the claude harness | Path to the registered harness CLI binary. |
| GANTRY_CLAUDE | harness.bin · the claude harness | Path to the registered harness CLI binary. |
| GANTRY_OPENCODE_BIN | harness.bin · the opencode harness | Path to the registered harness CLI binary. |
| GANTRY_CODEX_BIN | harness.bin · the codex harness | Path to the registered harness CLI binary. |
| GANTRY_GEMINI_BIN | harness.bin · the gemini harness | Path to the registered harness CLI binary. |
| GANTRY_CLAUDE_MODEL | harness.model · the claude harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. |
| GANTRY_MODEL | harness.model · the claude harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. |
| GANTRY_OPENCODE_MODEL | harness.model · the opencode harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. |
| GANTRY_CODEX_MODEL | harness.model · the codex harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. |
| GANTRY_GEMINI_MODEL | harness.model · the gemini harness | Main model pin for a registered harness; unset defers the choice to the harness CLI. |
| GANTRY_CLAUDE_SMALL_MODEL | harness.small_model · the claude harness | Small-model pin for a registered harness's utility calls. |
| GANTRY_COMMIT_MODEL | harness.small_model · the claude harness | Small-model pin for a registered harness's utility calls. |
| GANTRY_OPENCODE_SMALL_MODEL | harness.small_model · the opencode harness | Small-model pin for a registered harness's utility calls. |
| GANTRY_CODEX_SMALL_MODEL | harness.small_model · the codex harness | Small-model pin for a registered harness's utility calls. |
| GANTRY_GEMINI_SMALL_MODEL | harness.small_model · the gemini harness | Small-model pin for a registered harness's utility calls. |
| GANTRY_CLAUDE_ARGS | harness.args · the claude harness | Extra arguments appended to a registered harness invocation. |
| GANTRY_OPENCODE_ARGS | harness.args · the opencode harness | Extra arguments appended to a registered harness invocation. |
| GANTRY_CODEX_ARGS | harness.args · the codex harness | Extra arguments appended to a registered harness invocation. |
| GANTRY_GEMINI_ARGS | harness.args · the gemini harness | Extra arguments appended to a registered harness invocation. |
| GANTRY_ASSISTANT_MODEL | assistant.model | Model pin for the conversational Gantry Assistant; unset defers to the selected harness. |
| GANTRY_PLAN_EFFORT | effort.plan | Reasoning effort passed to the selected harness. |
| GANTRY_EFFORT | effort.build, effort.review, effort.util | Reasoning effort passed to the selected harness. |
| GANTRY_RETRY_DELAYS | retry.transient_delays | Backoff seconds between retry attempts for transient agent failures. |
| GANTRY_USAGE_RESET_MAX_RETRIES | retry.usage_reset_max_retries | Maximum usage-limit reset waits Gantry honours before giving up. |
| GANTRY_GATE_TIMEOUT_SECS | gate.timeout_secs | Wall-clock seconds a gate command or a pattern `command` step may run before Gantry terminates it. |
| GANTRY_SANDBOX | sandbox.mode | Whether Gantry's built-in process fence is best-effort, required, or disabled. |
| GANTRY_SANDBOX_CMD | sandbox.command | Per-agent wrapper command used verbatim instead of Gantry's built-in process fence. |
| GANTRY_WINDOW_TITLE | ui.window_title | Whether Gantry updates the terminal window title while a run is active. |
| GANTRY_EXTERNAL_AGENT | ui.external_agent | Whether blocker investigation agents open in another terminal window or use the inline suspended session. |
| GANTRY_TERMINAL_COMMAND | ui.terminal_command | Terminal command argv the investigation agent launch is appended to; it wins before every probed launch tier. |
| GANTRY_TUI_ANIMATE | ui.tui_animation | Whether the TUI animates; an off value selects reduced motion. |
| GANTRY_RUN | set on the interactive shell `gantry enter` opens in a run's worktree | Short name of the run whose worktree the shell is open in. |
| GANTRY_PLAN | set on the interactive shell `gantry enter` opens in a run's worktree | Plan name of the run whose worktree the shell is open in. |
| GANTRY_WORKTREE | set on the interactive shell `gantry enter` opens in a run's worktree | Absolute path of the run worktree the shell is rooted at. |
| GANTRY_ITEM | set on a script step the pattern driver runs, when the script step runs inside a `for` body | The task file the enclosing pattern body is currently on. |
| GANTRY_ORCHESTRATION | set on a script step the pattern driver runs | Repository-relative orchestration directory of the running pattern instance. |
| GANTRY_SOURCE_PLAN | set on a script step the pattern driver runs, when the run has a protected source-plan anchor | Repository-relative directory holding the run's protected copy of its source plan. |