#### Settings

# Reference

## Environment variables

### Paths and auth

| Variable | Default | Description |
| --- | --- | --- |
| `GROK_HOME` | `~/.grok` | Home for config, auth, sessions, skills, plugins, and logs. |
| `XAI_API_KEY` | — | API key when not using browser/session login (CI and headless). |

### Models and updates

| Variable | Default | Description |
| --- | --- | --- |
| `GROK_DEFAULT_MODEL` | catalog / config | Session default model (same idea as `-m` / `--model`). |
| `GROK_WEB_SEARCH_MODEL` | built-in | Model used by the `web_search` tool. |
| `GROK_MODELS_BASE_URL` | — | Custom inference base URL; model list from `{base}/models`. |
| `GROK_MODELS_LIST_URL` | `{GROK_MODELS_BASE_URL}/models` | Override model-list URL when it differs from the default. |
| `GROK_XAI_API_BASE_URL` | `https://api.x.ai/v1` | xAI API base for API-key auth. |
| `GROK_DISABLE_AUTOUPDATER` | unset (updates allowed) | If set, suppress auto-updater for this process (CI/containers). |

### Tools, sandbox, and features

| Variable | Default | Description |
| --- | --- | --- |
| `GROK_SANDBOX` | `off` | Sandbox profile: `off`, `workspace`, `read-only`, `strict` (or a custom profile name). Same as `--sandbox`. |
| `GROK_SANDBOX_AUTO_ALLOW_BASH` | `0` | Auto-allow bash inside an active sandbox (`1`/`0`). |
| `GROK_RESPECT_GITIGNORE` | use config if unset | Force gitignore filtering for search/read tools (`1`/`0`); overrides `[tools] respect_gitignore`. |
| `GROK_WEB_FETCH` | `0` | Enable the `web_fetch` tool (`1`/`0`). Off by default for security. |
| `GROK_WEB_FETCH_PROXY` | — | Egress proxy URL for `web_fetch`. |
| `GROK_MEMORY` | `0` | Enable cross-session memory (`1`/`0`). |
| `GROK_SUBAGENTS` | `0` | Enable subagents / the task tool (`1`/`0`). |
| `GROK_AGENT` | `grok-build` | Built-in agent name, profile, or absolute path to an agent definition. |
| `GROK_SHOW_THINKING_BLOCKS` | `0` | Show reasoning/thinking blocks in the TUI (`1`/`0`). |
| `GROK_WRITE_FILE` | `1` | Disable the `write` tool with `0` (read-only sessions). |
| `GROK_TOOL_SEARCH` | `1` | On-demand MCP tool discovery for large toolsets (`1`/`0`). |
| `GROK_LSP_TOOLS` | `0` | Enable the LSP code-intel tool (`1`/`0`). |

### MCP, logging, and proxy

| Variable | Default | Description |
| --- | --- | --- |
| `GROK_MCP_STARTUP_TIMEOUT_SECS` | `30` | Global MCP startup handshake timeout in **seconds**. Per-server `startup_timeout_sec` still wins. |
| `MCP_TIMEOUT` | same stack | Claude-compatible MCP startup timeout in **milliseconds** (checked before `GROK_MCP_STARTUP_TIMEOUT_SECS`). |
| `GROK_LOG_FILE` | — | Write logs to this path (useful when the TUI captures stderr). |
| `RUST_LOG` | — | Log filter for `GROK_LOG_FILE` and headless stderr (for example `debug`). |
| `GROK_CRASH_HANDLER` | `0` | On panic, write a report under `$GROK_HOME/crash/` (`1`/`0`). |
| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | system | Standard HTTP(S) proxy variables for outbound traffic. |

### Cursor / Claude compatibility scanners

All default **on** (`true` / `1` or `false` / `0`):

| Variable | Description |
| --- | --- |
| `GROK_CURSOR_SKILLS_ENABLED` | Scan Cursor skills directories. |
| `GROK_CURSOR_RULES_ENABLED` | Scan `.cursor/rules/`. |
| `GROK_CURSOR_AGENTS_ENABLED` | Scan Cursor agent definitions. |
| `GROK_CURSOR_MCPS_ENABLED` | Scan Cursor `mcp.json`. |
| `GROK_CURSOR_HOOKS_ENABLED` | Scan Cursor hooks. |
| `GROK_CLAUDE_SKILLS_ENABLED` | Scan Claude skills. |
| `GROK_CLAUDE_RULES_ENABLED` | Scan Claude rules. |
| `GROK_CLAUDE_AGENTS_ENABLED` | Scan `CLAUDE.md` / `CLAUDE.local.md`. |
| `GROK_CLAUDE_MCPS_ENABLED` | Scan Claude MCP config. |
| `GROK_CLAUDE_HOOKS_ENABLED` | Scan Claude hooks. |

## TOML Values

Project `.grok/config.toml` only contributes **`[mcp_servers]`**, **`[plugins]`**, and **`[permission]`**. Other sections belong in user config (`~/.grok/config.toml` or `$GROK_HOME/config.toml`).

### `[models]`

| Setting | Values / default | Description |
| --- | --- | --- |
| `default` | model id (for example `"grok-build"`) | Model used for new sessions. |
| `web_search` | model id | Model used by the client `web_search` tool. |
| `default_reasoning_effort` | effort level if supported | Default reasoning effort for the default model. |
| `session_summary` | model id | Model used for session summaries. |
| `image_description` | model id | Model used for image description. |
| `extra_headers` | map | Headers applied to every model (per-model keys win). |
| `temperature` / `top_p` / `max_completion_tokens` | numbers | Global sampling defaults. |
| `max_retries` | number | Global inference retry default. |
| `stream_tool_calls` | `true` / `false` | Global tool-call streaming request shape (some BYOK endpoints need `false`). |
| `allowed_models` | glob list | Restrict model picker / default / `-m` selection. |
| `hidden_models` | id list | Hide from the picker (still usable via `-m`). |
| `disabled_models` | id list | Remove from the catalog (wins over hidden). |

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

Custom / BYOK models (OpenAI-compatible or Anthropic Messages). Prefer `env_key` over hardcoding `api_key`.

| Setting | Values / default | Description |
| --- | --- | --- |
| `model` | string | Model id sent to the API. |
| `base_url` | URL | Provider endpoint. |
| `name` | string | Label in the model picker. |
| `description` | string | Optional description. |
| `api_key` | string | Inline API key (prefer `env_key`). |
| `env_key` | env var name | Environment variable holding the API key. |
| `api_backend` | `chat_completions` | `responses` | `messages` | Protocol. |
| `temperature` / `top_p` / `max_completion_tokens` | numbers | Sampling. |
| `context_window` | tokens | Context window size (drives auto-compact timing). |
| `extra_headers` | map | Per-request headers. |
| `supports_backend_search` | `true` / `false` | Whether the endpoint supports Grok-hosted server-side search tools. |
| `supports_reasoning_effort` / `reasoning_effort` | bool / effort | Reasoning controls when supported. |
| `stream_tool_calls` | `true` / `false` | Per-model tool-call streaming. |
| `max_retries` / `inference_idle_timeout_secs` | numbers | Reliability. |

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

String fields such as `url`, `command`, `args`, `env`, and `headers` support `${VAR}` expansion. Headers may also use `{{session_id}}`.

**stdio**

| Setting | Values / default | Description |
| --- | --- | --- |
| `command` | string | Executable (for example `npx`). |
| `args` | string array | Arguments. |
| `env` | map | Process environment. |
| `cwd` | path | Working directory for the process. |

**HTTP / remote**

| Setting | Values / default | Description |
| --- | --- | --- |
| `url` | URL | HTTP/SSE MCP endpoint. |
| `headers` | map | Request headers. |
| `bearer_token_env_var` | env var name | Inject `Authorization: Bearer` from an environment variable. |

**Common**

| Setting | Values / default | Description |
| --- | --- | --- |
| `enabled` | `true` | Enable or disable the server. |
| `startup_timeout_sec` | `30` | Startup handshake timeout (seconds). |
| `tool_timeout_sec` | `6000` | Default per-tool-call timeout (seconds). |
| `tool_timeouts` | map name → seconds | Per-tool timeout overrides. |

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

| Setting | Section | Values / default | Description |
| --- | --- | --- | --- |
| `respect_gitignore` | `[tools]` | `true` / `false` (default `false`) | When `true`, search and read tools skip gitignored files. |
| `file_toolset` | `[toolset]` | `standard` (default) | `hashline` | File edit tool scheme. |
| `timeout_secs` | `[toolset.bash]` | seconds (default `120`) | Foreground bash command timeout. |
| `output_byte_limit` | `[toolset.bash]` | bytes (default `20000`) | Max captured bash output. |
| `max_timeout_secs` | `[toolset.bash]` | seconds (default `36000`) | Cap on model-requested foreground timeouts. |
| `auto_background_on_timeout` | `[toolset.bash]` | `true` / `false` (default `true`) | Auto-background the command on timeout. |
| `proxy_endpoint` | `[toolset.web_fetch]` | URL | Egress proxy for `web_fetch`. |
| `allowed_domains` | `[toolset.web_fetch]` | string array | Domain allowlist override for `web_fetch`. |

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

| Setting | Values / default | Description |
| --- | --- | --- |
| `profile` | `off` (default) | `workspace` | `read-only` | `strict` (or custom) | Filesystem sandbox profile. Custom profile names are defined in `sandbox.toml`. |
| `auto_allow_bash` | `true` / `false` (default `false`) | Skip bash permission prompts when a sandbox profile is active. |

### `sandbox.toml` custom profiles

Define custom profiles in `~/.grok/sandbox.toml` (user) or `.grok/sandbox.toml` (project). Activate with `[sandbox] profile = "…"` in `config.toml`, `--sandbox`, or `GROK_SANDBOX`. Built-in names (`off`, `workspace`, `read-only`, `strict`, `devbox`) cannot be redefined as custom profiles.

```toml customLanguage="toml"
[profiles.project]
extends = "workspace"
restrict_network = false
read_only = ["/data"]
read_write = ["/tmp/scratch"]
# Kernel-enforced deny (read + write/rename). Entries with *, ?, or [ are globs.
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]
```

| Setting | Values / default | Description |
| --- | --- | --- |
| `extends` | `workspace` (default if omitted) | `devbox` | `read-only` | `strict` | Built-in profile to inherit. |
| `restrict_network` | `true` / `false` | Restrict network access (Linux seccomp when enforced). |
| `read_only` | path list | Additional read-only paths. |
| `read_write` | path list | Additional read-write paths. |
| `deny` | path or **glob** list | Kernel-enforced deny for read and write/rename. An entry is a glob if it contains `*`, `?`, or `[` (for example `**/.env`, `**/*.pem`). |

A non-empty `deny` list is enforced at the kernel level when the sandbox can be applied. On Linux, read-deny requires `bubblewrap`. For managed deployments and policy, see [Enterprise Deployment](/build/enterprise).

### `[session]` and `[cli]`

| Setting | Section | Values / default | Description |
| --- | --- | --- | --- |
| `auto_compact_threshold_percent` | `[session]` | `0–100` (default `85`) | Auto-compact when context usage reaches this percent. |
| `load_envrc` | `[session]` | `true` / `false` (default `true`) | Inject `.envrc` variables into bash. |
| `auto_update` | `[cli]` | `true` / `false` (default on when unset) | Check for CLI updates on launch. |
| `channel` | `[cli]` | `stable` | `alpha` | Release channel preference. |
| `show_tips` | `[cli]` | `true` / `false` | Startup tips. |

### `[permission]`

Project-scoped and user-scoped. Evaluation order: **deny > ask > allow**.

| Setting | Values | Description |
| --- | --- | --- |
| `allow` / `deny` / `ask` | rule string arrays | Compact rules, for example `Bash(git *)`, `Read(src/**)`, `Edit(**/*.rs)`, `MCPTool(server__*)`. |
| `rules` | array of `{ action, tool, pattern? }` | Verbose form. `action`: `allow` | `deny` | `ask`. `tool`: `any` | `bash` | `edit` | `read` | `grep` | `mcp` | `webfetch`. |

### `[features]`, `[subagents]`, and `[memory]`

| Setting | Section | Values / default | Description |
| --- | --- | --- | --- |
| `web_fetch` | `[features]` | `true` / `false` | Enable the `web_fetch` tool. |
| `lsp_tools` | `[features]` | `true` / `false` (default off) | Expose the LSP tool. |
| `write_file` | `[features]` | `true` / `false` (default on) | Enable the `write` tool. |
| `tool_search` | `[features]` | `true` / `false` (default on) | MCP tool search / discovery. |
| `enabled` | `[subagents]` | `true` / `false` | Subagent / task tool master switch. |
| `toggle` | `[subagents.toggle]` | map of subagent → bool | Enable or disable individual subagent types. |
| `models` | `[subagents.models]` | map of subagent → model id | Per-subagent model routing. |
| `enabled` | `[memory]` | `true` / `false` (default off) | Cross-session memory master switch. |

### `[skills]`, `[plugins]`, and `[compat.*]`

| Setting | Section | Values | Description |
| --- | --- | --- | --- |
| `paths` | `[skills]` / `[plugins]` | path lists | Extra skill or plugin directories. |
| `disabled` | `[skills]` / `[plugins]` | name lists | Discover but do not activate. |
| `enabled` | `[plugins]` | name lists | Explicitly enable plugins (project plugins may default off). |
| `skills` / `rules` / `agents` / `mcps` / `hooks` | `[compat.cursor]` / `[compat.claude]` | `true` / `false` (default `true`) | Scan Cursor or Claude harness directories. |