Use this page as a searchable reference for Codex configuration files. For conceptual guidance and examples, start with Basic Config and Advanced Config.
config.toml
User-level configuration lives in ~/.codex/config.toml.
| Key | Type / Values | Details |
|---|---|---|
approval_policy | untrusted | on-failure | on-request | never | Controls when Codex pauses for approval before executing commands. |
chatgpt_base_url | string | Override the base URL used during the ChatGPT login flow. |
check_for_update_on_startup | boolean | Check for Codex updates on startup (set to false only when updates are centrally managed). |
cli_auth_credentials_store | file | keyring | auto | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
compact_prompt | string | Inline override for the history compaction prompt. |
developer_instructions | string | Additional developer instructions injected into the session (optional). |
disable_paste_burst | boolean | Disable burst-paste detection in the TUI. |
experimental_compact_prompt_file | string (path) | Load the compaction prompt override from a file (experimental). |
experimental_use_freeform_apply_patch | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`. |
experimental_use_unified_exec_tool | boolean | Legacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`. |
features.apply_patch_freeform | boolean | Expose the freeform `apply_patch` tool (experimental). |
features.child_agents_md | boolean | Append AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental). |
features.elevated_windows_sandbox | boolean | Enable the elevated Windows sandbox pipeline (experimental). |
features.exec_policy | boolean | Enforce rules checks for `shell`/`unified_exec` (experimental; on by default). |
features.experimental_windows_sandbox | boolean | Run the Windows restricted-token sandbox (experimental). |
features.powershell_utf8 | boolean | Force PowerShell UTF-8 output (defaults to true). |
features.remote_compaction | boolean | Enable remote compaction (ChatGPT auth only; experimental; on by default). |
features.remote_models | boolean | Refresh remote model list before showing readiness (experimental). |
features.shell_snapshot | boolean | Snapshot shell environment to speed up repeated commands (beta). |
features.shell_tool | boolean | Enable the default `shell` tool for running commands (stable; on by default). |
features.unified_exec | boolean | Use the unified PTY-backed exec tool (beta). |
features.web_search_request | boolean | Allow the model to issue web searches (stable). |
feedback.enabled | boolean | Enable feedback submission via `/feedback` across Codex surfaces (default: true). |
file_opener | vscode | vscode-insiders | windsurf | cursor | none | URI scheme used to open citations from Codex output (default: `vscode`). |
forced_chatgpt_workspace_id | string (uuid) | Limit ChatGPT logins to a specific workspace identifier. |
forced_login_method | chatgpt | api | Restrict Codex to a specific authentication method. |
hide_agent_reasoning | boolean | Suppress reasoning events in both the TUI and `codex exec` output. |
history.max_bytes | number | If set, caps the history file size in bytes by dropping oldest entries. |
history.persistence | save-all | none | Control whether Codex saves session transcripts to history.jsonl. |
include_apply_patch_tool | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
instructions | string | Reserved for future use; prefer `model_instructions_file` or `AGENTS.md`. |
mcp_oauth_callback_port | integer | Optional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS. |
mcp_oauth_credentials_store | auto | file | keyring | Preferred store for MCP OAuth credentials. |
mcp_servers.<id>.args | array<string> | Arguments passed to the MCP stdio server command. |
mcp_servers.<id>.bearer_token_env_var | string | Environment variable sourcing the bearer token for an MCP HTTP server. |
mcp_servers.<id>.command | string | Launcher command for an MCP stdio server. |
mcp_servers.<id>.cwd | string | Working directory for the MCP stdio server process. |
mcp_servers.<id>.disabled_tools | array<string> | Deny list applied after `enabled_tools` for the MCP server. |
mcp_servers.<id>.enabled | boolean | Disable an MCP server without removing its configuration. |
mcp_servers.<id>.enabled_tools | array<string> | Allow list of tool names exposed by the MCP server. |
mcp_servers.<id>.env | map<string,string> | Environment variables forwarded to the MCP stdio server. |
mcp_servers.<id>.env_http_headers | map<string,string> | HTTP headers populated from environment variables for an MCP HTTP server. |
mcp_servers.<id>.env_vars | array<string> | Additional environment variables to whitelist for an MCP stdio server. |
mcp_servers.<id>.http_headers | map<string,string> | Static HTTP headers included with each MCP HTTP request. |
mcp_servers.<id>.startup_timeout_ms | number | Alias for `startup_timeout_sec` in milliseconds. |
mcp_servers.<id>.startup_timeout_sec | number | Override the default 10s startup timeout for an MCP server. |
mcp_servers.<id>.tool_timeout_sec | number | Override the default 60s per-tool timeout for an MCP server. |
mcp_servers.<id>.url | string | Endpoint for an MCP streamable HTTP server. |
model | string | Model to use (e.g., `gpt-5-codex`). |
model_auto_compact_token_limit | number | Token threshold that triggers automatic history compaction (unset uses model defaults). |
model_context_window | number | Context window tokens available to the active model. |
model_instructions_file | string (path) | Replacement for built-in instructions instead of `AGENTS.md`. |
model_provider | string | Provider id from `model_providers` (default: `openai`). |
model_providers.<id>.base_url | string | API base URL for the model provider. |
model_providers.<id>.env_http_headers | map<string,string> | HTTP headers populated from environment variables when present. |
model_providers.<id>.env_key | string | Environment variable supplying the provider API key. |
model_providers.<id>.env_key_instructions | string | Optional setup guidance for the provider API key. |
model_providers.<id>.experimental_bearer_token | string | Direct bearer token for the provider (discouraged; use `env_key`). |
model_providers.<id>.http_headers | map<string,string> | Static HTTP headers added to provider requests. |
model_providers.<id>.name | string | Display name for a custom model provider. |
model_providers.<id>.query_params | map<string,string> | Extra query parameters appended to provider requests. |
model_providers.<id>.request_max_retries | number | Retry count for HTTP requests to the provider (default: 4). |
model_providers.<id>.requires_openai_auth | boolean | The provider uses OpenAI authentication (defaults to false). |
model_providers.<id>.stream_idle_timeout_ms | number | Idle timeout for SSE streams in milliseconds (default: 300000). |
model_providers.<id>.stream_max_retries | number | Retry count for SSE streaming interruptions (default: 5). |
model_providers.<id>.wire_api | chat | responses | Protocol used by the provider (defaults to `chat` if omitted). |
model_reasoning_effort | minimal | low | medium | high | xhigh | Adjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent). |
model_reasoning_summary | auto | concise | detailed | none | Select reasoning summary detail or disable summaries entirely. |
model_supports_reasoning_summaries | boolean | Force Codex to send reasoning metadata even for unknown models. |
model_verbosity | low | medium | high | Control GPT-5 Responses API verbosity (defaults to `medium`). |
notice.hide_full_access_warning | boolean | Track acknowledgement of the full access warning prompt. |
notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |
notice.hide_gpt5_1_migration_prompt | boolean | Track acknowledgement of the GPT-5.1 migration prompt. |
notice.hide_rate_limit_model_nudge | boolean | Track opt-out of the rate limit model switch reminder. |
notice.hide_world_writable_warning | boolean | Track acknowledgement of the Windows world-writable directories warning. |
notice.model_migrations | map<string,string> | Track acknowledged model migrations as old->new mappings. |
notify | array<string> | Command invoked for notifications; receives a JSON payload from Codex. |
oss_provider | lmstudio | ollama | Default local provider used when running with `--oss` (defaults to prompting if unset). |
otel.environment | string | Environment tag applied to emitted OpenTelemetry events (default: `dev`). |
otel.exporter | none | otlp-http | otlp-grpc | Select the OpenTelemetry exporter and provide any endpoint metadata. |
otel.exporter.<id>.endpoint | string | Exporter endpoint for OTEL logs. |
otel.exporter.<id>.headers | map<string,string> | Static headers included with OTEL exporter requests. |
otel.exporter.<id>.protocol | binary | json | Protocol used by the OTLP/HTTP exporter. |
otel.exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL exporter TLS. |
otel.exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL exporter TLS. |
otel.exporter.<id>.tls.client-private-key | string | Client private key path for OTEL exporter TLS. |
otel.log_user_prompt | boolean | Opt in to exporting raw user prompts with OpenTelemetry logs. |
otel.trace_exporter | none | otlp-http | otlp-grpc | Select the OpenTelemetry trace exporter and provide any endpoint metadata. |
otel.trace_exporter.<id>.endpoint | string | Trace exporter endpoint for OTEL logs. |
otel.trace_exporter.<id>.headers | map<string,string> | Static headers included with OTEL trace exporter requests. |
otel.trace_exporter.<id>.protocol | binary | json | Protocol used by the OTLP/HTTP trace exporter. |
otel.trace_exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL trace exporter TLS. |
otel.trace_exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL trace exporter TLS. |
otel.trace_exporter.<id>.tls.client-private-key | string | Client private key path for OTEL trace exporter TLS. |
profile | string | Default profile applied at startup (equivalent to `--profile`). |
profiles.<name>.* | various | Profile-scoped overrides for any of the supported configuration keys. |
profiles.<name>.experimental_use_freeform_apply_patch | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
profiles.<name>.experimental_use_unified_exec_tool | boolean | Legacy name for enabling unified exec; prefer `[features].unified_exec`. |
profiles.<name>.include_apply_patch_tool | boolean | Legacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`. |
profiles.<name>.oss_provider | lmstudio | ollama | Profile-scoped OSS provider for `--oss` sessions. |
project_doc_fallback_filenames | array<string> | Additional filenames to try when `AGENTS.md` is missing. |
project_doc_max_bytes | number | Maximum bytes read from `AGENTS.md` when building project instructions. |
project_root_markers | array<string> | List of project root marker filenames; used when searching parent directories for the project root. |
projects.<path>.trust_level | string | Mark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`). |
review_model | string | Optional model override used by `/review` (defaults to the current session model). |
sandbox_mode | read-only | workspace-write | danger-full-access | Sandbox policy for filesystem and network access during command execution. |
sandbox_workspace_write.exclude_slash_tmp | boolean | Exclude `/tmp` from writable roots in workspace-write mode. |
sandbox_workspace_write.exclude_tmpdir_env_var | boolean | Exclude `$TMPDIR` from writable roots in workspace-write mode. |
sandbox_workspace_write.network_access | boolean | Allow outbound network access inside the workspace-write sandbox. |
sandbox_workspace_write.writable_roots | array<string> | Additional writable roots when `sandbox_mode = "workspace-write"`. |
shell_environment_policy.exclude | array<string> | Glob patterns for removing environment variables after the defaults. |
shell_environment_policy.experimental_use_profile | boolean | Use the user shell profile when spawning subprocesses. |
shell_environment_policy.ignore_default_excludes | boolean | Keep variables containing KEY/SECRET/TOKEN before other filters run. |
shell_environment_policy.include_only | array<string> | Whitelist of patterns; when set only matching variables are kept. |
shell_environment_policy.inherit | all | core | none | Baseline environment inheritance when spawning subprocesses. |
shell_environment_policy.set | map<string,string> | Explicit environment overrides injected into every subprocess. |
show_raw_agent_reasoning | boolean | Surface raw reasoning content when the active model emits it. |
skills.config | array<object> | Per-skill enablement overrides stored in config.toml. |
skills.config.<index>.enabled | boolean | Enable or disable the referenced skill. |
skills.config.<index>.path | string (path) | Path to a skill folder containing `SKILL.md`. |
tool_output_token_limit | number | Token budget for storing individual tool/function outputs in history. |
tui | table | TUI-specific options such as enabling inline desktop notifications. |
tui.alternate_screen | auto | always | never | Control alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback). |
tui.animations | boolean | Enable terminal animations (welcome screen, shimmer, spinner) (default: true). |
tui.notifications | boolean | array<string> | Enable TUI notifications; optionally restrict to specific event types. |
tui.scroll_events_per_tick | number | Wheel event density used to normalize TUI2 scrolling. |
tui.scroll_invert | boolean | Invert mouse scroll direction in TUI2. |
tui.scroll_mode | auto | wheel | trackpad | Scroll interpretation mode for TUI2. |
tui.scroll_trackpad_accel_events | number | Trackpad events required to gain +1x acceleration. |
tui.scroll_trackpad_accel_max | number | Maximum acceleration multiplier for trackpad scrolling. |
tui.scroll_trackpad_lines | number | Baseline trackpad scroll sensitivity for TUI2. |
tui.scroll_wheel_like_max_duration_ms | number | Auto-mode wheel fallback duration threshold (ms). |
tui.scroll_wheel_lines | number | Lines per wheel notch for TUI2 scrolling. |
tui.scroll_wheel_tick_detect_max_ms | number | Auto-mode wheel tick detection threshold (ms). |
tui.show_tooltips | boolean | Show onboarding tooltips in the TUI welcome screen (default: true). |
windows_wsl_setup_acknowledged | boolean | Track Windows onboarding acknowledgement (Windows only). |
approval_policyuntrusted | on-failure | on-request | neverControls when Codex pauses for approval before executing commands.
chatgpt_base_urlstringOverride the base URL used during the ChatGPT login flow.
check_for_update_on_startupbooleanCheck for Codex updates on startup (set to false only when updates are centrally managed).
cli_auth_credentials_storefile | keyring | autoControl where the CLI stores cached credentials (file-based auth.json vs OS keychain).
compact_promptstringInline override for the history compaction prompt.
developer_instructionsstringAdditional developer instructions injected into the session (optional).
disable_paste_burstbooleanDisable burst-paste detection in the TUI.
experimental_compact_prompt_filestring (path)Load the compaction prompt override from a file (experimental).
experimental_use_freeform_apply_patchbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform` or `codex --enable apply_patch_freeform`.
experimental_use_unified_exec_toolbooleanLegacy name for enabling unified exec; prefer `[features].unified_exec` or `codex --enable unified_exec`.
features.apply_patch_freeformbooleanExpose the freeform `apply_patch` tool (experimental).
features.child_agents_mdbooleanAppend AGENTS.md scope/precedence guidance even when no AGENTS.md is present (experimental).
features.elevated_windows_sandboxbooleanEnable the elevated Windows sandbox pipeline (experimental).
features.exec_policybooleanEnforce rules checks for `shell`/`unified_exec` (experimental; on by default).
features.experimental_windows_sandboxbooleanRun the Windows restricted-token sandbox (experimental).
features.powershell_utf8booleanForce PowerShell UTF-8 output (defaults to true).
features.remote_compactionbooleanEnable remote compaction (ChatGPT auth only; experimental; on by default).
features.remote_modelsbooleanRefresh remote model list before showing readiness (experimental).
features.shell_snapshotbooleanSnapshot shell environment to speed up repeated commands (beta).
features.shell_toolbooleanEnable the default `shell` tool for running commands (stable; on by default).
features.unified_execbooleanUse the unified PTY-backed exec tool (beta).
features.web_search_requestbooleanAllow the model to issue web searches (stable).
feedback.enabledbooleanEnable feedback submission via `/feedback` across Codex surfaces (default: true).
file_openervscode | vscode-insiders | windsurf | cursor | noneURI scheme used to open citations from Codex output (default: `vscode`).
forced_chatgpt_workspace_idstring (uuid)Limit ChatGPT logins to a specific workspace identifier.
forced_login_methodchatgpt | apiRestrict Codex to a specific authentication method.
hide_agent_reasoningbooleanSuppress reasoning events in both the TUI and `codex exec` output.
history.max_bytesnumberIf set, caps the history file size in bytes by dropping oldest entries.
history.persistencesave-all | noneControl whether Codex saves session transcripts to history.jsonl.
include_apply_patch_toolbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
instructionsstringReserved for future use; prefer `model_instructions_file` or `AGENTS.md`.
mcp_oauth_callback_portintegerOptional fixed port for the local HTTP callback server used during MCP OAuth login. When unset, Codex binds to an ephemeral port chosen by the OS.
mcp_oauth_credentials_storeauto | file | keyringPreferred store for MCP OAuth credentials.
mcp_servers.<id>.argsarray<string>Arguments passed to the MCP stdio server command.
mcp_servers.<id>.bearer_token_env_varstringEnvironment variable sourcing the bearer token for an MCP HTTP server.
mcp_servers.<id>.commandstringLauncher command for an MCP stdio server.
mcp_servers.<id>.cwdstringWorking directory for the MCP stdio server process.
mcp_servers.<id>.disabled_toolsarray<string>Deny list applied after `enabled_tools` for the MCP server.
mcp_servers.<id>.enabledbooleanDisable an MCP server without removing its configuration.
mcp_servers.<id>.enabled_toolsarray<string>Allow list of tool names exposed by the MCP server.
mcp_servers.<id>.envmap<string,string>Environment variables forwarded to the MCP stdio server.
mcp_servers.<id>.env_http_headersmap<string,string>HTTP headers populated from environment variables for an MCP HTTP server.
mcp_servers.<id>.env_varsarray<string>Additional environment variables to whitelist for an MCP stdio server.
mcp_servers.<id>.http_headersmap<string,string>Static HTTP headers included with each MCP HTTP request.
mcp_servers.<id>.startup_timeout_msnumberAlias for `startup_timeout_sec` in milliseconds.
mcp_servers.<id>.startup_timeout_secnumberOverride the default 10s startup timeout for an MCP server.
mcp_servers.<id>.tool_timeout_secnumberOverride the default 60s per-tool timeout for an MCP server.
mcp_servers.<id>.urlstringEndpoint for an MCP streamable HTTP server.
modelstringModel to use (e.g., `gpt-5-codex`).
model_auto_compact_token_limitnumberToken threshold that triggers automatic history compaction (unset uses model defaults).
model_context_windownumberContext window tokens available to the active model.
model_instructions_filestring (path)Replacement for built-in instructions instead of `AGENTS.md`.
model_providerstringProvider id from `model_providers` (default: `openai`).
model_providers.<id>.base_urlstringAPI base URL for the model provider.
model_providers.<id>.env_http_headersmap<string,string>HTTP headers populated from environment variables when present.
model_providers.<id>.env_keystringEnvironment variable supplying the provider API key.
model_providers.<id>.env_key_instructionsstringOptional setup guidance for the provider API key.
model_providers.<id>.experimental_bearer_tokenstringDirect bearer token for the provider (discouraged; use `env_key`).
model_providers.<id>.http_headersmap<string,string>Static HTTP headers added to provider requests.
model_providers.<id>.namestringDisplay name for a custom model provider.
model_providers.<id>.query_paramsmap<string,string>Extra query parameters appended to provider requests.
model_providers.<id>.request_max_retriesnumberRetry count for HTTP requests to the provider (default: 4).
model_providers.<id>.requires_openai_authbooleanThe provider uses OpenAI authentication (defaults to false).
model_providers.<id>.stream_idle_timeout_msnumberIdle timeout for SSE streams in milliseconds (default: 300000).
model_providers.<id>.stream_max_retriesnumberRetry count for SSE streaming interruptions (default: 5).
model_providers.<id>.wire_apichat | responsesProtocol used by the provider (defaults to `chat` if omitted).
model_reasoning_effortminimal | low | medium | high | xhighAdjust reasoning effort for supported models (Responses API only; `xhigh` is model-dependent).
model_reasoning_summaryauto | concise | detailed | noneSelect reasoning summary detail or disable summaries entirely.
model_supports_reasoning_summariesbooleanForce Codex to send reasoning metadata even for unknown models.
model_verbositylow | medium | highControl GPT-5 Responses API verbosity (defaults to `medium`).
notice.hide_full_access_warningbooleanTrack acknowledgement of the full access warning prompt.
notice.hide_gpt-5.1-codex-max_migration_promptbooleanTrack acknowledgement of the gpt-5.1-codex-max migration prompt.
notice.hide_gpt5_1_migration_promptbooleanTrack acknowledgement of the GPT-5.1 migration prompt.
notice.hide_rate_limit_model_nudgebooleanTrack opt-out of the rate limit model switch reminder.
notice.hide_world_writable_warningbooleanTrack acknowledgement of the Windows world-writable directories warning.
notice.model_migrationsmap<string,string>Track acknowledged model migrations as old->new mappings.
notifyarray<string>Command invoked for notifications; receives a JSON payload from Codex.
oss_providerlmstudio | ollamaDefault local provider used when running with `--oss` (defaults to prompting if unset).
otel.environmentstringEnvironment tag applied to emitted OpenTelemetry events (default: `dev`).
otel.exporternone | otlp-http | otlp-grpcSelect the OpenTelemetry exporter and provide any endpoint metadata.
otel.exporter.<id>.endpointstringExporter endpoint for OTEL logs.
otel.exporter.<id>.headersmap<string,string>Static headers included with OTEL exporter requests.
otel.exporter.<id>.protocolbinary | jsonProtocol used by the OTLP/HTTP exporter.
otel.exporter.<id>.tls.ca-certificatestringCA certificate path for OTEL exporter TLS.
otel.exporter.<id>.tls.client-certificatestringClient certificate path for OTEL exporter TLS.
otel.exporter.<id>.tls.client-private-keystringClient private key path for OTEL exporter TLS.
otel.log_user_promptbooleanOpt in to exporting raw user prompts with OpenTelemetry logs.
otel.trace_exporternone | otlp-http | otlp-grpcSelect the OpenTelemetry trace exporter and provide any endpoint metadata.
otel.trace_exporter.<id>.endpointstringTrace exporter endpoint for OTEL logs.
otel.trace_exporter.<id>.headersmap<string,string>Static headers included with OTEL trace exporter requests.
otel.trace_exporter.<id>.protocolbinary | jsonProtocol used by the OTLP/HTTP trace exporter.
otel.trace_exporter.<id>.tls.ca-certificatestringCA certificate path for OTEL trace exporter TLS.
otel.trace_exporter.<id>.tls.client-certificatestringClient certificate path for OTEL trace exporter TLS.
otel.trace_exporter.<id>.tls.client-private-keystringClient private key path for OTEL trace exporter TLS.
profilestringDefault profile applied at startup (equivalent to `--profile`).
profiles.<name>.*variousProfile-scoped overrides for any of the supported configuration keys.
profiles.<name>.experimental_use_freeform_apply_patchbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
profiles.<name>.experimental_use_unified_exec_toolbooleanLegacy name for enabling unified exec; prefer `[features].unified_exec`.
profiles.<name>.include_apply_patch_toolbooleanLegacy name for enabling freeform apply_patch; prefer `[features].apply_patch_freeform`.
profiles.<name>.oss_providerlmstudio | ollamaProfile-scoped OSS provider for `--oss` sessions.
project_doc_fallback_filenamesarray<string>Additional filenames to try when `AGENTS.md` is missing.
project_doc_max_bytesnumberMaximum bytes read from `AGENTS.md` when building project instructions.
project_root_markersarray<string>List of project root marker filenames; used when searching parent directories for the project root.
projects.<path>.trust_levelstringMark a project or worktree as trusted or untrusted (`"trusted"` | `"untrusted"`).
review_modelstringOptional model override used by `/review` (defaults to the current session model).
sandbox_moderead-only | workspace-write | danger-full-accessSandbox policy for filesystem and network access during command execution.
sandbox_workspace_write.exclude_slash_tmpbooleanExclude `/tmp` from writable roots in workspace-write mode.
sandbox_workspace_write.exclude_tmpdir_env_varbooleanExclude `$TMPDIR` from writable roots in workspace-write mode.
sandbox_workspace_write.network_accessbooleanAllow outbound network access inside the workspace-write sandbox.
sandbox_workspace_write.writable_rootsarray<string>Additional writable roots when `sandbox_mode = "workspace-write"`.
shell_environment_policy.excludearray<string>Glob patterns for removing environment variables after the defaults.
shell_environment_policy.experimental_use_profilebooleanUse the user shell profile when spawning subprocesses.
shell_environment_policy.ignore_default_excludesbooleanKeep variables containing KEY/SECRET/TOKEN before other filters run.
shell_environment_policy.include_onlyarray<string>Whitelist of patterns; when set only matching variables are kept.
shell_environment_policy.inheritall | core | noneBaseline environment inheritance when spawning subprocesses.
shell_environment_policy.setmap<string,string>Explicit environment overrides injected into every subprocess.
show_raw_agent_reasoningbooleanSurface raw reasoning content when the active model emits it.
skills.configarray<object>Per-skill enablement overrides stored in config.toml.
skills.config.<index>.enabledbooleanEnable or disable the referenced skill.
skills.config.<index>.pathstring (path)Path to a skill folder containing `SKILL.md`.
tool_output_token_limitnumberToken budget for storing individual tool/function outputs in history.
tuitableTUI-specific options such as enabling inline desktop notifications.
tui.alternate_screenauto | always | neverControl alternate screen usage for the TUI (default: auto; auto skips it in Zellij to preserve scrollback).
tui.animationsbooleanEnable terminal animations (welcome screen, shimmer, spinner) (default: true).
tui.notificationsboolean | array<string>Enable TUI notifications; optionally restrict to specific event types.
tui.scroll_events_per_ticknumberWheel event density used to normalize TUI2 scrolling.
tui.scroll_invertbooleanInvert mouse scroll direction in TUI2.
tui.scroll_modeauto | wheel | trackpadScroll interpretation mode for TUI2.
tui.scroll_trackpad_accel_eventsnumberTrackpad events required to gain +1x acceleration.
tui.scroll_trackpad_accel_maxnumberMaximum acceleration multiplier for trackpad scrolling.
tui.scroll_trackpad_linesnumberBaseline trackpad scroll sensitivity for TUI2.
tui.scroll_wheel_like_max_duration_msnumberAuto-mode wheel fallback duration threshold (ms).
tui.scroll_wheel_linesnumberLines per wheel notch for TUI2 scrolling.
tui.scroll_wheel_tick_detect_max_msnumberAuto-mode wheel tick detection threshold (ms).
tui.show_tooltipsbooleanShow onboarding tooltips in the TUI welcome screen (default: true).
windows_wsl_setup_acknowledgedbooleanTrack Windows onboarding acknowledgement (Windows only).
Note: experimental_instructions_file has been renamed to model_instructions_file. The old key is deprecated; update existing configs to the new name.
requirements.toml
requirements.toml is an admin-enforced configuration file that constrains security-sensitive settings users can’t override. For details, locations, and examples, see Admin-enforced requirements.
| Key | Type / Values | Details |
|---|---|---|
allowed_approval_policies | array<string> | Allowed values for `approval_policy`. |
allowed_sandbox_modes | array<string> | Allowed values for `sandbox_mode`. |
mcp_servers | table | Allowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled. |
mcp_servers.<id>.identity | table | Identity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP). |
mcp_servers.<id>.identity.command | string | Allow an MCP stdio server when its `mcp_servers.<id>.command` matches this command. |
mcp_servers.<id>.identity.url | string | Allow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL. |
allowed_approval_policiesarray<string>Allowed values for `approval_policy`.
allowed_sandbox_modesarray<string>Allowed values for `sandbox_mode`.
mcp_serverstableAllowlist of MCP servers that may be enabled. Both the server name (`<id>`) and its identity must match for the MCP server to be enabled. Any configured MCP server not in the allowlist (or with a mismatched identity) is disabled.
mcp_servers.<id>.identitytableIdentity rule for a single MCP server. Set either `command` (stdio) or `url` (streamable HTTP).
mcp_servers.<id>.identity.commandstringAllow an MCP stdio server when its `mcp_servers.<id>.command` matches this command.
mcp_servers.<id>.identity.urlstringAllow an MCP streamable HTTP server when its `mcp_servers.<id>.url` matches this URL.