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_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). |
UI and appearance
| Variable | Default | Description |
|---|---|---|
GROK_THEME |
built-in | Color theme. |
GROK_SHOW_THINKING_BLOCKS |
1 |
Show thinking/reasoning blocks in the TUI (1/0). |
GROK_GROUP_TOOL_VERBS |
1 |
Fold consecutive read/search/list tool rows (1/0). |
GROK_COLLAPSED_EDIT_BLOCKS |
0 |
Collapse edits to one-line +N/-M summaries (1/0). |
GROK_PROMPT_SUGGESTIONS |
1 |
Next-prompt ghost text after each turn (1/0). |
GROK_SCROLL_SPEED |
50 |
Mouse/trackpad scroll speed (1–100). |
GROK_SCROLL_MODE |
auto |
Scroll input: auto, wheel, or trackpad. |
GROK_SCROLL_LINES |
use config if unset | Lines per scroll tick (1–10). |
GROK_INVERT_SCROLL |
0 |
Reverse vertical scroll direction (1/0). |
GROK_DEFAULT_SELECTED_PERMISSION |
always_allow_all_sessions |
Preselected row on the first permission prompt. |
GROK_REMEMBER_TOOL_APPROVALS |
0 |
Show per-tool "Always allow …" options (1/0). |
GROK_MOUSE_REPORTING_TOGGLE |
0 |
Ctrl+R in scrollback toggles terminal mouse capture (1/0). |
GROK_DISPLAY_REFRESH_AUTO_CADENCE |
0 |
Match stream/scroll cadence to display refresh rate (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 |
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. |
disable_zdr_incompatible_tools |
[tools] |
true / false (default false) |
Restrict tools needing xAI-hosted output (video) under ZDR; without a configured output bucket they return setup guidance instead of generating. |
zdr_video_output_s3 |
[tools.zdr_video_output_s3] |
table | User-supplied S3 bucket for ZDR video output — see Video Output Storage under ZDR. |
file_toolset |
[toolset] |
standard (default) |
hashline |
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 |
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.
[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 |
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. Operator guide: Sandbox. Managed pins: Enterprise Deployments.
[session], [cli], and [hints]
| 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 |
show_tips |
[cli] |
true / false |
Startup tips. |
new_session_worktree_mode |
[hints] |
ask |
always |
fork_worktree_mode |
[hints] |
ask |
always |
[ui], [ui.display_refresh], and [ui.contextual_hints]
| Setting | Section | Values / default | Description |
|---|---|---|---|
compact_mode |
[ui] |
true / false (default false) |
Denser message padding. Also /compact-mode. |
screen_mode |
[ui] |
fullscreen (default when unset) |
minimal |
show_timestamps |
[ui] |
true / false (default true) |
Clock time next to messages. Also /timestamps. |
show_timeline |
[ui] |
true / false (default false) |
Per-turn tick rail instead of the scrollbar. |
page_flip_on_send |
[ui] |
true / false (default true) |
Snap the sent prompt to the top of the viewport. |
max_thoughts_width |
[ui] |
40–500 (default 120) |
Column width for the thoughts panel. |
combine_queued_prompts |
[ui] |
true / false (default false) |
Merge consecutive plain follow-ups into one turn. |
theme |
[ui] |
theme name or auto / system (default Grok Night) |
Color theme. auto follows OS light/dark. Also /theme. |
auto_dark_theme |
[ui] |
theme name (default groknight) |
Theme when theme = "auto" and the OS is dark. |
auto_light_theme |
[ui] |
theme name (default grokday) |
Theme when theme = "auto" and the OS is light. |
simple_mode |
[ui] |
true / false (default true) |
Readline prompt editing when true; experimental vim prompt keys when false. |
vim_mode |
[ui] |
true / false (default false) |
Vim keys in the scrollback (not the prompt). Also /vim-mode. |
prompt_suggestions |
[ui] |
true / false (default true) |
Next-prompt ghost text after each turn (Tab to accept). |
mouse_reporting_toggle |
[ui] |
true / false (default false) |
Ctrl+R in scrollback toggles terminal mouse capture. |
keep_text_selection |
[ui] |
flash (default) |
hold |
cursor_blink |
[ui] |
true / false (unset inherits terminal) |
Force blinking (true) or steady (false) block cursor. |
show_thinking_blocks |
[ui] |
true / false (default true) |
Show thinking/reasoning blocks while streaming. |
group_tool_verbs |
[ui] |
true / false (default true) |
Fold consecutive read/search/list tool rows into one summary. |
collapsed_edit_blocks |
[ui] |
true / false (default false) |
Show edits as one-line +N/-M summaries. |
render_mermaid |
[ui] |
auto (default) |
on |
scroll_speed |
[ui] |
1–100 (default 50) |
Mouse/trackpad scroll speed multiplier. |
scroll_mode |
[ui] |
auto (default) |
wheel |
scroll_lines |
[ui] |
1–10 (unset uses terminal profile) |
Lines per scroll tick for wheel and trackpad. |
invert_scroll |
[ui] |
true / false (default false) |
Reverse vertical scroll direction. |
permission_mode |
[ui] |
default |
ask |
default_selected_permission |
[ui] |
always_allow_all_sessions (default) |
allow_command_always |
remember_tool_approvals |
[ui] |
true / false (default false) |
Show per-tool "Always allow …" options. Restart required. |
cancel_subagents_on_turn_cancel |
[ui] |
ask (default when unset) |
always_stop |
hunk_tracker_mode |
[ui] |
agent_only (default) |
all_dirty |
fork_secondary_model |
[ui] |
model id (default: main default) | Model for the secondary agent when forking. |
voice_keybind_enabled |
[ui] |
true / false (default true) |
Enable Ctrl+Space / F8 for voice dictation (/voice still works when off). |
voice_capture_mode |
[ui] |
hold (default) |
toggle |
voice_stt_language |
[ui] |
language code or auto (default en / [voice].language) |
Speech-to-text language for dictation. |
auto_cadence_enabled |
[ui.display_refresh] |
true / false (default false) |
Match stream/scroll cadence to display refresh rate. Restart required. |
undo |
[ui.contextual_hints] |
true / false (default true) |
Ctrl+Z restores a wiped prompt draft. |
plan_mode |
[ui.contextual_hints] |
true / false (default true) |
Suggest plan mode (Shift+Tab) for planning-style prompts. |
image_input |
[ui.contextual_hints] |
true / false (default true) |
Clipboard image paste tip when the model accepts images. |
send_now |
[ui.contextual_hints] |
true / false (default true) |
After queuing a mid-turn follow-up, Enter on empty prompt sends now. |
small_screen |
[ui.contextual_hints] |
true / false (default true) |
Suggest /compact-mode on short terminals. |
word_select |
[ui.contextual_hints] |
true / false (default true) |
After double-click with fold/nav selection, point at Word select in settings. |
ssh_wrap |
[ui.contextual_hints] |
true / false (default true) |
Recommend grok wrap when SSH lacks a clipboard sink. |
[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 |
[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. |