Documentation 2026-06-22 00:00 UTC to 2026-07-02 06:57 UTC

1# Settings1# Settings

2 2 

3Settings live in `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`). Specify only the values you want to override; everything else falls back to built-in defaults. Settings can also be changed from the TUI Settings modal.3Grok Build offers a variety of configurations to suit your needs, many of which are made directly available in the TUI under `/settings`.

4 4 

5```text5Settings are persisted under `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`). To configure the default home directory, you can set `$GROK_HOME`.

6[ui]

7scroll_speed = 50 # mouse-wheel / trackpad scroll speed, 1-100 (higher = faster)

8vim_mode = false # vim-style scrollback navigation keys

9 6 

10[session]7For MCP servers, marketplaces, skills, plugins, and hooks, see [Skills, Plugins, and Marketplaces](/build/features/skills-plugins-marketplaces).

11auto_compact_threshold_percent = 85 # auto-compact at this % of context window8 

9## Scopes

10 

11| Scope | Path | Use for |

12| --- | --- | --- |

13| Environment | `GROK_*` (and related) variables | Session / CI overrides |

14| User | `~/.grok/config.toml` (or `$GROK_HOME/config.toml`) | Personal defaults |

15| Project | `.grok/config.toml` in the repo | Repo-shared MCP, plugins, and permission rules |

16| Managed | `~/.grok/managed_config.toml`, `/etc/grok/managed_config.toml` | Enterprise-served defaults |

17| Requirements | `~/.grok/requirements.toml`, `/etc/grok/requirements.toml` | Policy pins |

18 

19Project configs are limited to MCP servers, plugins, and permission rules, not full user configs. For more on scope merge order, sandoxing, and managed deployments, see [Enterprise Deployment](/build/enterprise).

20 

21## Verification

22 

23To confirm which configs are picked up by Grok Build, run the following command:

24 

25```bash customLanguage="bash"

26grok inspect

12```27```

13 28 

14## File toolset (hashline edits)29## Example `config.toml`

15 30 

16By default Grok edits files with the standard toolset (`read_file`, `search_replace`, `grep`). You can switch to the anchor-based hashline toolset (`hashline_read`, `hashline_edit`, `hashline_grep`), which reads and edits files using stable line anchors instead of exact string matches:31Copy into `$GROK_HOME/config.toml`, or `~/.grok/config.toml` when `GROK_HOME` is unset. Prefer `/settings` for UI, notifications, and other in-app options.

17 32 

18```text33```toml customLanguage="toml"

19[toolset]34[models]

20file_toolset = "hashline" # "standard" (default) or "hashline"35default = "grok-build" # recommended for coding / agent sessions

36web_search = "grok-4.3" # model used by client-side web_search tool

21 37 

22[toolset.hashline]38[model."grok-4.3"]

23scheme = "chunk" # "chunk" (default) or "content_only"39model = "grok-4.3" # id sent to the API

24hash_len = 3 # anchor hash length, 1-4 (default 3)40base_url = "https://api.x.ai/v1" # provider endpoint

25chunk_size = 8 # chunk size for the chunk scheme (default 8)41name = "Grok 4.3" # shown in model picker

42description = "Grok 4.3 from xAI"

43env_key = "XAI_API_KEY" # env var holding the API key

44api_backend = "responses" # chat_completions | responses | messages

45temperature = 0.7

46top_p = 0.95

47max_completion_tokens = 8192

48context_window = 1000000

49extra_headers = { "x-api-key" = "xai-..." }

50supports_backend_search = true # if the endpoint supports Grok-hosted server-side search tools

51 

52[mcp_servers.filesystem]

53command = "npx"

54args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]

55enabled = true

56startup_timeout_sec = 30

57tool_timeout_sec = 6000

58 

59[mcp_servers.linear]

60url = "https://mcp.linear.app/mcp"

61headers = { "Authorization" = "Bearer ${LINEAR_API_KEY}", "x-mcp-session-id" = "{{session_id}}" }

26```62```

27 63 

28The two toolsets are mutually exclusive. The `[toolset.hashline]` parameters only apply when `file_toolset = "hashline"`.64## TOML Values

65 

66For the full list of `config.toml` keys, see [TOML Values](/build/settings/reference#toml-values).

67 

68## Environment variables

69 

70For the full list of environment variables, see [Environment variables](/build/settings/reference#environment-variables).

1#### Settings

2 

3# Reference

4 

5## Environment variables

6 

7### Paths and auth

8 

9| Variable | Default | Description |

10| --- | --- | --- |

11| `GROK_HOME` | `~/.grok` | Home for config, auth, sessions, skills, plugins, and logs. |

12| `XAI_API_KEY` | — | API key when not using browser/session login (CI and headless). |

13 

14### Models and updates

15 

16| Variable | Default | Description |

17| --- | --- | --- |

18| `GROK_DEFAULT_MODEL` | catalog / config | Session default model (same idea as `-m` / `--model`). |

19| `GROK_WEB_SEARCH_MODEL` | built-in | Model used by the `web_search` tool. |

20| `GROK_MODELS_BASE_URL` | — | Custom inference base URL; model list from `{base}/models`. |

21| `GROK_MODELS_LIST_URL` | `{GROK_MODELS_BASE_URL}/models` | Override model-list URL when it differs from the default. |

22| `GROK_XAI_API_BASE_URL` | `https://api.x.ai/v1` | xAI API base for API-key auth. |

23| `GROK_DISABLE_AUTOUPDATER` | unset (updates allowed) | If set, suppress auto-updater for this process (CI/containers). |

24 

25### Tools, sandbox, and features

26 

27| Variable | Default | Description |

28| --- | --- | --- |

29| `GROK_SANDBOX` | `off` | Sandbox profile: `off`, `workspace`, `read-only`, `strict` (or a custom profile name). Same as `--sandbox`. |

30| `GROK_SANDBOX_AUTO_ALLOW_BASH` | `0` | Auto-allow bash inside an active sandbox (`1`/`0`). |

31| `GROK_RESPECT_GITIGNORE` | use config if unset | Force gitignore filtering for search/read tools (`1`/`0`); overrides `[tools] respect_gitignore`. |

32| `GROK_WEB_FETCH` | `0` | Enable the `web_fetch` tool (`1`/`0`). Off by default for security. |

33| `GROK_WEB_FETCH_PROXY` | — | Egress proxy URL for `web_fetch`. |

34| `GROK_MEMORY` | `0` | Enable cross-session memory (`1`/`0`). |

35| `GROK_SUBAGENTS` | `0` | Enable subagents / the task tool (`1`/`0`). |

36| `GROK_AGENT` | `grok-build` | Built-in agent name, profile, or absolute path to an agent definition. |

37| `GROK_SHOW_THINKING_BLOCKS` | `0` | Show reasoning/thinking blocks in the TUI (`1`/`0`). |

38| `GROK_WRITE_FILE` | `1` | Disable the `write` tool with `0` (read-only sessions). |

39| `GROK_TOOL_SEARCH` | `1` | On-demand MCP tool discovery for large toolsets (`1`/`0`). |

40| `GROK_LSP_TOOLS` | `0` | Enable the LSP code-intel tool (`1`/`0`). |

41 

42### MCP, logging, and proxy

43 

44| Variable | Default | Description |

45| --- | --- | --- |

46| `GROK_MCP_STARTUP_TIMEOUT_SECS` | `30` | Global MCP startup handshake timeout in **seconds**. Per-server `startup_timeout_sec` still wins. |

47| `MCP_TIMEOUT` | same stack | Claude-compatible MCP startup timeout in **milliseconds** (checked before `GROK_MCP_STARTUP_TIMEOUT_SECS`). |

48| `GROK_LOG_FILE` | — | Write logs to this path (useful when the TUI captures stderr). |

49| `RUST_LOG` | — | Log filter for `GROK_LOG_FILE` and headless stderr (for example `debug`). |

50| `GROK_CRASH_HANDLER` | `0` | On panic, write a report under `$GROK_HOME/crash/` (`1`/`0`). |

51| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | system | Standard HTTP(S) proxy variables for outbound traffic. |

52 

53### Cursor / Claude compatibility scanners

54 

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

56 

57| Variable | Description |

58| --- | --- |

59| `GROK_CURSOR_SKILLS_ENABLED` | Scan Cursor skills directories. |

60| `GROK_CURSOR_RULES_ENABLED` | Scan `.cursor/rules/`. |

61| `GROK_CURSOR_AGENTS_ENABLED` | Scan Cursor agent definitions. |

62| `GROK_CURSOR_MCPS_ENABLED` | Scan Cursor `mcp.json`. |

63| `GROK_CURSOR_HOOKS_ENABLED` | Scan Cursor hooks. |

64| `GROK_CLAUDE_SKILLS_ENABLED` | Scan Claude skills. |

65| `GROK_CLAUDE_RULES_ENABLED` | Scan Claude rules. |

66| `GROK_CLAUDE_AGENTS_ENABLED` | Scan `CLAUDE.md` / `CLAUDE.local.md`. |

67| `GROK_CLAUDE_MCPS_ENABLED` | Scan Claude MCP config. |

68| `GROK_CLAUDE_HOOKS_ENABLED` | Scan Claude hooks. |

69 

70## TOML Values

71 

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

73 

74### `[models]`

75 

76| Setting | Values / default | Description |

77| --- | --- | --- |

78| `default` | model id (for example `"grok-build"`) | Model used for new sessions. |

79| `web_search` | model id | Model used by the client `web_search` tool. |

80| `default_reasoning_effort` | effort level if supported | Default reasoning effort for the default model. |

81| `session_summary` | model id | Model used for session summaries. |

82| `image_description` | model id | Model used for image description. |

83| `extra_headers` | map | Headers applied to every model (per-model keys win). |

84| `temperature` / `top_p` / `max_completion_tokens` | numbers | Global sampling defaults. |

85| `max_retries` | number | Global inference retry default. |

86| `stream_tool_calls` | `true` / `false` | Global tool-call streaming request shape (some BYOK endpoints need `false`). |

87| `allowed_models` | glob list | Restrict model picker / default / `-m` selection. |

88| `hidden_models` | id list | Hide from the picker (still usable via `-m`). |

89| `disabled_models` | id list | Remove from the catalog (wins over hidden). |

90 

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

92 

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

94 

95| Setting | Values / default | Description |

96| --- | --- | --- |

97| `model` | string | Model id sent to the API. |

98| `base_url` | URL | Provider endpoint. |

99| `name` | string | Label in the model picker. |

100| `description` | string | Optional description. |

101| `api_key` | string | Inline API key (prefer `env_key`). |

102| `env_key` | env var name | Environment variable holding the API key. |

103| `api_backend` | `chat_completions` | `responses` | `messages` | Protocol. |

104| `temperature` / `top_p` / `max_completion_tokens` | numbers | Sampling. |

105| `context_window` | tokens | Context window size (drives auto-compact timing). |

106| `extra_headers` | map | Per-request headers. |

107| `supports_backend_search` | `true` / `false` | Whether the endpoint supports Grok-hosted server-side search tools. |

108| `supports_reasoning_effort` / `reasoning_effort` | bool / effort | Reasoning controls when supported. |

109| `stream_tool_calls` | `true` / `false` | Per-model tool-call streaming. |

110| `max_retries` / `inference_idle_timeout_secs` | numbers | Reliability. |

111 

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

113 

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

115 

116**stdio**

117 

118| Setting | Values / default | Description |

119| --- | --- | --- |

120| `command` | string | Executable (for example `npx`). |

121| `args` | string array | Arguments. |

122| `env` | map | Process environment. |

123| `cwd` | path | Working directory for the process. |

124 

125**HTTP / remote**

126 

127| Setting | Values / default | Description |

128| --- | --- | --- |

129| `url` | URL | HTTP/SSE MCP endpoint. |

130| `headers` | map | Request headers. |

131| `bearer_token_env_var` | env var name | Inject `Authorization: Bearer` from an environment variable. |

132 

133**Common**

134 

135| Setting | Values / default | Description |

136| --- | --- | --- |

137| `enabled` | `true` | Enable or disable the server. |

138| `startup_timeout_sec` | `30` | Startup handshake timeout (seconds). |

139| `tool_timeout_sec` | `6000` | Default per-tool-call timeout (seconds). |

140| `tool_timeouts` | map name → seconds | Per-tool timeout overrides. |

141 

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

143 

144| Setting | Section | Values / default | Description |

145| --- | --- | --- | --- |

146| `respect_gitignore` | `[tools]` | `true` / `false` (default `false`) | When `true`, search and read tools skip gitignored files. |

147| `file_toolset` | `[toolset]` | `standard` (default) | `hashline` | File edit tool scheme. |

148| `timeout_secs` | `[toolset.bash]` | seconds (default `120`) | Foreground bash command timeout. |

149| `output_byte_limit` | `[toolset.bash]` | bytes (default `20000`) | Max captured bash output. |

150| `max_timeout_secs` | `[toolset.bash]` | seconds (default `36000`) | Cap on model-requested foreground timeouts. |

151| `auto_background_on_timeout` | `[toolset.bash]` | `true` / `false` (default `true`) | Auto-background the command on timeout. |

152| `proxy_endpoint` | `[toolset.web_fetch]` | URL | Egress proxy for `web_fetch`. |

153| `allowed_domains` | `[toolset.web_fetch]` | string array | Domain allowlist override for `web_fetch`. |

154 

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

156 

157| Setting | Values / default | Description |

158| --- | --- | --- |

159| `profile` | `off` (default) | `workspace` | `read-only` | `strict` (or custom) | Filesystem sandbox profile. Custom profile names are defined in `sandbox.toml`. |

160| `auto_allow_bash` | `true` / `false` (default `false`) | Skip bash permission prompts when a sandbox profile is active. |

161 

162### `sandbox.toml` custom profiles

163 

164Define 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.

165 

166```toml customLanguage="toml"

167[profiles.project]

168extends = "workspace"

169restrict_network = false

170read_only = ["/data"]

171read_write = ["/tmp/scratch"]

172# Kernel-enforced deny (read + write/rename). Entries with *, ?, or [ are globs.

173deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

174```

175 

176| Setting | Values / default | Description |

177| --- | --- | --- |

178| `extends` | `workspace` (default if omitted) | `devbox` | `read-only` | `strict` | Built-in profile to inherit. |

179| `restrict_network` | `true` / `false` | Restrict network access (Linux seccomp when enforced). |

180| `read_only` | path list | Additional read-only paths. |

181| `read_write` | path list | Additional read-write paths. |

182| `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`). |

183 

184A 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).

185 

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

187 

188| Setting | Section | Values / default | Description |

189| --- | --- | --- | --- |

190| `auto_compact_threshold_percent` | `[session]` | `0–100` (default `85`) | Auto-compact when context usage reaches this percent. |

191| `load_envrc` | `[session]` | `true` / `false` (default `true`) | Inject `.envrc` variables into bash. |

192| `auto_update` | `[cli]` | `true` / `false` (default on when unset) | Check for CLI updates on launch. |

193| `channel` | `[cli]` | `stable` | `alpha` | Release channel preference. |

194| `show_tips` | `[cli]` | `true` / `false` | Startup tips. |

195 

196### `[permission]`

197 

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

199 

200| Setting | Values | Description |

201| --- | --- | --- |

202| `allow` / `deny` / `ask` | rule string arrays | Compact rules, for example `Bash(git *)`, `Read(src/**)`, `Edit(**/*.rs)`, `MCPTool(server__*)`. |

203| `rules` | array of `{ action, tool, pattern? }` | Verbose form. `action`: `allow` | `deny` | `ask`. `tool`: `any` | `bash` | `edit` | `read` | `grep` | `mcp` | `webfetch`. |

204 

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

206 

207| Setting | Section | Values / default | Description |

208| --- | --- | --- | --- |

209| `web_fetch` | `[features]` | `true` / `false` | Enable the `web_fetch` tool. |

210| `lsp_tools` | `[features]` | `true` / `false` (default off) | Expose the LSP tool. |

211| `write_file` | `[features]` | `true` / `false` (default on) | Enable the `write` tool. |

212| `tool_search` | `[features]` | `true` / `false` (default on) | MCP tool search / discovery. |

213| `enabled` | `[subagents]` | `true` / `false` | Subagent / task tool master switch. |

214| `toggle` | `[subagents.toggle]` | map of subagent → bool | Enable or disable individual subagent types. |

215| `models` | `[subagents.models]` | map of subagent → model id | Per-subagent model routing. |

216| `enabled` | `[memory]` | `true` / `false` (default off) | Cross-session memory master switch. |

217 

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

219 

220| Setting | Section | Values | Description |

221| --- | --- | --- | --- |

222| `paths` | `[skills]` / `[plugins]` | path lists | Extra skill or plugin directories. |

223| `disabled` | `[skills]` / `[plugins]` | name lists | Discover but do not activate. |

224| `enabled` | `[plugins]` | name lists | Explicitly enable plugins (project plugins may default off). |

225| `skills` / `rules` / `agents` / `mcps` / `hooks` | `[compat.cursor]` / `[compat.claude]` | `true` / `false` (default `true`) | Scan Cursor or Claude harness directories. |