Configuration reference¶
Every configuration section, with its keys, types, and defaults. All
sections are optional — omit a section to accept its defaults. Settings
live in ~/.gdc/config.toml (user) or <project>/.gdc/config.toml
(project); see Overview for file locations and precedence.
Paths may use ~ for your home directory; gdc expands it.
[provider]¶
How to reach the model. You can set a single endpoint, or define several named profiles and choose which is active.
| Key | Type | Default | Description |
|---|---|---|---|
base_url |
string | (local default) | The OpenAI-compatible endpoint URL. |
model |
string | — | The model name to request. |
api_key |
string | — | API key for hosted endpoints. Never printed in help or errors. |
active |
string | — | Name of the profile under [provider.profiles] to use. |
[provider]
base_url = "http://localhost:11434/v1"
model = "qwen2.5-coder:14b-instruct"
# Optional: named profiles you can switch between.
active = "local"
[provider.profiles.local]
base_url = "http://localhost:11434/v1"
model = "qwen2.5-coder:14b-instruct"
[provider.profiles.hosted]
base_url = "https://api.example.com/v1"
model = "some-hosted-model"
api_key = "sk-..."
When active names a profile, its fields are used; anything the profile
omits falls back to the top-level [provider] fields.
[storage]¶
| Key | Type | Default | Description |
|---|---|---|---|
path |
string | ~/.gdc/sessions.db |
Where sessions are saved. |
[permissions]¶
Rules that shape which actions run freely, prompt you, or are refused. Your rules add to a built-in safety baseline; where an allow and a deny overlap, deny wins. See Permissions.
[permissions.bash]¶
| Key | Type | Default | Description |
|---|---|---|---|
allow |
list of strings | [] |
Command names to allow without prompting. |
deny |
list of strings | [] |
Command names to always refuse. |
[permissions.path]¶
| Key | Type | Default | Description |
|---|---|---|---|
allow |
list of strings | [] |
Glob patterns for paths the agent may access outside the project. |
deny |
list of strings | [] |
Glob patterns for paths to always refuse. |
[permissions.bash]
allow = ["jq", "rg"]
deny = ["aws"]
[permissions.path]
allow = ["~/work/scratch/**"]
deny = ["~/.aws/**"]
[profile.<name>]¶
Extra permission rules for your own profiles
(the ones you define under ~/.gdc/agents/ or a project's .gdc/agents/).
Built-in profiles keep their shipped behavior and ignore these overrides.
Each rule is an entry with three fields:
| Field | Type | Description |
|---|---|---|
permission |
string | The action kind, e.g. edit, bash, tool. |
pattern |
string | A glob the target must match. |
action |
string | allow, ask, or deny. |
[[profile.reviewer.rules]]
permission = "edit"
pattern = "*"
action = "deny"
[[profile.reviewer.rules]]
permission = "edit"
pattern = "docs/**"
action = "allow"
Later, more specific rules override earlier blanket ones.
[mcp.servers.<name>]¶
External tool servers. gdc
detects the transport from the fields you set: a command means a local
program, a url means a remote service.
Local program:
| Key | Type | Default | Description |
|---|---|---|---|
command |
string | (required) | The program to launch. |
args |
list of strings | [] |
Arguments passed to it. |
env |
table | {} |
Extra environment variables. |
trusted |
bool | false |
Allow its tools without prompting. |
Remote service:
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | (required) | The service URL (http/https). |
auth_header |
string | — | Value sent as the Authorization header. |
headers |
table | {} |
Extra request headers. |
trusted |
bool | false |
Allow its tools without prompting. |
[skills]¶
| Key | Type | Default | Description |
|---|---|---|---|
paths |
list of strings | [] |
Extra directories to scan for skills. |
[agents]¶
Where to find your custom profiles.
| Key | Type | Default | Description |
|---|---|---|---|
paths |
list of strings | [] |
Extra directories to scan for profile files. |
watch_profile_dirs |
bool | true |
Reload profiles automatically when the files change. |
[output_styles]¶
Default reply style.
| Key | Type | Default | Description |
|---|---|---|---|
default |
string | — | Style applied when none is chosen per run. |
paths |
list of strings | [] |
Extra directories to scan for custom styles. |
[agent]¶
Fine-tuning of the conversation loop.
| Key | Type | Default | Description |
|---|---|---|---|
context_collapse_window |
integer | (off) | When set to N ≥ 1, keeps the most recent N messages verbatim while condensing older context to save room. |
[task]¶
Limits for coordinated multi-agent work.
| Key | Type | Default | Description |
|---|---|---|---|
max_parallel_workers |
integer | 2 |
How many subagents may run at once for one parent. |
worker_token_budget_per_turn |
"half" | "full" | integer |
"half" |
How the parent's token budget is shared with subagents. |
spawn_budget_per_turn |
integer | 10 |
Soft cap on subagent spawns per turn. |
coordinator_turn_wallclock_secs |
integer | 600 |
Time limit for one coordinator turn. |
resume_interrupted_workers_on_startup |
bool | false |
Re-launch subagents interrupted by a restart. |
idle_timeout_secs |
integer | 0 (off) |
Archive finished subagent records after this many idle seconds. |
auto_continue_on_worker_completion |
bool | false |
Continue the parent automatically when a subagent finishes. |
auto_continue_max_chain |
integer | 5 |
Cap on consecutive automatic continuations. |
See the Admin guide for the durability options that matter on a server.
[plugin.plugins.<name>]¶
Per-plugin settings.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Whether the plugin loads. |
trusted |
bool | false |
Allow its tools without prompting. |
call_timeout_secs |
integer | (host default) | Time limit for one plugin call. |
[memory]¶
Persistent memory behavior.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Master switch for loading memory into sessions. |
inject_user |
bool | true |
Include user-scope notes. |
inject_project |
bool | true |
Include project-scope notes. |
inject_local |
bool | true |
Include local-scope notes. |
max_index_bytes_per_scope |
integer | 4096 |
Cap on how much of each scope's index is loaded. |
[hooks]¶
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Master switch for hooks. |
default_timeout_secs |
integer | 5 |
Default time limit for a hook. |
Each handler is an entry:
| Field | Type | Description |
|---|---|---|
event |
string | pre_tool_use, post_tool_use, on_message, or on_compact. |
command |
string | The program to run. |
timeout_secs |
integer | Optional per-entry time limit. |
An optional matcher narrows when it fires:
[hooks]
enabled = true
default_timeout_secs = 5
[[hooks.entries]]
event = "pre_tool_use"
command = "/usr/local/bin/audit.sh"
timeout_secs = 2
[hooks.entries.matcher]
tool = "Bash"
[tui]¶
Terminal-app appearance.
| Key | Type | Default | Description |
|---|---|---|---|
theme |
string | "dark" |
"dark" or "light". |
[tui.notifications]¶
| Key | Type | Default | Description |
|---|---|---|---|
flash_enabled |
bool | true |
Flash the screen when attention is needed. |
toast_enabled |
bool | true |
Show pop-up notices. |
bell_enabled |
bool | false |
Ring the terminal bell. |
[grants]¶
| Key | Type | Default | Description |
|---|---|---|---|
file_mirror |
bool | true |
Also mirror remembered approvals into the project's config file (in addition to gdc's own store). |
[sandbox]¶
Experimental
The sandbox is an evolving, defense-in-depth layer. Its options may change.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | true |
Master switch. |
read_denylist_extra |
list of strings | [] |
Extra path globs to keep unreadable. |
Subsections [sandbox.plan_mode] (with bash_whitelist) and
[sandbox.ui] (with enable_global_approve) refine plan-mode command
allowances and approval behavior.
[swarm]¶
TLS settings for distributed swarm.
Experimental
Distributed swarm is an advanced, evolving capability.
| Key | Type | Default | Description |
|---|---|---|---|
self_signed_tls |
bool | false |
Generate and use a self-signed certificate. |
self_signed_sans |
list of strings | [] |
Extra names to include in the certificate. |
tls_ca |
string (path) | — | A certificate authority bundle to pin when connecting. |