# Configuration reference

> Schema-oriented keys for ~/.grok/config.toml and pager.toml: [cli], [models], [ui], [features], [session], [tools], [mcp_servers], [skills], [compat], permissions, sandbox, and env var counterparts.

- Repository: xai-org/grok-build
- GitHub: https://github.com/xai-org/grok-build
- Human docs: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458
- Complete Markdown: https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/llms-full.txt

## Source Files

- `crates/codegen/xai-grok-pager/docs/user-guide/05-configuration.md`
- `crates/codegen/xai-grok-config-types/src/lib.rs`
- `crates/codegen/xai-grok-config-types/src/mcp.rs`
- `crates/codegen/xai-grok-config-types/src/permission.rs`
- `crates/codegen/xai-grok-config/src/validation.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/features.rs`
- `crates/codegen/xai-grok-env/src`
- `crates/codegen/xai-grok-paths/src/lib.rs`

---

---
title: "Configuration reference"
description: "Schema-oriented keys for ~/.grok/config.toml and pager.toml: [cli], [models], [ui], [features], [session], [tools], [mcp_servers], [skills], [compat], permissions, sandbox, and env var counterparts."
---

Grok Build resolves settings from CLI flags, environment variables, TOML layers under `$GROK_HOME` (default `~/.grok`), managed/requirements policy files, and built-in defaults. The primary user schema is `config.toml`; TUI layout and appearance live in `pager.toml`; OS sandbox profiles live in `sandbox.toml`. Typed sections are deserialized in the shell/agent config types (`CliConfig`, `ModelsConfig`, `UiConfig`, `Features`, `SessionConfig`, `PermissionConfig`, `McpServerConfig`, `SkillsConfig`, `CompatConfigToml`, `SandboxSettingsConfig`).

## Config surfaces

| Path | Role |
|------|------|
| `~/.grok/config.toml` | Main user schema (`[cli]`, `[models]`, `[ui]`, `[features]`, …) |
| `~/.grok/pager.toml` | TUI terminal, animation, prompt, scrollback, blocks |
| `~/.grok/sandbox.toml` | Custom OS sandbox profiles |
| `~/.grok/managed_config.toml` | Org-managed user layer (often synced) |
| `~/.grok/requirements.toml` | User requirements layer (policy pins) |
| `/etc/grok/managed_config.toml` | System managed layer (Unix) |
| `/etc/grok/requirements.toml` | System requirements layer (Unix) |
| `.grok/config.toml` | Project-scoped `[mcp_servers]`, `[plugins]`, `[permission]`, and `[mcp] max_output_bytes` |
| `.grok/sandbox.toml` | Project custom profiles (additive names only) |

`GROK_HOME` replaces `~/.grok` for all user-global paths. `grok_home()` creates the directory if needed; loaders that must not mistake a project `.grok` for the user home use `user_grok_home()` and return `None` when no home resolves.

:::files
~/.grok/
├── config.toml
├── pager.toml
├── sandbox.toml
├── managed_config.toml
├── requirements.toml
├── auth.json
├── sessions/
├── memory/
├── skills/
├── plugins/
├── agents/
├── lsp.json
└── logs/
::

## Precedence

Highest wins unless a resolver documents a special walk:

1. **CLI flags** — e.g. `--model`, `--sandbox`, `--yolo`
2. **Environment variables** — e.g. `XAI_API_KEY`, `GROK_MEMORY`, `GROK_SANDBOX`
3. **User `config.toml`** — `$GROK_HOME/config.toml`
4. **Managed / requirements** — `managed_config.toml`, `requirements.toml` (user, system, macOS MDM)
5. **Built-in defaults**

Boolean feature flags commonly use: **requirement → CLI → env → user config → managed → remote settings → default** (`BoolFlag` / `ConfigSource`).

Exceptions:

| Knob | Walk |
|------|------|
| `[features] remote_fetch` | Requirements (MDM → system → user) → managed → system managed → user config → default `true`. No env/remote tier (air-gapped safety). |
| `[permission]` rules | Merged across scopes; severity `deny` > `ask` > `allow` (not last-write-wins). |
| Project MCP/plugins | `.grok/config.toml` (cwd) > `<repo-root>/.grok/config.toml` > `~/.grok/config.toml` (same name replaces). |
| `[toolset.ask_user_question]` | requirements → env → user → managed → defaults. |

Dump the resolved view with `grok inspect`. How-to editing and workflows: [Configure Grok](/configure-grok).

## Project-scoped sections

Project `.grok/config.toml` contributes only:

- `[mcp_servers]`
- `[plugins]`
- `[permission]`
- `[mcp] max_output_bytes`

Other tables load from user/global layers only.

---

## `config.toml` schema

Omit keys you do not need; absent keys use defaults or remote/managed pins.

### `[cli]`

| Key | Type | Notes |
|-----|------|--------|
| `auto_update` | bool | Check for updates on launch |
| `channel` | string | Release channel (e.g. stable/alpha); remote may supply fallback |
| `use_leader` | bool | Leader-mode preference |
| `show_tips` | bool | Startup tips |
| `worktree_type` | string | Worktree backend preference |
| `session_registry` | bool | Session registry hooks |
| `minimum_version` | string | User floor; managed can raise via semver-max |
| `session_picker_grouped` | bool | Group sessions by repo in pickers |
| `dismissed_version` | string | Persisted dismiss state |
| `installer` / `npm_registry` | string | Installer metadata |

```toml
[cli]
auto_update = true
channel = "stable"
```

### `[models]` and `[model.<id>]`

**Global `[models]`** (applies when per-model fields are unset):

| Key | Type | Notes |
|-----|------|--------|
| `default` | string | Model for new sessions |
| `web_search` | string | Model for web_search tool |
| `session_summary` | string | Session summary model |
| `image_description` | string | Vision/transcription model |
| `prompt_suggestion` | string | Ghost-text suggestion model |
| `default_reasoning_effort` | string | Effort pin for default model |
| `allowed_models` | string[] | Glob allowlist for picker/`/model`/`-m` |
| `hidden_models` | string[] | Hide from picker (still usable via `-m`) |
| `disabled_models` | string[] | Remove from catalog (wins over hidden) |
| `agent_type` | string | Fallback agent type |
| `extra_headers` | map | Default request headers |
| `temperature` | float | Global sampling default |
| `top_p` | float | Global nucleus default |
| `max_completion_tokens` | u32 | Global completion cap |
| `max_retries` | u32 | Global retries (default often 8) |
| `inference_idle_timeout_secs` | u64 | Stream idle timeout |
| `stream_tool_calls` | bool | Stream tool-call deltas |

**Per-model `[model.<id>]`** (OpenAI-compatible / BYOK; override built-ins by id):

| Key | Type | Notes |
|-----|------|--------|
| `model` | string | Wire model id |
| `base_url` | string | OpenAI-compatible endpoint |
| `name` / `description` | string | Display metadata |
| `api_key` | string | Inline key |
| `env_key` | string or string[] | Env var(s); first set non-empty wins |
| `temperature` / `top_p` / `max_completion_tokens` | number | Sampling |
| `context_window` | number | Auto-compact sizing |
| `extra_headers` | map | Per-key override of global headers |

Credential order for a model: `api_key` → `env_key` → signed-in session → `XAI_API_KEY`.

```toml
[models]
default = "grok-build"
web_search = "grok-4.20-multi-agent"
temperature = 0.7
extra_headers = { "X-Request-Tags" = "team=example" }

[model.my-ollama]
model = "llama3.2"
base_url = "http://127.0.0.1:11434/v1"
name = "Local Llama"
env_key = "OLLAMA_API_KEY"
context_window = 128000
```

See [Custom models](/custom-models).

### `[ui]`

| Key | Type | Default / values | Notes |
|-----|------|------------------|--------|
| `simple_mode` | bool | `true` | Prompt editor: readline vs vim modal |
| `vim_mode` | bool | `false` | Scrollback vim keys (independent of `simple_mode`) |
| `screen_mode` | string | unset / `"minimal"` / `"fullscreen"` | Sticky TUI mode; CLI `/minimal` `/fullscreen` write it |
| `theme` | string | e.g. `groknight`, `auto` | Built-in theme or system auto |
| `auto_dark_theme` / `auto_light_theme` | string | — | Themes when `theme = "auto"` |
| `max_thoughts_width` | u16 | `120` | Reasoning column width |
| `default_selected_permission` | string | `always_allow_all_sessions` | First permission-menu cursor; also `allow_command_always`, `allow_once`, `reject` |
| `remember_tool_approvals` | bool | `false` | Show per-command “Always allow” rows |
| `show_thinking_blocks` | bool | `true` | Show thinking in scrollback |
| `group_tool_verbs` | bool | `true` | Fold consecutive read/search/list rows |
| `collapsed_edit_blocks` | bool | `false` | Edit as `+N/-M` until expanded |
| `compact_mode` | bool | — | Compact UI; also `/compact-mode` |
| `scroll_speed` | u8 | `50` (1–100) | Wheel/trackpad multiplier |
| `scroll_mode` | string | `auto` \| `wheel` \| `trackpad` | Input classification |
| `scroll_lines` | u8 | unset (1–10) | Explicit lines/tick for both devices |
| `invert_scroll` | bool | `false` | Natural scrolling |
| `prompt_suggestions` | bool | on when unset | Ghost-text after turns |
| `permission_mode` / `approval_mode` | string | — | Permission mode preference |
| `hunk_tracker_mode` | string | `agent_only` \| `all_dirty` \| `off` | Diff hunk tracking |
| `render_mermaid` | string | `auto` \| `on` \| `off` | Mermaid in scrollback |
| `cursor_blink` | bool | inherit terminal | Force block cursor blink |
| `mouse_reporting_toggle` | bool | `false` | Opt-in Ctrl+R mouse toggle (scrollback focus) |
| `cancel_subagents_on_turn_cancel` | string | `ask` \| `always_stop` \| `always_continue` | Cancel-turn subagent policy |

Env overrides (first load; do not write `config.toml`): `GROK_DEFAULT_SELECTED_PERMISSION`, `GROK_SCROLL_SPEED`, `GROK_SCROLL_MODE`, `GROK_SCROLL_LINES`, `GROK_INVERT_SCROLL`, `GROK_PROMPT_SUGGESTIONS`, `GROK_HUNK_TRACKER`.

#### `[ui.notifications]`

| Key | Type | Default | Notes |
|-----|------|---------|--------|
| `method` | string | `auto` | `auto` \| `osc9` \| `osc99` \| `osc777` \| `bel` \| `none` |
| `condition` | string | `unfocused` | `unfocused` \| `always` \| `never` |
| `idle_threshold_secs` | int | `3` | Unfocused delay before fire |
| `events` | string[] | turn_complete, approval_required | Plus session_ready, task_complete, agent_error |
| `sleep_prevention` | bool | `true` | Keep display awake on turns |
| `progress_bar` | bool | `true` | OSC 9;4 tab progress |
| `title.enabled` | bool | `true` | Terminal title updates |
| `title.items` | string[] | action-required, spinner, … | Title segments |

`[[ui.notifications.hooks]]`: `command`, `events`, `only_unfocused` (default true), `timeout_secs` (default 10). Hook env: `$GROK_EVENT`, `$GROK_MESSAGE`, `$GROK_SESSION_ID`.

#### `[ui.display_refresh]`

| Key | Type | Default | Notes |
|-----|------|---------|--------|
| `probe_enabled` | bool | on | Primary-display Hz probe |
| `auto_cadence_enabled` | bool | off | Derive paint cadence from probe |
| `floor_ms` / `ceiling_ms` | u32 | 8 / 16 | Auto-cadence clamps |
| `min_hz` / `max_hz` | u32 | 55 / 165 | Accepted probe band |

### `[features]`

| Key | Type | Typical default | Notes |
|-----|------|-----------------|--------|
| `telemetry` | bool / mode | off | Master anonymous telemetry; modes may include session-metrics/full/off |
| `feedback` | bool | true (product docs) | Feedback UX; remote may pin |
| `lsp_tools` | bool | false | Expose `lsp` tool |
| `codebase_indexing` | bool or glob list | true | Code graph; globs can include non-git dirs |
| `two_pass_compaction` | bool | false | Prefire compaction |
| `remote_fetch` | bool | true | Online model-catalog + settings fetches |
| `managed_config` | bool | true | Background managed-config sync |
| `web_fetch` | bool | false (resolver) | Web fetch tool |
| `tool_search` | bool | true | MCP tool search |
| `ask_user_question` | bool | true | Ask-user-question tool |
| `session_recap` | bool | true | `/recap` + return-from-away |
| `write_file` | bool | true | Write-file tool |
| `cancel_rewind` | bool | true | Ctrl+C restore prompt before activity |
| `auto_wake` | bool | true | Wake on background/subagent completion |
| `backend_tools` | bool | true | Server-side web_search / x_search |
| `video_gen` | bool | false | Video generation tool |
| `image_gen_model_override` | string | — | Imagine model pin |
| `non_git_warning` | bool | false | Warn outside git repos |
| `support_permission` | bool | — | Agent may request tool permission |
| `zdr_access_enabled` | bool | false | ZDR access gate |

```toml
[features]
telemetry = false
feedback = true
lsp_tools = false
codebase_indexing = true
two_pass_compaction = false
remote_fetch = true
```

### `[session]`

| Key | Type | Default | Notes |
|-----|------|---------|--------|
| `auto_compact_threshold_percent` | u8 | 85 | % of context window before auto-compact |
| `load_envrc` | bool | true | Inject `.envrc` into bash tool env |

Env: resolver chain for auto-compact (env / per-model / remote / default).

### `[tools]` and `[toolset.*]`

```toml
[tools]
respect_gitignore = false   # GROK_RESPECT_GITIGNORE overrides

[toolset.bash]
timeout_secs = 120.0
output_byte_limit = 20000

[toolset.ask_user_question]
timeout_enabled = true
timeout_secs = 1800

[toolset.web_fetch]
proxy_endpoint = "https://proxy.example.com"
allowed_domains = ["docs.rs", "x.ai"]
```

Env: `GROK_ASK_USER_QUESTION_TIMEOUT_ENABLED`, `GROK_ASK_USER_QUESTION_TIMEOUT_SECS`, `GROK_RESPECT_GITIGNORE`, `GROK_WEB_FETCH`.

`[toolset] file_toolset` may be `"standard"` or `"hashline"` (remote can set default; local wins when set).

### `[mcp_servers.<name>]`

Transport is untagged: **stdio** (`command` + `args`) or **HTTP/SSE** (`url`).

| Key | Type | Default | Notes |
|-----|------|---------|--------|
| `command` / `args` / `env` / `cwd` | stdio | — | Process transport; `cwd` not exposed to ACP yet |
| `url` | string | — | Streamable HTTP |
| `type` | string | — | `"sse"` or URL ending `/sse` selects SSE |
| `headers` | map | — | HTTP headers; may use `{{session_id}}` |
| `bearer_token_env_var` | string | — | Sets `Authorization: Bearer …` |
| `oauth_client_id` / `oauth_client_secret_env_var` / `oauth_scopes` | HTTP OAuth fields | — | Flat on transport |
| `oauth` | block | — | `{ client_id, client_secret_env_var, scopes, callback_port }` |
| `enabled` | bool | `true` | Disabled servers skipped |
| `startup_timeout_sec` | u64 | 30 | Init handshake |
| `tool_timeout_sec` | u64 | 6000 | Default tool call timeout |
| `tool_timeouts` | map | — | Per-tool seconds |
| `expose_image_base64` | bool | — | Keep base64 in tool text (~2× tokens) |

```toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 6000

[mcp_servers.remote]
url = "https://mcp.example.com/api/mcp"
headers = { "x-mcp-session-id" = "{{session_id}}" }
bearer_token_env_var = "MCP_TOKEN"
```

Global MCP defaults may also live under `[mcp]` (e.g. `max_output_bytes`, default 20_000). Management CLI: [MCP servers](/mcp-servers).

### `[permission]`

Two equivalent shapes.

**Structured rules:**

```toml
[permission]
rules = [
  { action = "allow", tool = "bash", pattern = "git *" },
  { action = "deny",  tool = "bash", pattern = "rm -rf *" },
  { action = "ask",   tool = "edit" },
]
```

| Field | Values | Notes |
|-------|--------|--------|
| `action` | `allow` \| `deny` \| `ask` | Default if omitted: **deny** (fail closed) |
| `tool` | `any` \| `bash` \| `edit` \| `read` \| `grep` \| `mcp` \| `webfetch` | Case-insensitive enum |
| `pattern` | string | Optional match string |
| `pattern_mode` | `glob` (default) \| `domain` | Domain mode for WebFetch hosts |

**Compact arrays** (same strings as `--allow` / `--deny`):

```toml
[permission]
allow = ["Bash(git *)", "Read", "Grep"]
deny  = ["Bash(rm -rf *)", "Read(/Users/you/private/**)"]
ask   = ["Edit"]
```

Rules load once per session from user, every project `.grok/config.toml` on the path to cwd, managed layers, and Claude-compat settings. Severity is always `deny` > `ask` > `allow`. Details: [Permissions and safety](/permissions-and-safety).

### `[sandbox]` (in `config.toml`)

| Key | Type | Notes |
|-----|------|--------|
| `profile` | string | `off`, `workspace`, `devbox`, `read-only`, `strict`, or custom name |
| `auto_allow_bash` | bool | Skip bash permission prompts while sandbox is active |

CLI `--sandbox` and env `GROK_SANDBOX` override. Full profile matrix: [Sandbox profiles](/sandbox).

### `[skills]`

| Key | Type | Notes |
|-----|------|--------|
| `paths` | string[] | Extra skill dirs or `SKILL.md` files (`~` expanded) |
| `ignore` | string[] | Path prefixes excluded after discovery |
| `disabled` | string[] | Names remain listed but inactive |

Discovery still scans `.grok` / `.agents` / vendor trees gated by `[compat]`. See [Skills](/skills).

### `[compat]`

Every cell defaults **on**. Env > `config.toml` > default.

```toml
[compat.cursor]
skills = true
rules = true
agents = true
mcps = true
hooks = true
sessions = true   # staged until foreign-session scanner + resume skill

[compat.claude]
skills = true
rules = true
agents = true
mcps = true
hooks = true
sessions = true

[compat.codex]
sessions = true   # non-session Codex cells are reserved/inert
```

`grok inspect` shows unresolved cells as `?` / `compatibilityStatus: "unresolved"`.

### `[plugins]`

```toml
[plugins]
paths = ["~/my-plugins/custom-tools"]
disabled = ["user/a1b2c3d4/noisy-plugin"]
```

See [Plugins](/plugins).

### `[memory]`

Requires experimental memory (`GROK_MEMORY=1` or `--experimental-memory`). Nested tables include `session`, `watcher`, `search`, `initial_injection`, `embedding` (see user guide and [Project rules and memory](/project-rules-and-memory)).

### `[subagents]`

```toml
[subagents]
enabled = true

[subagents.toggle]
explore = true
plan = false

[subagents.models]
explore = "grok-build"
```

Env: `GROK_SUBAGENTS`. See [Subagents and personas](/subagents).

### `[auth]` and OIDC

```toml
[auth]
auth_provider_command = "/usr/local/bin/my-auth-provider"
auth_provider_label = "Acme Corp"
auth_token_ttl = 3600

[grok_com_config.oidc]
issuer = "https://acme.okta.com"
client_id = "0oa..."
# scopes / audience optional
```

Env: `XAI_API_KEY`, `GROK_AUTH_PROVIDER_COMMAND`, `GROK_AUTH_PROVIDER_LABEL`, `GROK_AUTH_TOKEN_TTL`, `GROK_AUTH_EARLY_INVALIDATION_SECS`, `GROK_OIDC_ISSUER`, `GROK_OIDC_CLIENT_ID`. See [Authentication](/authentication).

### `[hints]`

Persisted “don’t ask again” UI prefs (written by TUI; editable by hand):

| Key | Default | Notes |
|-----|---------|--------|
| `project_picker_disabled` | false | Skip non-project directory picker |
| `memory_modal_fullscreen` | false | Memory modal fullscreen state |
| `new_session_worktree_mode` | `"never"` | `ask` \| `always` \| `never` for `/new` |
| `fork_worktree_mode` | `"ask"` | Same for `/fork` |

### `[telemetry]`

| Key | Notes |
|-----|--------|
| `events_url` / `events_api_key` | Private collector for product events |
| `mixpanel_enabled` | Product analytics off-switch |
| `trace_upload` | Session/trace upload |
| `otel_enabled` | External OTLP stream (`GROK_EXTERNAL_OTEL`) |
| `otel_metrics_exporter` / `otel_logs_exporter` | `otlp` \| `console` \| `none` |
| `otel_endpoint` / `otel_protocol` | Collector base + `http/protobuf` \| `grpc` |
| `otel_log_user_prompts` / `otel_log_tool_details` | Content gates (admins may lock via requirements) |

External OTEL auth uses `OTEL_EXPORTER_OTLP_HEADERS` (not stored in TOML).

### Other tables

| Section | Purpose |
|---------|---------|
| `[relay]` | `enabled` — session sharing; env `GROK_RELAY_SYNC_ENABLED` |
| `[hub]` | `url` — default Computer Hub WS for `grok workspace` only |
| `[doom_loop_recovery]` | `enabled`, `max_threshold`, `max_retries` (env > TOML > remote > default) |
| `[folder_trust]` | `enabled` — gate repo-local MCP/LSP until trusted (`GROK_FOLDER_TRUST`) |
| `[diagnostics]` | `crash_handler` |
| `[compaction]` | Nested memory flush / pruning |

---

## `pager.toml` (TUI appearance)

Location: `~/.grok/pager.toml`. Applied on restart (except where noted). Theme primary control is often `[ui] theme` in `config.toml`; layout lives here. See [Theming](/theming).

### `[terminal]`

| Key | Values | Notes |
|-----|--------|--------|
| `alt_screen` | `auto` \| `always` \| `never` | Alternate screen vs main scrollback |
| `minimal` | bool (legacy) | Superseded by `[ui] screen_mode` when set |

### `[animation]`

| Key | Default | Notes |
|-----|---------|--------|
| `fps` | 30 | Animation tick rate |
| `wave_rows` | 32 | Accent wave period |

### `[prompt]`

| Key | Default | Notes |
|-----|---------|--------|
| `collapse_unfocused` | true | Collapse prompt when scrollback focused |
| `mouse_hover` | true | Hover highlight |
| `show_prefix` | true | Prompt prefix character |

### `[scrollback.*]`

| Table | Selected keys |
|-------|----------------|
| `scrollback.layout` | `outer_vpad`, `outer_hpad_left/right`, `block_pad_left/right` |
| `scrollback.scrollbar` | `enabled`, `gap_left`, `gap_right` |
| `scrollback.scroll` | `margin`, `min_page_fraction`, `follow_indicator`, `follow_auto_select`, `follow_by_overscroll`, `anchor_on_fold`, `respect_manual_folds` (default **false**) |
| `scrollback.display` | `sticky_headers`, `tab_width`, `expandable_indicator*`, `selection_buttons`, `dim_accent` |
| `scrollback.blocks.edit` | `indent`, `vpad`, `expanded_by_default`, `dual_line_numbers`, `line_summary`, `hunk_separator` |
| `scrollback.blocks.prompt` | `vpad`, `show_prefix`, `min_lines` |
| `scrollback.blocks.thinking` | `animate`, `truncated_lines` |

`expanded_by_default` / `line_summary` on edit blocks override `[ui] collapsed_edit_blocks` when set.

### `[todo]`

`badge_format`: `"default"` (`2/5`) \| `"colon"` \| `"comma"`.

### Top-level

`disable_plugins = false` — hide hooks/plugins UI.

Keyboard shortcuts are **not** configurable in TOML. See [Keyboard shortcuts](/keyboard-shortcuts).

---

## `sandbox.toml` profiles

Not the same as `[sandbox]` in `config.toml`. Custom profiles:

```toml
[profiles.project]
extends = "workspace"
restrict_network = true
read_only = ["/data"]
read_write = ["/tmp/scratch"]
deny = ["**/.env", "**/*.pem"]
```

| Field | Notes |
|-------|--------|
| `extends` | Built-in base: workspace, devbox, read-only, strict (default workspace) |
| `restrict_network` | Child network block (Linux-enforced for read-only/strict) |
| `read_only` / `read_write` | Extra path grants |
| `deny` | Kernel-enforced read+write/rename deny; globs use `*`, `?`, `[`, `**` |

Built-in names cannot be redefined. Project file may **add** profile names only; conflicting same-name custom profiles: global wins, startup warning if definitions differ.

Activation: `grok --sandbox project`, `[sandbox] profile = "project"`, or `GROK_SANDBOX=project`.

---

## Environment variable counterparts

| Variable | Maps to / effect |
|----------|------------------|
| `GROK_HOME` | Root for config, auth, sessions, skills, plugins |
| `XAI_API_KEY` | API auth for CI/headless |
| `GROK_SANDBOX` | Sandbox profile |
| `GROK_MEMORY` | Cross-session memory on/off |
| `GROK_SUBAGENTS` | Subagents on/off |
| `GROK_WEB_FETCH` | web_fetch tool |
| `GROK_AGENT` | Custom agent path or name |
| `GROK_RESPECT_GITIGNORE` | Overrides `[tools] respect_gitignore` |
| `GROK_TELEMETRY_ENABLED` | Telemetry master |
| `GROK_FEEDBACK_ENABLED` | Feedback system |
| `GROK_EXTERNAL_OTEL` | External OTEL stream |
| `GROK_RELAY_SYNC_ENABLED` | Relay sync |
| `GROK_FOLDER_TRUST` | Folder-trust gate |
| `GROK_CLI_CHAT_PROXY_BASE_URL` | API proxy base (also `GROK_PRODUCTION_*` endpoint family) |
| `GROK_GATEWAY_URL` | Cloud sandbox gateway opt-in |
| `GROK_LOG_FILE` / `RUST_LOG` | Logging path and filter |
| `GROK_DEPLOYMENT_KEY` | Enterprise management API key |
| `GROK_MANAGED_CONFIG_FAIL_CLOSED` | Tighten requirements fail-closed |
| `GROK_DEFAULT_SELECTED_PERMISSION` | First permission-menu row |
| `GROK_SCROLL_*` / `GROK_INVERT_SCROLL` | Scroll UI |
| `GROK_ASK_USER_QUESTION_TIMEOUT_*` | Ask-question timeouts |
| `GROK_TWO_PASS_COMPACTION` | Two-pass compaction |
| `GROK_PROMPT_SUGGESTIONS` | Ghost-text suggestions |
| `GROK_HUNK_TRACKER` | Hunk tracker mode |
| `GROK_COMPACTION_MODE` | Compaction presentation mode |
| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP collector auth (never stored in TOML) |

Endpoint production defaults (override via env): cli-chat-proxy, assets, relay WS, gateway WS, ws origin — resolved in `xai-grok-env`.

---

## Verify resolved config

```bash
grok inspect
# optional: JSON / focus on compat cells and sources
```

Expect explicit sources (`requirement`, `cli`, `env`, `user_config`, `managed`, `remote`, `default`) for critical flags. Invalid requirements under fail-closed refuse startup; soft-load paths skip bad layers with logs.

## Related pages

<CardGroup>
  <Card title="Configure Grok" href="/configure-grok">
    Edit workflow, precedence narrative, and inspect usage.
  </Card>
  <Card title="Custom models" href="/custom-models">
    BYOK, OpenAI-compatible endpoints, and model selection.
  </Card>
  <Card title="MCP servers" href="/mcp-servers">
    Register, enable, and manage MCP transports.
  </Card>
  <Card title="Permissions and safety" href="/permissions-and-safety">
    Rule evaluation, modes, and hooks interaction.
  </Card>
  <Card title="Sandbox profiles" href="/sandbox">
    Built-in isolation and custom deny globs.
  </Card>
  <Card title="Theming" href="/theming">
    Themes, screen modes, and color capability.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Flags that override TOML at runtime.
  </Card>
</CardGroup>