Configuration
Every setting Gantry reads, its default and the tiers that can set it, and every GANTRY_* environment variable.
The settings
Configuration settings — 29 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 → project harness.toml → 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 → 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 → 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 → 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 → 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 lets the harness CLI or its own config choose. | 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 cheap utility calls on a registered harness. | 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 Agent assistant. | kind registered harness id accepts claude · opencode · codex · gemini validated as harness registry set by assistant CLI → 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 Agent assistant; unset lets the selected harness choose. | 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 used for this role. | kind closed enum accepts low · medium · high validated as closed enum set by sprint front matter → environment → global config file → built-in default environment GANTRY_PLAN_EFFORT global config file may set it |
| [effort].build | medium | Reasoning effort used for this role. | kind closed enum accepts low · medium · high validated as closed enum set by sprint front matter → environment → global config file → built-in default environment GANTRY_EFFORT global config file may set it |
| [effort].review | medium | Reasoning effort used for this role. | kind closed enum accepts low · medium · high validated as closed enum set by sprint front matter → environment → global config file → built-in default environment GANTRY_EFFORT global config file may set it |
| [effort].util | medium | Reasoning effort used for this role. | kind closed enum accepts low · medium · high validated as closed enum set by sprint 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 |
| [sandbox].mode | auto | Whether Gantry runs agents inside the built-in sandbox wrapper; an explicit disabled mode wins over a custom command. | kind closed enum accepts auto · 0 · off · false · no · none · 1 · on · true · require · required · bwrap 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 | Custom sandbox wrapper command used instead of Gantry's built-in bubblewrap wrapper unless sandbox mode is disabled. | kind string list accepts — validated as string list set by environment → global config file environment GANTRY_SANDBOX_CMD global config file may set it |
| [sandbox].confinement_check | true | Whether unsandboxed runs check that agents did not modify the main checkout. | kind boolean accepts true · false · 1 · 0 · on · off · yes · no · none validated as boolean set by environment → global config file → built-in default environment GANTRY_CONFINEMENT_CHECK 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 target line used to bucket fleet statistics sessions. | 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 split line used to bucket fleet statistics sessions. | 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].tui_animation | on | Whether the TUI uses animated visual 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 — 35 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 lets the harness CLI or its own config choose. |
| GANTRY_MODEL | harness.model · the claude harness | Main model pin for a registered harness; unset lets the harness CLI or its own config choose. |
| GANTRY_OPENCODE_MODEL | harness.model · the opencode harness | Main model pin for a registered harness; unset lets the harness CLI or its own config choose. |
| GANTRY_CODEX_MODEL | harness.model · the codex harness | Main model pin for a registered harness; unset lets the harness CLI or its own config choose. |
| GANTRY_GEMINI_MODEL | harness.model · the gemini harness | Main model pin for a registered harness; unset lets the harness CLI or its own config choose. |
| GANTRY_CLAUDE_SMALL_MODEL | harness.small_model · the claude harness | Small-model pin for cheap utility calls on a registered harness. |
| GANTRY_COMMIT_MODEL | harness.small_model · the claude harness | Small-model pin for cheap utility calls on a registered harness. |
| GANTRY_OPENCODE_SMALL_MODEL | harness.small_model · the opencode harness | Small-model pin for cheap utility calls on a registered harness. |
| GANTRY_CODEX_SMALL_MODEL | harness.small_model · the codex harness | Small-model pin for cheap utility calls on a registered harness. |
| GANTRY_GEMINI_SMALL_MODEL | harness.small_model · the gemini harness | Small-model pin for cheap utility calls on a registered harness. |
| 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 Agent assistant; unset lets the selected harness choose. |
| GANTRY_PLAN_EFFORT | effort.plan | Reasoning effort used for this role. |
| GANTRY_EFFORT | effort.build, effort.review, effort.util | Reasoning effort used for this role. |
| 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_SANDBOX | sandbox.mode | Whether Gantry runs agents inside the built-in sandbox wrapper; an explicit disabled mode wins over a custom command. |
| GANTRY_SANDBOX_CMD | sandbox.command | Custom sandbox wrapper command used instead of Gantry's built-in bubblewrap wrapper unless sandbox mode is disabled. |
| GANTRY_CONFINEMENT_CHECK | sandbox.confinement_check | Whether unsandboxed runs check that agents did not modify the main checkout. |
| GANTRY_WINDOW_TITLE | ui.window_title | Whether Gantry updates the terminal window title while a run is active. |
| GANTRY_TUI_ANIMATE | ui.tui_animation | Whether the TUI uses animated visual 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 was opened 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 was opened 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 loop or fan-out item body | The work item the enclosing loop or fan-out 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. |