# `Codex.Config.Defaults`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/config/defaults.ex#L1)

Single source of truth for all Codex SDK default configuration values.

Every tunable constant lives here as a zero-arity function. Consumers call
these functions instead of defining their own module attributes or inline
magic numbers. A handful of values support runtime override via
`Application.get_env/3` — these are noted in the function docs.

## Quick example

    # In config/runtime.exs
    config :codex_sdk,
      rate_limit_default_delay_ms: 120_000,
      attachment_ttl_ms: 3_600_000

    # In your code — always resolved at call time
    Codex.Config.Defaults.rate_limit_default_delay_ms()
    #=> 120_000

See the *Configuration Defaults* guide for the full table of tunables.

# `app_server_init_timeout_ms`

```elixir
@spec app_server_init_timeout_ms() :: pos_integer()
```

App-server initialization/ready timeout (default: 10,000ms).

# `app_server_request_timeout_ms`

```elixir
@spec app_server_request_timeout_ms() :: pos_integer()
```

App-server JSON-RPC request timeout (default: 30,000ms).

# `approval_timeout_ms`

```elixir
@spec approval_timeout_ms() :: pos_integer()
```

Approval callback timeout (default: 30,000ms).

# `attachment_cleanup_interval_ms`

```elixir
@spec attachment_cleanup_interval_ms() :: pos_integer()
```

Interval between attachment cleanup sweeps (default: 60,000ms — 1 minute).

Overridable at runtime:

    config :codex_sdk, attachment_cleanup_interval_ms: 120_000

# `attachment_ttl_ms`

```elixir
@spec attachment_ttl_ms() :: pos_integer()
```

Time-to-live for file attachments (default: 86,400,000ms — 24 hours).

Overridable at runtime:

    config :codex_sdk, attachment_ttl_ms: 3_600_000

# `backoff_base_delay_ms`

```elixir
@spec backoff_base_delay_ms() :: pos_integer()
```

Base delay for exponential backoff (default: 100ms).

# `backoff_max_exponent`

```elixir
@spec backoff_max_exponent() :: pos_integer()
```

Maximum exponent for exponential backoff (default: 20).

# `backoff_max_ms`

```elixir
@spec backoff_max_ms() :: pos_integer()
```

Maximum backoff delay for exponential backoff (default: 5,000ms).

# `client_name`

```elixir
@spec client_name() :: String.t()
```

Client name sent during MCP initialization.

# `client_version`

```elixir
@spec client_version() :: String.t()
```

Client version sent during MCP/app-server initialization.

# `default_api_model`

```elixir
@spec default_api_model() :: String.t()
```

Default model for API auth contexts.

# `default_chatgpt_model`

```elixir
@spec default_chatgpt_model() :: String.t()
```

Default model for ChatGPT auth contexts.

# `default_transport`

```elixir
@spec default_transport() :: :exec | {:app_server, pid()}
```

Default transport for thread options.

`:exec` is the compatibility selector for the default core-backed exec JSONL
lane.

Overridable at runtime:

    config :codex_sdk, default_transport: :exec

# `exec_timeout_ms`

```elixir
@spec exec_timeout_ms() :: pos_integer()
```

Overall exec process timeout in milliseconds (default: 3,600,000 — 1 hour).

# `file_search_max_results`

```elixir
@spec file_search_max_results() :: pos_integer()
```

Default maximum results for file search tool (default: 100).

# `g711_bytes_per_sample`

```elixir
@spec g711_bytes_per_sample() :: pos_integer()
```

G.711 bytes per sample (default: 1).

# `g711_sample_rate`

```elixir
@spec g711_sample_rate() :: pos_integer()
```

G.711 audio sample rate in Hz (default: 8,000).

# `jsonrpc_version`

```elixir
@spec jsonrpc_version() :: String.t()
```

JSON-RPC version.

# `max_agent_turns`

```elixir
@spec max_agent_turns() :: pos_integer()
```

Default maximum agent turns for `RunConfig` (default: 10).

# `mcp_call_timeout_ms`

```elixir
@spec mcp_call_timeout_ms() :: pos_integer()
```

MCP `tools/call` timeout (default: 60,000ms).

# `mcp_default_retries`

```elixir
@spec mcp_default_retries() :: non_neg_integer()
```

Default number of retries for MCP tool calls (default: 3).

# `mcp_init_timeout_ms`

```elixir
@spec mcp_init_timeout_ms() :: pos_integer()
```

MCP `initialize` handshake timeout (default: 10,000ms).

# `mcp_list_timeout_ms`

```elixir
@spec mcp_list_timeout_ms() :: pos_integer()
```

MCP `tools/list` and `resources/list` timeout (default: 30,000ms).

# `mcp_max_tool_name_length`

```elixir
@spec mcp_max_tool_name_length() :: pos_integer()
```

Maximum length for qualified MCP tool names.

# `mcp_notification_timeout_ms`

```elixir
@spec mcp_notification_timeout_ms() :: pos_integer()
```

MCP notification send timeout (default: 10,000ms).

# `mcp_protocol_version`

```elixir
@spec mcp_protocol_version() :: String.t()
```

MCP protocol version string.

# `mcp_server_request_timeout_ms`

```elixir
@spec mcp_server_request_timeout_ms() :: pos_integer()
```

Timeout for app-server MCP server requests like list/reload (default: 30,000ms).

# `mcp_tool_name_delimiter`

```elixir
@spec mcp_tool_name_delimiter() :: String.t()
```

Delimiter for qualified MCP tool names.

# `oauth_browser_callback_port`

```elixir
@spec oauth_browser_callback_port() :: non_neg_integer()
```

Default localhost callback port for browser OAuth login (default: 1455).

Overridable at runtime:

    config :codex_sdk, oauth_browser_callback_port: 1455

# `oauth_browser_callback_timeout_ms`

```elixir
@spec oauth_browser_callback_timeout_ms() :: pos_integer()
```

Overall timeout for browser login callback completion (default: 120,000ms).

# `oauth_device_code_max_poll_interval_ms`

```elixir
@spec oauth_device_code_max_poll_interval_ms() :: pos_integer()
```

Maximum device code polling interval (default: 10,000ms).

# `oauth_device_code_timeout_ms`

```elixir
@spec oauth_device_code_timeout_ms() :: pos_integer()
```

Overall timeout for device code login completion (default: 900,000ms).

# `oauth_http_timeout_ms`

```elixir
@spec oauth_http_timeout_ms() :: pos_integer()
```

HTTP timeout for OAuth token requests (default: 10,000ms).

# `oauth_refresh_skew_ms`

```elixir
@spec oauth_refresh_skew_ms() :: pos_integer()
```

OAuth token refresh skew — refresh this many ms before expiry (default: 30,000ms).

# `oauth_wsl_device_fallback_grace_ms`

```elixir
@spec oauth_wsl_device_fallback_grace_ms() :: pos_integer()
```

WSL grace window before browser flow falls back to device flow (default: 5,000ms).

# `openai_api_base_url`

```elixir
@spec openai_api_base_url() :: String.t()
```

Default OpenAI API base URL.

# `openai_realtime_ws_url`

```elixir
@spec openai_realtime_ws_url() :: String.t()
```

Default OpenAI Realtime WebSocket URL.

# `pcm16_bytes_per_sample`

```elixir
@spec pcm16_bytes_per_sample() :: pos_integer()
```

PCM16 bytes per sample (default: 2).

# `pcm16_sample_rate`

```elixir
@spec pcm16_sample_rate() :: pos_integer()
```

PCM16 audio sample rate in Hz (default: 24,000).

# `preserved_env_keys`

```elixir
@spec preserved_env_keys() :: [String.t()]
```

Environment variable keys preserved when running with a cleared environment.

# `project_root_markers`

```elixir
@spec project_root_markers() :: [String.t()]
```

Markers used to find project root (default: `[".git"]`).

# `rate_limit_default_delay_ms`

```elixir
@spec rate_limit_default_delay_ms() :: pos_integer()
```

Default delay when rate-limited without an explicit Retry-After header.

Overridable at runtime:

    config :codex_sdk, rate_limit_default_delay_ms: 120_000

# `rate_limit_max_delay_ms`

```elixir
@spec rate_limit_max_delay_ms() :: pos_integer()
```

Maximum delay for rate-limit backoff.

Overridable at runtime:

    config :codex_sdk, rate_limit_max_delay_ms: 600_000

# `rate_limit_multiplier`

```elixir
@spec rate_limit_multiplier() :: float()
```

Multiplier for exponential rate-limit backoff.

Overridable at runtime:

    config :codex_sdk, rate_limit_multiplier: 3.0

# `remote_models_cache_ttl_seconds`

```elixir
@spec remote_models_cache_ttl_seconds() :: pos_integer()
```

Cache TTL for remote model list in seconds (default: 300 — 5 min).

# `remote_models_http_timeout_ms`

```elixir
@spec remote_models_http_timeout_ms() :: pos_integer()
```

HTTP timeout for remote model list fetches (default: 10,000ms).

# `retry_base_delay_ms`

```elixir
@spec retry_base_delay_ms() :: pos_integer()
```

Base delay for `Codex.Retry` backoff (default: 200ms).

# `retry_max_attempts`

```elixir
@spec retry_max_attempts() :: pos_integer()
```

Default maximum retry attempts for `Codex.Retry` (default: 4).

# `retry_max_delay_ms`

```elixir
@spec retry_max_delay_ms() :: pos_integer()
```

Maximum delay cap for `Codex.Retry` backoff (default: 10,000ms).

# `sessions_apply_timeout_ms`

```elixir
@spec sessions_apply_timeout_ms() :: pos_integer()
```

Session apply patch timeout (default: 60,000ms).

# `sessions_dir`

```elixir
@spec sessions_dir() :: String.t()
```

Default sessions storage directory under the effective `CODEX_HOME`.

# `shell_max_output_bytes`

```elixir
@spec shell_max_output_bytes() :: pos_integer()
```

Maximum shell command output before truncation (default: 10,000 bytes).

# `shell_timeout_ms`

```elixir
@spec shell_timeout_ms() :: pos_integer()
```

Shell command execution timeout (default: 60,000ms).

# `stream_queue_pop_timeout_ms`

```elixir
@spec stream_queue_pop_timeout_ms() :: pos_integer()
```

Default pop timeout for `StreamQueue` and `RunResultStreaming` (default: 5,000ms).

# `stt_default_turn_detection`

```elixir
@spec stt_default_turn_detection() :: map()
```

Default STT turn detection configuration.

# `stt_model`

```elixir
@spec stt_model() :: String.t()
```

Default STT model name.

# `system_config_path`

```elixir
@spec system_config_path() :: String.t()
```

System-level config file path (default: `/etc/codex/config.toml`).

# `telemetry_default_originator`

```elixir
@spec telemetry_default_originator() :: atom()
```

Default originator tag for telemetry metadata.

# `telemetry_otel_handler_id`

```elixir
@spec telemetry_otel_handler_id() :: String.t()
```

OpenTelemetry handler ID.

# `telemetry_processor_name`

```elixir
@spec telemetry_processor_name() :: atom()
```

Default OpenTelemetry processor name.

# `transport_call_timeout_ms`

```elixir
@spec transport_call_timeout_ms() :: pos_integer()
```

GenServer call timeout for transport operations (default: 5,000ms).

# `transport_close_grace_ms`

```elixir
@spec transport_close_grace_ms() :: pos_integer()
```

Grace period for transport close before escalation (default: 2,000ms).

# `transport_finalize_delay_ms`

```elixir
@spec transport_finalize_delay_ms() :: pos_integer()
```

Delay before finalizing exit to drain remaining output (default: 25ms).

# `transport_force_close_timeout_ms`

```elixir
@spec transport_force_close_timeout_ms() :: pos_integer()
```

Timeout for force-close operations (default: 500ms).

# `transport_headless_timeout_ms`

```elixir
@spec transport_headless_timeout_ms() :: pos_integer()
```

Timeout for headless transport without subscribers (default: 5,000ms).

# `transport_kill_grace_ms`

```elixir
@spec transport_kill_grace_ms() :: pos_integer()
```

Grace period for transport kill before demonitor (default: 250ms).

# `transport_max_buffer_size`

```elixir
@spec transport_max_buffer_size() :: pos_integer()
```

Maximum stdout buffer size in bytes (default: 1,048,576 — 1 MiB).

# `transport_max_lines_per_batch`

```elixir
@spec transport_max_lines_per_batch() :: pos_integer()
```

Maximum stdout lines drained per batch (default: 200).

# `transport_max_stderr_buffer_size`

```elixir
@spec transport_max_stderr_buffer_size() :: pos_integer()
```

Maximum stderr buffer size in bytes (default: 262,144 — 256 KiB).

# `transport_shutdown_grace_ms`

```elixir
@spec transport_shutdown_grace_ms() :: pos_integer()
```

Grace period for transport shutdown before kill (default: 250ms).

# `tts_buffer_size`

```elixir
@spec tts_buffer_size() :: pos_integer()
```

Default TTS audio buffer size in bytes (default: 120).

# `tts_default_instructions`

```elixir
@spec tts_default_instructions() :: String.t()
```

Default TTS instructions for partial-sentence streaming.

# `tts_default_voice`

```elixir
@spec tts_default_voice() :: atom()
```

Default TTS voice.

# `tts_model`

```elixir
@spec tts_model() :: String.t()
```

Default TTS model name.

# `tts_stream_timeout_ms`

```elixir
@spec tts_stream_timeout_ms() :: pos_integer()
```

TTS stream receive timeout (default: 30,000ms).

# `voice_default_sample_rate`

```elixir
@spec voice_default_sample_rate() :: pos_integer()
```

Default voice input sample rate in Hz (default: 24,000).

# `web_search_max_results`

```elixir
@spec web_search_max_results() :: pos_integer()
```

Default maximum results for web search tool (default: 10).

---

*Consult [api-reference.md](api-reference.md) for complete listing*