---
title: "Settings reference"
summary: "Every configuration key, its type, default, allowed values and environment variable, generated from the settings table that also writes .env.example."
description: "Every driga configuration key with its type, default, allowed values and DRIGA_* environment variable."
generated: true
read_when:
  - "You want to change a default in config.toml or through the environment."
  - "A DRIGA_* variable is rejected as unknown and you want the valid names."
---

Driga reads `config.toml` and the process environment. Precedence is explicit
flags, then environment, then the TOML file, then the defaults below. Empty
environment values count as unset, and dotenv files are never loaded. An
unknown `DRIGA_*` name is an error. Restart the collector after changing its
configuration; the CLI and hooks reload on every invocation.

Find and edit the file with `driga config path`, `driga config show` and
`driga config edit`. List settings are file-only and have no environment
variable.

## Summary

| Key | Type | Default | Environment |
|---|---|---|---|
| [`motion`](#motion) | string | `on` | `DRIGA_MOTION` |
| [`roots`](#roots) | list | empty | file only |
| [`root_depth`](#root_depth) | int | `3` | `DRIGA_ROOT_DEPTH` |
| [`exclude`](#exclude) | list | `**/node_modules`, `**/.tmp/**` | file only |
| [`stalled_after`](#stalled_after) | duration | `10m` | `DRIGA_STALLED_AFTER` |
| [`orphan_min_age`](#orphan_min_age) | duration | `10m` | `DRIGA_ORPHAN_MIN_AGE` |
| [`capture_text`](#capture_text) | string | `titles` | `DRIGA_CAPTURE_TEXT` |
| [`open_cmd`](#open_cmd) | string | empty | `DRIGA_OPEN_CMD` |
| [`no_service_hint`](#no_service_hint) | bool | `false` | `DRIGA_NO_SERVICE_HINT` |
| [`ui.theme`](#uitheme) | string | `system` | `DRIGA_UI_THEME` |
| [`adapters.claude.enabled`](#adaptersclaudeenabled) | bool | `true` | `DRIGA_ADAPTERS_CLAUDE_ENABLED` |
| [`adapters.codex.enabled`](#adapterscodexenabled) | bool | `true` | `DRIGA_ADAPTERS_CODEX_ENABLED` |
| [`adapters.gemini.enabled`](#adaptersgeminienabled) | bool | `true` | `DRIGA_ADAPTERS_GEMINI_ENABLED` |
| [`adapters.copilot.enabled`](#adapterscopilotenabled) | bool | `true` | `DRIGA_ADAPTERS_COPILOT_ENABLED` |
| [`orphans.extra_signatures`](#orphansextra_signatures) | list | empty | file only |
| [`machine.disk_free_min`](#machinedisk_free_min) | size | `0` | `DRIGA_MACHINE_DISK_FREE_MIN` |
| [`summaries.enabled`](#summariesenabled) | bool | `false` | `DRIGA_SUMMARIES_ENABLED` |
| [`summaries.model`](#summariesmodel) | string | `haiku` | `DRIGA_SUMMARIES_MODEL` |
| [`cleanup.worktree_idle`](#cleanupworktree_idle) | duration | `168h` | `DRIGA_CLEANUP_WORKTREE_IDLE` |
| [`cleanup.regenerable`](#cleanupregenerable) | list | `node_modules/`, `target/`, `.venv/`, `venv/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `.gradle/`, `.terraform/` | file only |
| [`fleet.serve`](#fleetserve) | bool | `false` | `DRIGA_FLEET_SERVE` |
| [`fleet.listen`](#fleetlisten) | string | empty | `DRIGA_FLEET_LISTEN` |
| [`fleet.share_text`](#fleetshare_text) | string | `titles` | `DRIGA_FLEET_SHARE_TEXT` |
| [`fleet.enroll_window`](#fleetenroll_window) | duration | `10m` | `DRIGA_FLEET_ENROLL_WINDOW` |
| [`fleet.allow_any_address`](#fleetallow_any_address) | bool | `false` | `DRIGA_FLEET_ALLOW_ANY_ADDRESS` |
| [`inbox.alerts`](#inboxalerts) | string | `waiting` | `DRIGA_INBOX_ALERTS` |
| [`inbox.alert_after`](#inboxalert_after) | duration | `0s` | `DRIGA_INBOX_ALERT_AFTER` |
| [`inbox.alert_repeat`](#inboxalert_repeat) | duration | `5m` | `DRIGA_INBOX_ALERT_REPEAT` |
| [`inbox.jump_terminal`](#inboxjump_terminal) | bool | `false` | `DRIGA_INBOX_JUMP_TERMINAL` |
| [`intake.otlp`](#intakeotlp) | bool | `false` | `DRIGA_INTAKE_OTLP` |
| [`intake.listen`](#intakelisten) | string | `127.0.0.1:7418` | `DRIGA_INTAKE_LISTEN` |

## General

Top-level keys of `config.toml`.

### motion

Event-bound motion in the terminal Flow map.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `on` | on or off | `DRIGA_MOTION` |

### roots

Additional repository discovery roots; ~ expands to HOME.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| list | empty | file-only; empty = session working directories only | file only |

### root_depth

Repository discovery depth.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| int | `3` | 0..max int; zero = roots only | `DRIGA_ROOT_DEPTH` |

### exclude

Repository discovery exclusions.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| list | `**/node_modules`, `**/.tmp/**` | file-only; empty = no exclusions | file only |

### stalled_after

Quiet busy-session threshold.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `10m` | 0..2562047h47m16.854775807s; zero = default 10m | `DRIGA_STALLED_AFTER` |

### orphan_min_age

Minimum orphan candidate age.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `10m` | 0..2562047h47m16.854775807s; zero = no age minimum | `DRIGA_ORPHAN_MIN_AGE` |

### capture_text

Local text capture policy.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `titles` | titles or snippets | `DRIGA_CAPTURE_TEXT` |

### open_cmd

Editor command; \{cwd\} is substituted.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | empty | empty = auto-detect | `DRIGA_OPEN_CMD` |

### no_service_hint

Suppress optional service hints.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false | `DRIGA_NO_SERVICE_HINT` |

## Terminal UI

The `[ui]` table.

### ui.theme

Palette for the whole terminal UI: light, dark, or system to follow the terminal.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `system` | system, light or dark | `DRIGA_UI_THEME` |

## Agent adapters

One `[adapters.<name>]` table per agent.

### adapters.claude.enabled

Enable Claude session discovery.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `true` | true or false | `DRIGA_ADAPTERS_CLAUDE_ENABLED` |

### adapters.codex.enabled

Enable Codex session discovery.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `true` | true or false | `DRIGA_ADAPTERS_CODEX_ENABLED` |

### adapters.gemini.enabled

Enable Gemini session discovery.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `true` | true or false | `DRIGA_ADAPTERS_GEMINI_ENABLED` |

### adapters.copilot.enabled

Enable Copilot hook and process discovery.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `true` | true or false | `DRIGA_ADAPTERS_COPILOT_ENABLED` |

## Orphans

The `[orphans]` table.

### orphans.extra_signatures

Additional signature files; ~ expands to HOME.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| list | empty | file-only; empty = built-in signatures | file only |

## Machine health

The `[machine]` table.

### machine.disk_free_min

Low disk free-space limit. Zero uses the smaller of 10% of the volume or 20 GB (decimal). Replaces cleanup.low_disk_\* warning thresholds.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| size | `0` | 0..18446744073709551615 bytes; optional KiB/MiB/GiB suffix; zero = automatic | `DRIGA_MACHINE_DISK_FREE_MIN` |

## Summaries

The `[summaries]` table. Summaries run your installed Claude CLI on demand.

### summaries.enabled

Enable optional local Claude summaries.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false | `DRIGA_SUMMARIES_ENABLED` |

### summaries.model

Model selection passed to the Claude CLI.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `haiku` | nonempty | `DRIGA_SUMMARIES_MODEL` |

## Cleanup

The `[cleanup]` table.

### cleanup.worktree_idle

Idle worktree cleanup eligibility.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `168h` | 0..2562047h47m16.854775807s; zero = no idle minimum | `DRIGA_CLEANUP_WORKTREE_IDLE` |

### cleanup.regenerable

Additional regenerable relative directories (merged with defaults).

| Type | Default | Allowed | Environment |
|---|---|---|---|
| list | `node_modules/`, `target/`, `.venv/`, `venv/`, `dist/`, `build/`, `.next/`, `__pycache__/`, `.gradle/`, `.terraform/` | file-only; empty = built-in directories | file only |

## Fleet

The `[fleet]` table for paired machines.

### fleet.serve

Enable optional fleet serving.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false; requires fleet.listen | `DRIGA_FLEET_SERVE` |

### fleet.listen

Fleet TCP listener address.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | empty | required with fleet.serve; explicit private IP/interface, public addresses require allow_any_address | `DRIGA_FLEET_LISTEN` |

### fleet.share_text

Fleet export text policy, bounded by local capture policy.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `titles` | none, titles or snippets | `DRIGA_FLEET_SHARE_TEXT` |

### fleet.enroll_window

Fleet enrollment duration.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `10m` | 1ns..10m; zero rejected | `DRIGA_FLEET_ENROLL_WINDOW` |

### fleet.allow_any_address

Permit explicit non-loopback fleet listener.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false | `DRIGA_FLEET_ALLOW_ANY_ADDRESS` |

## Inbox and alerts

The `[inbox]` table.

### inbox.alerts

Desktop alerts for attention and optionally completions.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `waiting` | waiting, all or off | `DRIGA_INBOX_ALERTS` |

### inbox.alert_after

Alert only when a wait is still open this long after it began.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `0s` | 0..2562047h47m16.854775807s; zero = alert immediately | `DRIGA_INBOX_ALERT_AFTER` |

### inbox.alert_repeat

Minimum interval between alerts for one session.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| duration | `5m` | 0..2562047h47m16.854775807s; zero = no throttle | `DRIGA_INBOX_ALERT_REPEAT` |

### inbox.jump_terminal

Opt in to bringing a proven macOS terminal window to front.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false | `DRIGA_INBOX_JUMP_TERMINAL` |

## OTLP intake

The `[intake]` table for the optional loopback OTLP receiver.

### intake.otlp

Enable optional loopback OTLP/HTTP JSON intake.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| bool | `false` | true or false | `DRIGA_INTAKE_OTLP` |

### intake.listen

OTLP intake TCP listener address.

| Type | Default | Allowed | Environment |
|---|---|---|---|
| string | `127.0.0.1:7418` | loopback IP and port 0..65535; zero = ephemeral port | `DRIGA_INTAKE_LISTEN` |

## Path overrides

Relative values resolve against the working directory at startup.

| Variable | Default | Purpose |
|---|---|---|
| `DRIGA_CONFIG` | $XDG_CONFIG_HOME/driga/config.toml or ~/.config/driga/config.toml | Configuration file override. |
| `DRIGA_DATA_DIR` | Linux: $XDG_DATA_HOME/driga or ~/.local/share/driga; macOS: ~/Library/Application Support/driga | Database and fleet data directory override. |
| `DRIGA_SPOOL_DIR` | Linux: $XDG_STATE_HOME/driga/events or ~/.local/state/driga/events; macOS: ~/Library/Application Support/driga/events | Hook/ack spool directory override. |

## Internal names

Driga sets these for its own child processes and tests. They are accepted so
those processes start cleanly; they are not configuration.

| Variable | Kind | Purpose |
|---|---|---|
| `DRIGA_CHAT_SOCKET` | path | Chat broker socket for the MCP child of one Chat turn. |
| `DRIGA_CHAT_CONVERSATION` | id | Chat conversation of the MCP child's turn. |
| `DRIGA_CHAT_TOKEN` | secret | Per-turn token tying the MCP child's approval requests to its turn. |
| `DRIGA_CHAT_READ_ONLY` | marker | 1 keeps the Chat MCP child read-only. |
| `DRIGA_INTERNAL` | marker | 1 suppresses recursive hooks from Driga-owned Claude subprocesses. |
| `DRIGA_FIXTURE_OUTPUT` | path | Fixture generator output directory (tests only). |
| `DRIGA_COLLECTOR_HEAP_CHILD` | marker | 1 selects isolated collector heap-test child. |
| `DRIGA_FLEET_HEAP_CHILD` | marker | 1 selects isolated fleet heap-test child. |
| `DRIGA_OTLP_TRACES_ADDED` | marker | 1 records enhanced telemetry installed by Driga in Claude settings. |
| `DRIGA_JSON_WATCH_CHILD` | marker | 1 selects isolated NDJSON watch-test child. |
| `DRIGA_TEST_MCP_PROCESS` | marker | 1 selects isolated MCP-test child. |