OpenAI - Codex Docs Changes

app-server.md +168 −16

Details

116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.116- **Start (or resume) a thread**: Call `thread/start` for a new conversation, `thread/resume` to continue an existing one, or `thread/fork` to branch history into a new thread id.

117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.117- **Begin a turn**: Call `turn/start` with the target `threadId` and user input. Optional fields override model, personality, `cwd`, sandbox policy, and more.

118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.118- **Steer an active turn**: Call `turn/steer` to append user input to the currently in-flight turn without creating a new turn.

119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.119- **Stream events**: After `turn/start`, keep reading notifications on stdout: `thread/archived`, `thread/unarchived`, `item/started`, `item/completed`, `item/agentMessage/delta`, tool progress, and other updates.

120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.120- **Finish the turn**: The server emits `turn/completed` with final status when the model finishes or after a `turn/interrupt` cancellation.

121 121

122## Initialization122## Initialization

201- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.201- `thread/start` - create a new thread; emits `thread/started` and automatically subscribes you to turn/item events for that thread.

202- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.202- `thread/resume` - reopen an existing thread by id so later `turn/start` calls append to it.

203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.203- `thread/fork` - fork a thread into a new thread id by copying stored history; emits `thread/started` for the new thread.

204- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history.204- `thread/read` - read a stored thread by id without resuming it; set `includeTurns` to return full turn history. Returned `thread` objects include runtime `status`.

205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters.205- `thread/list` - page through stored thread logs; supports cursor-based pagination plus `modelProviders`, `sourceKinds`, `archived`, and `cwd` filters. Returned `thread` objects include runtime `status`.

206- `thread/loaded/list` - list the thread ids currently loaded in memory.206- `thread/loaded/list` - list the thread ids currently loaded in memory.

207- `thread/archive` - move a thread’s log file into the archived directory; returns `{}` on success.207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.

208- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread`.208- `thread/unarchive` - restore an archived thread rollout back into the active sessions directory; returns the restored `thread` and emits `thread/unarchived`.

209- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.

209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.210- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

210- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.211- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.

211- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."212- `turn/start` - add user input to a thread and begin Codex generation; responds with the initial `turn` and streams events. For `collaborationMode`, `settings.developer_instructions: null` means "use built-in instructions for the selected mode."

223- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.224- `tool/requestUserInput` - prompt the user with 1-3 short questions for a tool call (experimental); questions can set `isOther` for a free-form option.

224- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.225- `config/mcpServer/reload` - reload MCP server configuration from disk and queue a refresh for loaded threads.

225- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).226- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).

226- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id).227- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

228- `feedback/upload` - submit a feedback report (classification + optional reason/logs + conversation id, plus optional `extraLogFiles` attachments).

227- `config/read` - fetch the effective configuration on disk after resolving configuration layering.229- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

228- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.230- `config/value/write` - write a single configuration key/value to the user's `config.toml` on disk.

229- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.231- `config/batchWrite` - apply configuration edits atomically to the user's `config.toml` on disk.

333 "threadId": "thr_123",335 "threadId": "thr_123",

334 "personality": "friendly"336 "personality": "friendly"

335} }337} }

336{ "id": 11, "result": { "thread": { "id": "thr_123" } } }338{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes" } } }

337```339```

338 340

339Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.341Resuming a thread doesn't update `thread.updatedAt` (or the rollout file's modified time) by itself. The timestamp updates when you start a turn.

352{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }354{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

353```355```

354 356

357When a user-facing thread title has been set, app-server hydrates `thread.name` on `thread/list`, `thread/read`, `thread/resume`, `thread/unarchive`, and `thread/rollback` responses. `thread/start` and `thread/fork` may omit `name` (or return `null`) until a title is set later.

358

355### Read a stored thread (without resuming)359### Read a stored thread (without resuming)

356 360

357Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.361Use `thread/read` when you want stored thread data but don't want to resume the thread or subscribe to its events.

358 362

359- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.363- `includeTurns` - when `true`, the response includes the thread's turns; when `false` or omitted, you get the thread summary only.

364- Returned `thread` objects include runtime `status` (`notLoaded`, `idle`, `systemError`, or `active` with `activeFlags`).

360 365

361```json366```json

362{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }367{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }

363{ "id": 19, "result": { "thread": { "id": "thr_123", "turns": [] } } }368{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "status": { "type": "notLoaded" }, "turns": [] } } }

364```369```

365 370

366Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.371Unlike `thread/resume`, `thread/read` doesn't load the thread into memory or emit `thread/started`.

400} }405} }

401{ "id": 20, "result": {406{ "id": 20, "result": {

402 "data": [407 "data": [

403 { "id": "thr_a", "preview": "Create a TUI", "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111 },408 { "id": "thr_a", "preview": "Create a TUI", "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },

404 { "id": "thr_b", "preview": "Fix tests", "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000 }409 { "id": "thr_b", "preview": "Fix tests", "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }

405 ],410 ],

406 "nextCursor": "opaque-token-or-null"411 "nextCursor": "opaque-token-or-null"

407} }412} }

409 414

410When `nextCursor` is `null`, you have reached the final page.415When `nextCursor` is `null`, you have reached the final page.

411 416

417### Track thread status changes

418

419`thread/status/changed` is emitted whenever a loaded thread's runtime status changes. The payload includes `threadId` and the new `status`.

420

421```json

422{

423 "method": "thread/status/changed",

424 "params": {

425 "threadId": "thr_123",

426 "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }

427 }

428}

429```

430

412### List loaded threads431### List loaded threads

413 432

414`thread/loaded/list` returns thread IDs currently loaded in memory.433`thread/loaded/list` returns thread IDs currently loaded in memory.

425```json444```json

426{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }445{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }

427{ "id": 22, "result": {} }446{ "id": 22, "result": {} }

447{ "method": "thread/archived", "params": { "threadId": "thr_b" } }

428```448```

429 449

430Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.450Archived threads won't appear in future calls to `thread/list` unless you pass `archived: true`.

435 455

436```json456```json

437{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }457{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }

438{ "id": 24, "result": { "thread": { "id": "thr_b" } } }458{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }

459{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

439```460```

440 461

441### Trigger thread compaction462### Trigger thread compaction

478}499}

479```500```

480 501

502On macOS, `includePlatformDefaults: true` appends a curated platform-default Seatbelt policy for restricted-read sessions. This improves tool compatibility without broadly allowing all of `/System`.

503

481Examples:504Examples:

482 505

483```json506```json

654- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).677- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).

655- When omitted, `timeoutMs` falls back to the server default.678- When omitted, `timeoutMs` falls back to the server default.

656 679

680### Read admin requirements (`configRequirements/read`)

681

682Use `configRequirements/read` to inspect the effective admin requirements loaded from `requirements.toml` and/or MDM.

683

684```json

685{ "method": "configRequirements/read", "id": 52, "params": {} }

686{ "id": 52, "result": {

687 "requirements": {

688 "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],

689 "allowedSandboxModes": ["readOnly", "workspaceWrite"],

690 "network": {

691 "enabled": true,

692 "allowedDomains": ["api.openai.com"],

693 "allowUnixSockets": ["/tmp/example.sock"],

694 "dangerouslyAllowAllUnixSockets": false

695 }

696 }

697} }

698```

699

700`result.requirements` is `null` when no requirements are configured. When present, the optional `network` object carries managed proxy constraints (domain rules, proxy settings, and unix-socket policy).

701

702### Windows sandbox setup (`windowsSandbox/setupStart`)

703

704Custom Windows clients can trigger sandbox setup asynchronously instead of blocking on startup checks.

705

706```json

707{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }

708{ "id": 53, "result": { "started": true } }

709```

710

711App-server starts setup in the background and later emits a completion notification:

712

713```json

714{

715 "method": "windowsSandbox/setupCompleted",

716 "params": { "mode": "elevated", "success": true, "error": null }

717}

718```

719

720Modes:

721

722- `elevated` - run the elevated Windows sandbox setup path.

723- `unelevated` - run the legacy setup/preflight path.

724

657## Events725## Events

658 726

659Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `turn/*`, and `item/*` notifications.727Event notifications are the server-initiated stream for thread lifecycles, turn lifecycles, and the items within them. After you start or resume a thread, keep reading the active transport stream for `thread/started`, `thread/archived`, `thread/unarchived`, `thread/status/changed`, `turn/*`, and `item/*` notifications.

660 728

661### Notification opt-out729### Notification opt-out

662 730

674- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.742- `fuzzyFileSearch/sessionUpdated` - `{ sessionId, query, files }` with the current matches for the active query.

675- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.743- `fuzzyFileSearch/sessionCompleted` - `{ sessionId }` once indexing and matching for that query completes.

676 744

745### Windows sandbox setup events

746

747- `windowsSandbox/setupCompleted` - `{ mode, success, error }` emitted after a `windowsSandbox/setupStart` request finishes.

748

677### Turn events749### Turn events

678 750

679- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.751- `turn/started` - `{ turn }` with the turn id, empty `items`, and `status: "inProgress"`.

689`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:761`ThreadItem` is the tagged union carried in turn responses and `item/*` notifications. Common item types include:

690 762

691- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).763- `userMessage` - `{id, content}` where `content` is a list of user inputs (`text`, `image`, or `localImage`).

692- `agentMessage` - `{id, text}` containing the accumulated agent reply.764- `agentMessage` - `{id, text, phase?}` containing the accumulated agent reply. When present, `phase` uses Responses API wire values (`commentary`, `final_answer`).

693- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.765- `plan` - `{id, text}` containing proposed plan text in plan mode. Treat the final `plan` item from `item/completed` as authoritative.

694- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.766- `reasoning` - `{id, summary, content}` where `summary` holds streamed reasoning summaries and `content` holds raw reasoning blocks.

695- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.767- `commandExecution` - `{id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}`.

751Order of messages:823Order of messages:

752 824

7531. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.8251. `item/started` shows the pending `commandExecution` item with `command`, `cwd`, and other fields.

7542. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, and optional `proposedExecpolicyAmendment`.8262. `item/commandExecution/requestApproval` includes `itemId`, `threadId`, `turnId`, optional `reason`, optional `command`, optional `cwd`, optional `commandActions`, optional `proposedExecpolicyAmendment`, and optional `networkApprovalContext`.

7553. Client responds with one of the command execution approval decisions above.8273. Client responds with one of the command execution approval decisions above.

7564. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.8284. `item/completed` returns the final `commandExecution` item with `status: completed | failed | declined`.

757 829

830When `networkApprovalContext` is present, the prompt is for managed network access (not a general shell-command approval). The current v2 schema exposes the target `host` and `protocol`; clients should render a network-specific prompt and not rely on `command` being a user-meaningful shell command preview.

831

832Codex deduplicates concurrent network approval prompts by destination (`host`, protocol, and port). The app-server may therefore send one prompt that unblocks multiple queued requests to the same destination, while different ports on the same host are treated separately.

833

758### File change approvals834### File change approvals

759 835

760Order of messages:836Order of messages:

766 842

767### MCP tool-call approvals (apps)843### MCP tool-call approvals (apps)

768 844

769App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.845App (connector) tool calls can also require approval. When an app tool call has side effects, the server may elicit approval with `tool/requestUserInput` and options such as **Accept**, **Decline**, and **Cancel**. Destructive tool annotations always trigger approval even when the tool also advertises less-privileged hints. If the user declines or cancels, the related `mcpToolCall` item completes with an error instead of running the tool.

770 846

771## Skills847## Skills

772 848

863 939

864## Apps (connectors)940## Apps (connectors)

865 941

866Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state.942Use `app/list` to fetch available apps. In the CLI/TUI, `/apps` is the user-facing picker; in custom clients, call `app/list` directly. Each entry includes both `isAccessible` (available to the user) and `isEnabled` (enabled in `config.toml`) so clients can distinguish install/access from local enabled state. App entries can also include optional `branding`, `appMetadata`, and `labels` fields.

867 943

868```json944```json

869{ "method": "app/list", "id": 50, "params": {945{ "method": "app/list", "id": 50, "params": {

879 "name": "Demo App",955 "name": "Demo App",

880 "description": "Example connector for documentation.",956 "description": "Example connector for documentation.",

881 "logoUrl": "https://example.com/demo-app.png",957 "logoUrl": "https://example.com/demo-app.png",

958 "logoUrlDark": null,

959 "distributionChannel": null,

960 "branding": null,

961 "appMetadata": null,

962 "labels": null,

882 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",963 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

883 "isAccessible": true,964 "isAccessible": true,

884 "isEnabled": true965 "isEnabled": true

904 "name": "Demo App",985 "name": "Demo App",

905 "description": "Example connector for documentation.",986 "description": "Example connector for documentation.",

906 "logoUrl": "https://example.com/demo-app.png",987 "logoUrl": "https://example.com/demo-app.png",

988 "logoUrlDark": null,

989 "distributionChannel": null,

990 "branding": null,

991 "appMetadata": null,

992 "labels": null,

907 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",993 "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",

908 "isAccessible": true,994 "isAccessible": true,

909 "isEnabled": true995 "isEnabled": true

936}1022}

937```1023```

938 1024

1025### Config RPC examples for app settings

1026

1027Use `config/read`, `config/value/write`, and `config/batchWrite` to inspect or update app controls in `config.toml`.

1028

1029Read the effective app config shape (including `_default` and per-tool overrides):

1030

1031```json

1032{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }

1033{ "id": 60, "result": {

1034 "config": {

1035 "apps": {

1036 "_default": {

1037 "enabled": true,

1038 "destructive_enabled": true,

1039 "open_world_enabled": true

1040 },

1041 "google_drive": {

1042 "enabled": true,

1043 "destructive_enabled": false,

1044 "default_tools_approval_mode": "prompt",

1045 "tools": {

1046 "files/delete": { "enabled": false, "approval_mode": "approve" }

1047 }

1048 }

1049 }

1050 }

1051} }

1052```

1053

1054Update a single app setting:

1055

1056```json

1057{

1058 "method": "config/value/write",

1059 "id": 61,

1060 "params": {

1061 "keyPath": "apps.google_drive.default_tools_approval_mode",

1062 "value": "prompt",

1063 "mergeStrategy": "replace"

1064 }

1065}

1066```

1067

1068Apply multiple app edits atomically:

1069

1070```json

1071{

1072 "method": "config/batchWrite",

1073 "id": 62,

1074 "params": {

1075 "edits": [

1076 {

1077 "keyPath": "apps._default.destructive_enabled",

1078 "value": false,

1079 "mergeStrategy": "upsert"

1080 },

1081 {

1082 "keyPath": "apps.google_drive.tools.files/delete.approval_mode",

1083 "value": "approve",

1084 "mergeStrategy": "upsert"

1085 }

1086 ]

1087 }

1088}

1089```

1090

939## Auth endpoints1091## Auth endpoints

940 1092

941The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.1093The JSON-RPC auth/account surface exposes request/response methods plus server-initiated notifications (no `id`). Use these to determine auth state, start or cancel logins, logout, and inspect ChatGPT rate limits.

app/automations.md +1 −1

Details

62 62

63If you are in a managed environment, admins can restrict these behaviors using63If you are in a managed environment, admins can restrict these behaviors using

64admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See64admin-enforced requirements. For example, they can disallow `approval_policy = "never"` or constrain allowed sandbox modes. See

~~65[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~65[Admin-enforced requirements (`requirements.toml`)](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

66 66

67Automations use `approval_policy = "never"` when your organization policy67Automations use `approval_policy = "never"` when your organization policy

68allows it. If `approval_policy = "never"` is disallowed by admin requirements,68allows it. If `approval_policy = "never"` is disallowed by admin requirements,

auth.md +11 −0

Details

9 9

10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.10Codex cloud requires signing in with ChatGPT. The Codex CLI and IDE extension support both sign-in methods.

11 11

12Your sign-in method also determines which admin controls and data-handling policies apply.

14- With sign in with ChatGPT, Codex usage follows your ChatGPT workspace permissions, RBAC, and ChatGPT Enterprise retention and residency settings

15- With an API key, usage follows your API organization's retention and data-sharing settings instead

17For the CLI, Sign in with ChatGPT is the default authentication path when no valid session is available.

12### Sign in with ChatGPT19### Sign in with ChatGPT

13 20

14When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.21When you sign in with ChatGPT from the Codex app, CLI, or IDE Extension, Codex opens a browser window for you to complete the login flow. After you sign in, the browser returns an access token to the CLI or IDE extension.

19 26

20OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).27OpenAI bills API key usage through your OpenAI Platform account at standard API rates. See the [API pricing page](https://openai.com/api/pricing/).

21 28

29Recommendation is to use API key authentication for programmatic Codex CLI workflows (for example CI/CD jobs). Do not expose Codex execution in untrusted or publicly triggerable environments.

22## Secure your Codex cloud account31## Secure your Codex cloud account

23 32

24Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).33Codex cloud interacts directly with your codebase, so it needs stronger security than many other ChatGPT features. Enable multi-factor authentication (MFA).

43 52

44Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.53Codex caches login details locally in a plaintext file at `~/.codex/auth.json` or in your OS-specific credential store.

45 54

55For sign in with ChatGPT sessions, Codex refreshes tokens automatically during use before they expire, so active sessions usually continue without requiring another browser login.

46## Credential storage57## Credential storage

47 58

48Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:59Use `cli_auth_credentials_store` to control where the Codex CLI stores cached credentials:

cli/features.md +7 −0

Details

20 20

21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.21- Send prompts, code snippets, or screenshots (see [image inputs](#image-inputs)) directly into the composer.

22- Watch Codex explain its plan before making a change, and approve or reject steps inline.22- Watch Codex explain its plan before making a change, and approve or reject steps inline.

23- Read syntax-highlighted markdown code blocks and diffs in the TUI, then use `/theme` to preview and save a preferred color theme.

23- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.24- Navigate draft history in the composer with <kbd>Up</kbd>/<kbd>Down</kbd>; Codex restores prior draft text and image placeholders.

24- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.25- Press <kbd>Ctrl</kbd>+<kbd>C</kbd> or use `/exit` to close the interactive session when you're done.

25 26

83 84

84Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.85Codex accepts common formats such as PNG and JPEG. Use comma-separated filenames for two or more images, and combine them with text instructions to add context.

85 86

87## Syntax highlighting and themes

89The TUI syntax-highlights fenced markdown code blocks and file diffs so code is easier to scan during reviews and debugging.

91Use `/theme` to open the theme picker, preview themes live, and save your selection to `tui.theme` in `~/.codex/config.toml`. You can also add custom `.tmTheme` files under `$CODEX_HOME/themes` and select them in the picker.

86## Running local code review93## Running local code review

87 94

88Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.95Type `/review` in the CLI to open Codex's review presets. The CLI launches a dedicated reviewer that reads the diff you select and reports prioritized, actionable findings without touching your working tree. By default it uses the current session model; set `review_model` in `config.toml` to override.

config-advanced.md +8 −1

Details

17```toml17```toml

18model = "gpt-5-codex"18model = "gpt-5-codex"

19approval_policy = "on-request"19approval_policy = "on-request"

20model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"

20 21

21[profiles.deep-review]22[profiles.deep-review]

22model = "gpt-5-pro"23model = "gpt-5-pro"

23model_reasoning_effort = "high"24model_reasoning_effort = "high"

24approval_policy = "never"25approval_policy = "never"

26model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

25 27

26[profiles.lightweight]28[profiles.lightweight]

27model = "gpt-4.1"29model = "gpt-4.1"

30 32

31To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.33To make a profile the default, add `profile = "deep-review"` at the top level of `config.toml`. Codex loads that profile unless you override it on the command line.

32 34

35Profiles can also override `model_catalog_json`. When both the top level and the selected profile set `model_catalog_json`, Codex prefers the profile value.

33## One-off overrides from the CLI37## One-off overrides from the CLI

34 38

35In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:39In addition to editing `~/.codex/config.toml`, you can override configuration for a single run from the CLI:

188 192

189For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).193For operational details that are easy to miss while editing `config.toml`, see [Common sandbox and approval combinations](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).

190 194

195You can also use a granular reject policy (`approval_policy = { reject = { ... } }`) to auto-reject only selected prompt categories (sandbox approvals, execpolicy rule prompts, or MCP elicitations) while keeping other prompts interactive.

196

191```197```

192approval_policy = "untrusted" # Other options: on-request, never198approval_policy = "untrusted" # Other options: on-request, never, or { reject = { ... } }

193sandbox_mode = "workspace-write"199sandbox_mode = "workspace-write"

200allow_login_shell = false # Optional hardening: disallow login shells for shell tools

194 201

195[sandbox_workspace_write]202[sandbox_workspace_write]

196exclude_tmpdir_env_var = false # Allow $TMPDIR203exclude_tmpdir_env_var = false # Allow $TMPDIR

config-basic.md +11 −3

Details

35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or35 `requirements.toml` (for example, disallowing `approval_policy = "never"` or

36 `sandbox_mode = "danger-full-access"`). See [Managed36 `sandbox_mode = "danger-full-access"`). See [Managed

37configuration](https://developers.openai.com/codex/security#managed-configuration) and [Admin-enforced37configuration](https://developers.openai.com/codex/security#managed-configuration) and [Admin-enforced

~~38requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~38 requirements](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

39 39

40## Common configuration options40## Common configuration options

41 41

69 69

70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).70For mode-by-mode behavior (including protected `.git`/`.codex` paths and network defaults), see [Sandbox and approvals](https://developers.openai.com/codex/security#sandbox-and-approvals), [Protected paths in writable roots](https://developers.openai.com/codex/security#protected-paths-in-writable-roots), and [Network access](https://developers.openai.com/codex/security#network-access).

71 71

72#### Windows sandbox mode

74When running Codex natively on Windows, set the native sandbox mode to `elevated` in the `windows` table. Use `unelevated` only if you do not have administrator permissions or if elevated setup fails.

76```toml

77[windows]

78sandbox = "elevated" # Recommended

79# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

80```

72#### Web search mode82#### Web search mode

73 83

74Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:84Codex enables web search by default for local tasks and serves results from a web search cache. The cache is an OpenAI-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using `--yolo` or another [full access sandbox setting](https://developers.openai.com/codex/security#common-sandbox-and-approval-combinations), web search defaults to live results. Choose a mode with `web_search`:

config-reference.md +244 −36

Details

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

15| `agents.max_depth` | `number` | Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1). |

16| `approval_policy` | `untrusted | on-request | never` | Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |17| `allow_login_shell` | `boolean` | Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells. |

~~17| `apps.<id>.disabled_reason` | `unknown | user` | Optional reason attached when an app/connector is disabled. |~~18| `approval_policy` | `untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }` | Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs. |

19| `approval_policy.reject.mcp_elicitations` | `boolean` | When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user. |

20| `approval_policy.reject.rules` | `boolean` | When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected. |

21| `approval_policy.reject.sandbox_approval` | `boolean` | When `true`, sandbox escalation approval prompts are auto-rejected. |

22| `apps._default.destructive_enabled` | `boolean` | Default allow/deny for app tools with `destructive_hint = true`. |

23| `apps._default.enabled` | `boolean` | Default app enabled state for all apps unless overridden per app. |

24| `apps._default.open_world_enabled` | `boolean` | Default allow/deny for app tools with `open_world_hint = true`. |

26| `apps.<id>.default_tools_enabled` | `boolean` | Default enabled state for tools in this app unless a per-tool override exists. |

27| `apps.<id>.destructive_enabled` | `boolean` | Allow or block tools in this app that advertise `destructive_hint = true`. |

29| `apps.<id>.open_world_enabled` | `boolean` | Allow or block tools in this app that advertise `open_world_hint = true`. |

31| `apps.<id>.tools.<tool>.enabled` | `boolean` | Per-tool enabled override for an app tool (for example `repos/list`). |

32| `background_terminal_max_timeout` | `number` | Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key. |

30| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |44| `features.apps_mcp_gateway` | `boolean` | Route Apps MCP calls through the OpenAI connectors MCP gateway (`https://api.openai.com/v1/connectors/mcp/`) instead of legacy routing (experimental). |

~~33| `features.elevated_windows_sandbox` | `boolean` | Enable the elevated Windows sandbox pipeline (experimental). |~~

~~34| `features.experimental_windows_sandbox` | `boolean` | Run the Windows restricted-token sandbox (experimental). |~~

72| `mcp_oauth_callback_url` | `string` | Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port. |

92| `model_catalog_json` | `string (path)` | Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile. |

143| `profiles.<name>.model_catalog_json` | `string (path)` | Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile). |

162| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |177| `web_search` | `disabled | cached | live` | Web search mode (default: `"cached"`; cached uses an OpenAI-maintained index and does not fetch live pages; if you use `--yolo` or another full access sandbox setting, it defaults to `"live"`). Use `"live"` to fetch the most recent data from the web, or `"disabled"` to remove the tool. |

164 180

165Key181Key

166 182

188 204

189Key205Key

190 206

207`agents.max_depth`

208

209Type / Values

210

211`number`

212

213Details

214

215Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).

216

217Key

218

191`agents.max_threads`219`agents.max_threads`

192 220

193Type / Values221Type / Values

200 228

201Key229Key

202 230

231`allow_login_shell`

232

233Type / Values

234

235`boolean`

236

237Details

238

239Allow shell-based tools to use login-shell semantics. Defaults to `true`; when `false`, `login = true` requests are rejected and omitted `login` defaults to non-login shells.

240

241Key

242

203`approval_policy`243`approval_policy`

204 244

205Type / Values245Type / Values

206 246

207`untrusted | on-request | never`247`untrusted | on-request | never | { reject = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool } }`

248

249Details

250

251Controls when Codex pauses for approval before executing commands. You can also use `approval_policy = { reject = { ... } }` to auto-reject specific prompt categories while keeping other prompts interactive. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.

252

253Key

254

255`approval_policy.reject.mcp_elicitations`

256

257Type / Values

258

259`boolean`

260

261Details

262

263When `true`, MCP elicitation prompts are auto-rejected instead of shown to the user.

264

265Key

266

267`approval_policy.reject.rules`

268

269Type / Values

270

271`boolean`

272

273Details

274

275When `true`, approvals triggered by execpolicy `prompt` rules are auto-rejected.

276

277Key

278

279`approval_policy.reject.sandbox_approval`

280

281Type / Values

282

283`boolean`

284

285Details

286

287When `true`, sandbox escalation approval prompts are auto-rejected.

288

289Key

290

291`apps._default.destructive_enabled`

292

293Type / Values

294

295`boolean`

296

297Details

298

299Default allow/deny for app tools with `destructive_hint = true`.

300

301Key

302

303`apps._default.enabled`

304

305Type / Values

306

307`boolean`

308

309Details

310

311Default app enabled state for all apps unless overridden per app.

312

313Key

314

315`apps._default.open_world_enabled`

316

317Type / Values

318

319`boolean`

320

321Details

322

323Default allow/deny for app tools with `open_world_hint = true`.

324

325Key

326

327`apps.<id>.default_tools_approval_mode`

328

329Type / Values

330

331`auto | prompt | approve`

332

333Details

334

335Default approval behavior for tools in this app unless a per-tool override exists.

336

337Key

338

339`apps.<id>.default_tools_enabled`

340

341Type / Values

342

343`boolean`

208 344

209Details345Details

210 346

211Controls when Codex pauses for approval before executing commands. `on-failure` is deprecated; use `on-request` for interactive runs or `never` for non-interactive runs.347Default enabled state for tools in this app unless a per-tool override exists.

212 348

213Key349Key

214 350

215`apps.<id>.disabled_reason`351`apps.<id>.destructive_enabled`

216 352

217Type / Values353Type / Values

218 354

219`unknown | user`355`boolean`

220 356

221Details357Details

222 358

223Optional reason attached when an app/connector is disabled.359Allow or block tools in this app that advertise `destructive_hint = true`.

224 360

225Key361Key

226 362

236 372

237Key373Key

238 374

375`apps.<id>.open_world_enabled`

376

377Type / Values

378

379`boolean`

380

381Details

382

383Allow or block tools in this app that advertise `open_world_hint = true`.

384

385Key

386

387`apps.<id>.tools.<tool>.approval_mode`

388

389Type / Values

390

391`auto | prompt | approve`

392

393Details

394

395Per-tool approval behavior override for a single app tool.

396

397Key

398

399`apps.<id>.tools.<tool>.enabled`

400

401Type / Values

402

403`boolean`

404

405Details

406

407Per-tool enabled override for an app tool (for example `repos/list`).

408

409Key

410

411`background_terminal_max_timeout`

412

413Type / Values

414

415`number`

416

417Details

418

419Maximum poll window in milliseconds for empty `write_stdin` polls (background terminal polling). Default: `300000` (5 minutes). Replaces the older `background_terminal_timeout` key.

420

421Key

422

239`chatgpt_base_url`423`chatgpt_base_url`

240 424

241Type / Values425Type / Values

404 588

405Key589Key

406 590

407`features.elevated_windows_sandbox`

~~408~~

409Type / Values

~~410~~

411`boolean`

~~412~~

413Details

~~414~~

415Enable the elevated Windows sandbox pipeline (experimental).

~~416~~

417Key

~~418~~

419`features.experimental_windows_sandbox`

~~420~~

421Type / Values

~~422~~

423`boolean`

~~424~~

425Details

~~426~~

427Run the Windows restricted-token sandbox (experimental).

~~428~~

429Key

~~430~~

431`features.multi_agent`591`features.multi_agent`

432 592

433Type / Values593Type / Values

728 888

729Key889Key

730 890

891`mcp_oauth_callback_url`

892

893Type / Values

894

895`string`

896

897Details

898

899Optional redirect URI override for MCP OAuth login (for example, a devbox ingress URL). `mcp_oauth_callback_port` still controls the callback listener port.

900

901Key

902

731`mcp_oauth_credentials_store`903`mcp_oauth_credentials_store`

732 904

733Type / Values905Type / Values

956 1128

957Key1129Key

958 1130

1131`model_catalog_json`

1132

1133Type / Values

1134

1135`string (path)`

1136

1137Details

1138

1139Optional path to a JSON model catalog loaded on startup. Profile-level `profiles.<name>.model_catalog_json` can override this per profile.

1140

1141Key

1142

959`model_context_window`1143`model_context_window`

960 1144

961Type / Values1145Type / Values

1556 1740

1557Key1741Key

1558 1742

1743`profiles.<name>.model_catalog_json`

1744

1745Type / Values

1746

1747`string (path)`

1748

1749Details

1750

1751Profile-scoped model catalog JSON path override (applied on startup only; overrides the top-level `model_catalog_json` for that profile).

1752

1753Key

1754

1559`profiles.<name>.oss_provider`1755`profiles.<name>.oss_provider`

1560 1756

1561Type / Values1757Type / Values

1974 2170

1975Track Windows onboarding acknowledgement (Windows only).2171Track Windows onboarding acknowledgement (Windows only).

1976 2172

2173Key

2174

2175`windows.sandbox`

2176

2177Type / Values

2178

2179`unelevated | elevated`

2180

2181Details

2182

2183Windows-only native sandbox mode when running Codex natively on Windows.

2184

1977Expand to view all2185Expand to view all

1978 2186

1979You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).2187You can find the latest JSON schema for `config.toml` [here](https://developers.openai.com/codex/config-schema.json).

1988 2196

1989## `requirements.toml`2197## `requirements.toml`

1990 2198

1991`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](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).2199`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](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

1992 2200

1993For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched2201For ChatGPT Business and Enterprise users, Codex can also apply cloud-fetched

1994requirements. See the security page for precedence details.2202requirements. See the security page for precedence details.

1995 2203

1996| Key | Type / Values | Details |2204| Key | Type / Values | Details |

1997| --- | --- | --- |2205| --- | --- | --- |

2000| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |2208| `allowed_web_search_modes` | `array<string>` | Allowed values for `web_search` (`disabled`, `cached`, `live`). `disabled` is always allowed; an empty list effectively allows only `disabled`. |

2001| `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. |2209| `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. |

2020 2228

2021Details2229Details

2022 2230

2023Allowed values for `approval\_policy`.2231Allowed values for `approval_policy` (for example `untrusted`, `on-request`, `never`, and `reject`).

2024 2232

2025Key2233Key

2026 2234

config-sample.md +72 −17

Details

49# model_context_window = 128000 # tokens; default: auto for model49# model_context_window = 128000 # tokens; default: auto for model

50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults50# model_auto_compact_token_limit = 0 # tokens; unset uses model defaults

51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex51# tool_output_token_limit = 10000 # tokens stored per tool output; default: 10000 for gpt-5.2-codex

52# model_catalog_json = "/absolute/path/to/models.json" # optional startup-only model catalog override

53# background_terminal_max_timeout = 300000 # ms; max empty write_stdin poll window (default 5m)

52# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"54# log_dir = "/absolute/path/to/codex-logs" # directory for Codex logs; default: "$CODEX_HOME/log"

53 55

54################################################################################56################################################################################

107# - untrusted: only known-safe read-only commands auto-run; others prompt109# - untrusted: only known-safe read-only commands auto-run; others prompt

108# - on-request: model decides when to ask (default)110# - on-request: model decides when to ask (default)

109# - never: never prompt (risky)111# - never: never prompt (risky)

112# - { reject = { ... } }: auto-reject selected prompt categories

110approval_policy = "on-request"113approval_policy = "on-request"

114# Example granular auto-reject policy:

115# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

116

117# Allow login-shell semantics for shell-based tools when they request `login = true`.

118# Default: true. Set false to force non-login shells and reject explicit login-shell requests.

119allow_login_shell = true

111 120

112# Filesystem/network sandbox policy for tool calls:121# Filesystem/network sandbox policy for tool calls:

113# - read-only (default)122# - read-only (default)

138# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.147# Optional fixed port for MCP OAuth callback: 1-65535. Default: unset.

139# mcp_oauth_callback_port = 4321148# mcp_oauth_callback_port = 4321

140 149

150# Optional redirect URI override for MCP OAuth login (for example, remote devbox ingress).

151# Custom callback paths are supported. `mcp_oauth_callback_port` still controls the listener port.

152# mcp_oauth_callback_url = "https://devbox.example.internal/callback"

153

141################################################################################154################################################################################

142# Project Documentation Controls155# Project Documentation Controls

143################################################################################156################################################################################

194# Active profile name. When unset, no profile is applied.207# Active profile name. When unset, no profile is applied.

195# profile = "default"208# profile = "default"

196 209

210################################################################################

211# Agents (multi-agent roles and limits)

212################################################################################

213

214# [agents]

215# Maximum concurrently open agent threads. Default: 6

216# max_threads = 6

217# Maximum nested spawn depth. Root session starts at depth 0. Default: 1

218# max_depth = 1

219

220# [agents.reviewer]

221# description = "Find security, correctness, and test risks in code."

222# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

223

197################################################################################224################################################################################

198# Skills (per-skill overrides)225# Skills (per-skill overrides)

199################################################################################226################################################################################

276# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).303# Control alternate screen usage (auto skips it in Zellij to preserve scrollback).

277# alternate_screen = "auto"304# alternate_screen = "auto"

278 305

279# Ordered list of footer status-line item IDs. Default: null (disabled).306# Ordered list of footer status-line item IDs. When unset, Codex uses:

307# ["model-with-reasoning", "context-remaining", "current-dir"].

308# Set to [] to hide the footer.

280# status_line = ["model", "context-remaining", "git-branch"]309# status_line = ["model", "context-remaining", "git-branch"]

281 310

311# Syntax-highlighting theme (kebab-case). Use /theme in the TUI to preview and save.

312# You can also add custom .tmTheme files under $CODEX_HOME/themes.

313# theme = "catppuccin-mocha"

314

282# Control whether users can submit feedback from `/feedback`. Default: true315# Control whether users can submit feedback from `/feedback`. Default: true

283[feedback]316[feedback]

284enabled = true317enabled = true

301 334

302[features]335[features]

303# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.336# Leave this table empty to accept defaults. Set explicit booleans to opt in/out.

304shell_tool = true337# shell_tool = true

305# apps = false338# apps = false

306# apps_mcp_gateway = false339# apps_mcp_gateway = false

307# Deprecated legacy toggles; prefer the top-level `web_search` setting.

308# web_search = false

309# web_search_cached = false340# web_search_cached = false

310# web_search_request = false341# web_search_request = false

311unified_exec = false342# unified_exec = false

312shell_snapshot = false343# shell_snapshot = false

313apply_patch_freeform = false344# apply_patch_freeform = false

345# multi_agent = false

314# search_tool = false346# search_tool = false

315# personality = true347# personality = true

316request_rule = true348# request_rule = true

317collaboration_modes = true349# collaboration_modes = true

318use_linux_sandbox_bwrap = false350# use_linux_sandbox_bwrap = false

319experimental_windows_sandbox = false351# remote_models = false

320elevated_windows_sandbox = false352# runtime_metrics = false

321remote_models = false353# powershell_utf8 = true

322runtime_metrics = false354# child_agents_md = false

323powershell_utf8 = true

324child_agents_md = false

325 355

326################################################################################356################################################################################

327# Define MCP servers under this table. Leave empty to disable.357# Define MCP servers under this table. Leave empty to disable.

411# model_verbosity = "medium"441# model_verbosity = "medium"

412# personality = "friendly" # or "pragmatic" or "none"442# personality = "friendly" # or "pragmatic" or "none"

413# chatgpt_base_url = "https://chatgpt.com/backend-api/"443# chatgpt_base_url = "https://chatgpt.com/backend-api/"

444# model_catalog_json = "./models.json"

414# experimental_compact_prompt_file = "./compact_prompt.txt"445# experimental_compact_prompt_file = "./compact_prompt.txt"

415# include_apply_patch_tool = false446# include_apply_patch_tool = false

416# experimental_use_unified_exec_tool = false447# experimental_use_unified_exec_tool = false

424 455

425# Optional per-app controls.456# Optional per-app controls.

426[apps]457[apps]

458# [_default] applies to all apps unless overridden per app.

459# [apps._default]

460# enabled = true

461# destructive_enabled = true

462# open_world_enabled = true

463#

427# [apps.google_drive]464# [apps.google_drive]

428# enabled = false465# enabled = false

429# disabled_reason = "user" # or "unknown"466# destructive_enabled = false # block destructive-hint tools for this app

467# default_tools_enabled = true

468# default_tools_approval_mode = "prompt" # auto | prompt | approve

469#

470# [apps.google_drive.tools."files/delete"]

471# enabled = false

472# approval_mode = "approve"

430 473

431################################################################################474################################################################################

432# Projects (trust levels)475# Projects (trust levels)

477# client-certificate = "/etc/codex/certs/client.pem"520# client-certificate = "/etc/codex/certs/client.pem"

478# client-private-key = "/etc/codex/certs/client-key.pem"521# client-private-key = "/etc/codex/certs/client-key.pem"

479```522```

523

524################################################################################

525

526# Windows

527

528################################################################################

529

530[windows]

531

532# Native Windows sandbox mode (Windows only): unelevated | elevated

533

534sandbox = "unelevated"

enterprise/admin-setup.md +145 −85

Details

2 2

3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.3This guide is for ChatGPT Enterprise admins who want to set up Codex for their workspace.

4 4

5Use this page as the step-by-step rollout guide. It focuses on setup order and decision points. For detailed policy, configuration, and monitoring details, use the linked pages: [Authentication](https://developers.openai.com/codex/auth), [Security](https://developers.openai.com/codex/security), [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration), and [Governance](https://developers.openai.com/codex/enterprise/governance).

5## Enterprise-grade security and privacy7## Enterprise-grade security and privacy

6 8

7Codex supports ChatGPT Enterprise security features, including:9Codex supports ChatGPT Enterprise security features, including:

8 10

9- No training on enterprise data11- No training on enterprise data

~~10- Zero data retention for the CLI and IDE~~12- Zero data retention for the App, CLI, and IDE (code remains in developer environment)

~~11- Residency and retention follow ChatGPT Enterprise policies~~13- Residency and retention that follow ChatGPT Enterprise policies

12- Granular user access controls14- Granular user access controls

~~13- Data encryption at rest (AES 256) and in transit (TLS 1.2+)~~15- Data encryption at rest (AES-256) and in transit (TLS 1.2+)

14 16

~~15For more, see [Security](https://developers.openai.com/codex/security).~~17For security controls and runtime protections, see [Security](https://developers.openai.com/codex/security). Refer to [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) for more details.

16 18

17## Local vs. cloud setup19## Local vs. cloud setup

18 20

19Codex operates in two environments: local and cloud.21Codex operates in two environments: local and cloud.

20 22

~~211. Local use includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.~~231. **Codex local** includes the Codex app, CLI, and IDE extension. The agent runs on the developer’s computer in a sandbox.

222. Use in the cloud includes Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack). The agent runs remotely in a hosted container with your codebase.242. **Codex cloud** includes hosted Codex features (including Codex cloud, iOS, Code Review, and tasks created by the [Slack integration](https://developers.openai.com/codex/integrations/slack) or [Linear integration](https://developers.openai.com/codex/integrations/linear)). The agent runs remotely in a hosted container with your codebase.

23 25

~~24Use separate permissions and role-based access control (RBAC) to control access to local and cloud features. You can enable local, cloud, or both for all users or for specific groups.~~26You can enable local, cloud, or both, and control access with workspace settings and role-based access control (RBAC).

25 27

~~26## Codex local setup~~28## Step 0: Owners and rollout decision

27 29

~~28### Enable Codex app, CLI, and IDE extension in workspace settings~~30Ensure you have the following owners:

29 31

30To enable Codex locally for workspace members, go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings). Turn on **Allow members to use Codex Local**. This setting doesn’t require the GitHub connector.32- Workspace owner with access to ChatGPT Enterprise

33- IT management owner for managed configuration

34- Governance owner for analytics / compliance review

31 35

32After you turn this on, users can sign in to use the Codex app, CLI, and IDE extension with their ChatGPT account. If you turn off this setting, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”36A rollout decision:

33 37

~~34## Team Config~~38- Codex local only (Codex app, CLI, and IDE extension)

39- Codex cloud only (Codex web, GitHub code review)

40- Both local + cloud

35 41

~~36Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.~~42Review [authentication](https://developers.openai.com/codex/auth) before rollout:

37 43

~~38| Type | Path | Use it to |~~44- Codex local supports ChatGPT sign-in or API keys. Confirm MFA/SSO requirements and any managed login restrictions in authentication

~~39| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |~~45- Codex cloud requires ChatGPT sign-in

~~40| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |~~

~~41| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |~~

~~42| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |~~

43 46

~~44For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).~~47## Step 1: Enable workspace toggles

49Turn on only the Codex features you plan to roll out in this phase.

51Go to [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

53### Codex local

55Turn on **Allow members to use Codex Local**.

57This enables use of the Codex app, CLI, and IDE extension for allowed users.

45 58

~~46## Codex cloud setup~~59If this toggle is off, users who attempt to use the Codex app, CLI, or IDE will see the following error: “403 - Unauthorized. Contact your ChatGPT administrator for access.”

61#### Enable device code authentication for Codex CLI

63Allow developers to sign in with device codes when using Codex CLI in a non-interactive environment. More details in [authentication](https://developers.openai.com/codex/auth/).

65![Codex local toggle](/images/codex/enterprise/local-toggle-config.png)

67### Codex cloud

47 68

48### Prerequisites69### Prerequisites

49 70

57 78

58Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).79Start by turning on the ChatGPT GitHub Connector in the Codex section of [Workspace Settings > Settings and Permissions](https://chatgpt.com/admin/settings).

59 80

~~60To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**.~~81To enable Codex cloud for your workspace, turn on **Allow members to use Codex cloud**. Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.

83Note that it may take up to 10 minutes for Codex to appear in ChatGPT.

85#### Allow members to administer Codex

87Allows users to view overall Codex [workspace analytics](https://chatgpt.com/codex/settings/analytics), access [cloud-managed requirements](https://chatgpt.com/codex/settings/managed-configs), and manage Cloud environments (edit and delete).

89Codex cloud not required.

91#### Enable Codex Slack app to post answers on task completion

93Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.

95To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).

97#### Enable Codex agent to access the internet

99By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.

100

101This setting enables users to use an allowlist for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.

61 102

~~62Once enabled, users can access Codex directly from the left-hand navigation panel in ChatGPT.~~103For security implications of internet access and runtime controls, see [Security](https://developers.openai.com/codex/security).

63 104

64![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)105![Codex cloud toggle](/images/codex/enterprise/cloud-toggle-config.png)

65 106

~~66After you turn on Codex in your Enterprise workspace settings, it may take up~~107## Step 2: Set up custom roles (RBAC)

~~67to 10 minutes for Codex to appear in ChatGPT.~~

68 108

~~69### Configure the GitHub Connector IP allow list~~109Use RBAC to control which users or groups can access Codex local and Codex cloud.

70 110

~~71To control which IP addresses can connect to your ChatGPT GitHub connector, configure these IP ranges:~~111### What RBAC lets you do

72 112

~~73- [ChatGPT egress IP ranges](https://openai.com/chatgpt-actions.json)~~113Workspace Owners can use RBAC in ChatGPT admin settings to:

~~74- [Codex container egress IP ranges](https://openai.com/chatgpt-agents.json)~~

75 114

~~76These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.~~115- Set a default role for users who are not assigned any custom role

116- Create custom roles with granular permissions

117- Assign one or more custom roles to Groups (including SCIM-synced groups)

118- Manage roles centrally from the Custom Roles tab

77 119

~~78### Allow members to administer Codex~~120Users can inherit multiple roles, and permissions resolve to the maximum allowed across those roles.

79 121

~~80This toggle allows users to view Codex workspace analytics and manage environments (edit and delete).~~122### Important behavior to plan for

81 123

~~82Codex supports role-based access (see [Role-based access (RBAC)](#role-based-access-rbac)), so you can turn on this toggle for a specific subset of users.~~124Users in any custom role group do not use the workspace default permissions.

83 125

~~84### Enable Codex Slack app to post answers on task completion~~126If you are gradually rolling out Codex, one suggestion is to have a “Codex Users” group and a second “Codex Admin” group that has the “Allow members to administer Codex” toggle enabled.

85 127

~~86Codex integrates with Slack. When a user mentions `@Codex` in Slack, Codex starts a cloud task, gets context from the Slack thread, and responds with a link to a PR to review in the thread.~~128For RBAC setup details and the full permission model, see the [OpenAI RBAC Help Center article](https://help.openai.com/en/articles/11750701-rbac).

87 129

88To allow the Slack app to post answers on task completion, turn on **Allow Codex Slack app to post answers on task completion**. When enabled, Codex posts its full answer back to Slack when the task completes. Otherwise, Codex posts only a link to the task.130## Step 3: Configure Codex local managed settings

89 131

~~90To learn more, see [Codex in Slack](https://developers.openai.com/codex/integrations/slack).~~132For Codex local, set an admin-approved baseline for local behavior before broader rollout.

91 133

~~92### Enable Codex agent to access the internet~~134### Use managed configuration for two different goals

93 135

~~94By default, Codex cloud agents have no internet access during runtime to help protect against security and safety risks like prompt injection.~~136- **Requirements** (`requirements.toml`): Admin-enforced constraints users cannot override

137- **Managed defaults** (`managed_config.toml`): Starting values applied when Codex launches

95 138

~~96As an admin, you can allow users to enable agent internet access in their environments. To enable it, turn on **Allow Codex agent to access the internet**.~~139### Team Config

97 140

~~98When this setting is on, users can use an allow list for common software dependency domains, add more domains and trusted sites, and specify allowed HTTP methods.~~141Teams who want to standardize Codex across an organization can use Team Config to share defaults, rules, and skills without duplicating setup on every local configuration.

99 142

100### Enable code review with Codex cloud143| Type | Path | Use it to |

144| ------------------------------------ | ------------- | ---------------------------------------------------------------------------- |

145| [Config basics](https://developers.openai.com/codex/config-basic) | `config.toml` | Set defaults for sandbox mode, approvals, model, reasoning effort, and more. |

146| [Rules](https://developers.openai.com/codex/rules) | `rules/` | Control which commands Codex can run outside the sandbox. |

147| [Skills](https://developers.openai.com/codex/skills) | `skills/` | Make shared skills available to your team. |

148

149For locations and precedence, see [Config basics](https://developers.openai.com/codex/config-basic#configuration-precedence).

150

151### Recommended first decisions for local rollout

152

153Define a baseline for your pilot:

154

155- Approval policy posture

156- Sandbox mode posture

157- Web search posture

158- MCP / connectors policy

159- Local logging and telemetry posture

101 160

102To allow Codex to do code reviews, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).161For exact keys, precedence, MDM deployment, and examples, see [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration) and [Security](https://developers.openai.com/codex/security).

103 162

104Users can specify whether they want Codex to review their pull requests. Users can also configure whether code review runs for all contributors to a repository.163If you plan to restrict login method or workspace for local clients, see the admin-managed authentication restrictions in [Authentication](https://developers.openai.com/codex/auth).

105 164

106Codex supports two types of code reviews:165## Step 4: Configure Codex cloud usage (if enabled)

107 166

1081. Automatically triggered code reviews when a user opens a PR for review.167This step covers repository and environment setup after the Codex cloud workspace toggle is enabled.

1092. Reactive code reviews when a user mentions @Codex to look at issues. For example, “@Codex fix this CI error” or “@Codex address that feedback.”

110 168

111## Role-based access (RBAC)169### Connect Codex cloud to repositories

112 170

113Codex supports role-based access. RBAC is a security and permissions model used to control access to systems or resources based on a user’s role assignments.1711. Navigate to [Codex](https://chatgpt.com/codex) and select **Get started**

1722. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven't already connected GitHub to ChatGPT

1733. Install or authorize the ChatGPT GitHub Connector

1744. Choose an installation target for the ChatGPT Connector (typically your main organization)

1755. Allow the repositories you want to connect to Codex

114 176

115To enable RBAC for Codex, navigate to Settings & Permissions → Custom Roles in [ChatGPT’s admin page](https://chatgpt.com/admin/settings) and assign roles to groups created in the Groups tab.177For more, see [Cloud environments](https://developers.openai.com/codex/cloud/environments).

116 178

117This simplifies permission management for Codex and improves security in your ChatGPT workspace. To learn more, see the [Help Center article](https://help.openai.com/en/articles/11750701-rbac).179Codex uses short-lived, least-privilege GitHub App installation tokens for each operation and respects the user's existing GitHub repository permissions and branch protection rules.

180

181### Configure IP addresses (as needed)

182

183Configure connector / IP allow lists if required by your network policy with these [egress IP ranges](https://openai.com/chatgpt-agents.json).

184

185These IP ranges can change. Consider checking them automatically and updating your allow list based on the latest values.

186

187### Enable code review with Codex cloud

118 188

119## Set up your first Codex cloud environment189To allow Codex to perform code reviews on GitHub, go to [Settings → Code review](https://chatgpt.com/codex/settings/code-review).

120 190

1211. Go to Codex cloud and select **Get started**.191Code review can be configured at the repository level. Users can also enable auto review for their PRs and choose when Codex automatically triggers a review. More details on [GitHub](https://developers.openai.com/codex/integrations/github) integration page.

1222. Select **Connect to GitHub** to install the ChatGPT GitHub Connector if you haven’t already connected GitHub to ChatGPT.

123 - Allow the ChatGPT Connector for your account.

124 - Choose an installation target for the ChatGPT Connector (typically your main organization).

125 - Allow the repositories you want to connect to Codex (a GitHub admin may need to approve this).

1263. Create your first environment by selecting the repository most relevant to your developers, then select **Create environment**.

127 - Add the email addresses of any environment collaborators to give them edit access.

1284. Start a few starter tasks (for example, writing tests, fixing bugs, or exploring code).

129 192

130You have now created your first environment. Users who connect to GitHub can create tasks using this environment. Users who have access to the repository can also push pull requests generated from their tasks.193Additional integration docs for [Slack](https://developers.openai.com/codex/integrations/slack), [GitHub](https://developers.openai.com/codex/integrations/github), and [Linear](https://developers.openai.com/codex/integrations/linear).

131 194

132### Environment management195## Step 5: Set up governance and observability

133 196

134As a ChatGPT workspace administrator, you can edit and delete Codex environments in your workspace.197Codex gives enterprise teams several options for visibility into adoption and impact. Set up governance early so your team can monitor adoption, investigate issues, and support compliance workflows.

135 198

136### Connect more GitHub repositories with Codex cloud199### Codex governance typically uses

137 200

1381. Select **Environments**, or open the environment selector and select **Manage Environments**.201- Analytics Dashboard for quick, self-serve visibility

1392. Select **Create Environment**.202- Analytics API for programmatic reporting and BI integration

1403. Select the repository you want to connect.203- Compliance API for audit and investigation workflows

1414. Enter a name and description.

1425. Select the environment visibility.

1436. Select **Create Environment**.

144 204

145Codex automatically optimizes your environment setup by reviewing your codebase. Avoid advanced environment configuration until you observe specific performance issues. For more, see [Codex cloud](https://developers.openai.com/codex/cloud).205### Recommended minimum setup

146 206

147### Share setup instructions with users207- Assign an owner for adoption reporting

208- Assign an owner for audit and compliance review

209- Define a review cadence

210- Decide what success looks like

148 211

149You can share these steps with end users:212For details and examples, see [Governance](https://developers.openai.com/codex/enterprise/governance).

150 213

1511. Go to [Codex](https://chatgpt.com/codex) in the left-hand panel of ChatGPT.214## Step 6: Confirm and validate setup

1522. Select **Connect to GitHub** in the prompt composer if you’re not already connected.

153 - Sign in to GitHub.

1543. You can now use shared environments with your workspace or create your own environment.

1554. Try a task in both Ask and Code mode. For example:

156 - Ask: Find bugs in this codebase.

157 - Write code: Improve test coverage following the existing test patterns.

158 215

159## Track Codex usage216### What to verify

160 217

161- For workspaces with rate limits, use [Settings → Usage](https://chatgpt.com/codex/settings/usage) to view workspace metrics for Codex.218- Users can sign in to Codex local (ChatGPT or API key)

162- For more detail on enterprise governance, refer to the [Governance](https://developers.openai.com/codex/enterprise/governance) page.219- (If enabled) Users can sign in to Codex cloud (ChatGPT sign-in required)

163- For enterprise workspaces with flexible pricing, you can see credit usage in the ChatGPT workspace billing console.220- MFA and SSO requirements match your enterprise security policy

221- RBAC and workspace toggles produce the expected access behavior

222- Managed configuration is applied for users

223- Governance data is visible for admins

164 224

165## Zero data retention (ZDR)225For authentication options and enterprise login restrictions, see [Authentication](https://developers.openai.com/codex/auth).

166 226

167Codex supports OpenAI organizations with [Zero Data Retention (ZDR)](https://platform.openai.com/docs/guides/your-data#zero-data-retention) enabled.227Once your team is confident with setup, you can confidently roll Codex out to additional teams and organizations.

enterprise/governance.md +2 −0

Details

88 88

89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.89The Compliance API gives enterprises a way to export logs and metadata for Codex activity so you can connect that data to your existing audit, monitoring, and security workflows. It is designed for use with tools like eDiscovery, DLP, SIEM, or other compliance systems.

90 90

91For Codex usage authenticated through ChatGPT, Compliance API exports provide audit records for Codex activity and can be used in investigations and compliance workflows. These audit logs are retained for up to 30 days. API-key-authenticated Codex usage follows your API organization settings and is not included in Compliance API exports.

91### What you can export93### What you can export

92 94

93#### Activity logs95#### Activity logs

enterprise/managed-configuration.md +180 −0 added

Details

1# Managed configuration

3Enterprise admins can control local Codex behavior in two ways:

5- **Requirements**: admin-enforced constraints that users can't override.

6- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

8## Admin-enforced requirements (requirements.toml)

10Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers can be enabled). When resolving configuration (for example from `config.toml`, profiles, or CLI config overrides), if a value conflicts with an enforced requirement, Codex falls back to a requirements-compatible value and notifies the user. If an `mcp_servers` allowlist is configured, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex disables it.

12For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml).

14### Locations and precedence

16Requirements layers are applied in this order (earlier wins per field):

181. Cloud-managed requirements (ChatGPT Business or Enterprise)

192. macOS managed preferences (MDM) via `com.openai.codex:requirements_toml_base64`

203. System `requirements.toml` (`/etc/codex/requirements.toml` on Unix systems, including Linux/macOS)

22Across layers, requirements are merged per field: if an earlier layer sets a field (including an empty list), later layers do not override that field, but lower layers can still fill fields that remain unset.

24For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

26### Cloud-managed requirements

28When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also fetch admin-enforced requirements from the Codex service. This is another source of `requirements.toml`-compatible requirements. This applies across Codex surfaces, including the CLI, App, and IDE Extension.

30#### Configure cloud-managed requirements

32Go to the [Codex managed-config page](https://chatgpt.com/codex/settings/managed-configs).

34Create a new managed requirements file using the same format and keys as `requirements.toml`.

36```toml

37enforce_residency = "us"

38allowed_approval_policies = ["on-request"]

39allowed_sandbox_modes = ["read-only", "workspace-write"]

41[rules]

42prefix_rules = [

43 { pattern = [{ any_of = ["bash", "sh", "zsh"] }], decision = "prompt", justification = "Require explicit approval for shell entrypoints" },

44]

45```

47Save the configuration. Once saved, the updated managed requirements apply immediately for matching users.

48For more examples, see [Example requirements.toml](#example-requirementstoml).

50#### Assign requirements to groups

52Admins can configure different managed requirements for different user groups, and also set a default fallback requirements policy.

54If a user matches multiple group-specific rules, the first matching rule applies. Codex does not fill unset requirement fields from later matching group rules.

56For example, if the first matching group rule sets only `allowed_sandbox_modes = ["read-only"]` and a later matching group rule sets `allowed_approval_policies = ["on-request"]`, Codex applies only the first matching group rule and does not fill `allowed_approval_policies` from the later rule.

58#### How Codex applies cloud-managed requirements locally

60When a user starts Codex and signs in with ChatGPT on a Business or Enterprise plan, Codex applies managed requirements on a best-effort basis. Codex first checks for a valid, unexpired local managed requirements cache entry and uses it if available. If the cache is missing, expired, invalid, or does not match the current auth identity, Codex attempts to fetch managed requirements from the service (with retries) and writes a new signed cache entry on success. If no valid cached entry is available and the fetch fails or times out, Codex continues without the managed requirements layer.

62After cache resolution, managed requirements are enforced as part of the normal requirements layering described above.

64### Example requirements.toml

66This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

68```toml

69allowed_approval_policies = ["untrusted", "on-request"]

70allowed_sandbox_modes = ["read-only", "workspace-write"]

71```

73You can also constrain web search mode:

75```toml

76allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

77```

79`allowed_web_search_modes = []` effectively allows only `"disabled"`.

80For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

82### Enforce command rules from requirements

84Admins can also enforce restrictive command rules from `requirements.toml`

85using a `[rules]` table. These rules merge with regular `.rules` files, and the

86most restrictive decision still wins.

88Unlike `.rules`, requirements rules must specify `decision`, and that decision

89must be `"prompt"` or `"forbidden"` (not `"allow"`).

91```toml

92[rules]

93prefix_rules = [

94 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

95 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

96]

97```

99To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

100

101```toml

102[mcp_servers.docs]

103identity = { command = "codex-mcp" }

104

105[mcp_servers.remote]

106identity = { url = "https://example.com/mcp" }

107```

108

109If `mcp_servers` is present but empty, Codex disables all MCP servers.

110

111## Managed defaults (`managed_config.toml`)

112

113Managed defaults merge on top of a user's local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

114

115Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

116

117### Precedence and layering

118

119Codex assembles the effective configuration in this order (top overrides bottom):

120

121- Managed preferences (macOS MDM; highest precedence)

122- `managed_config.toml` (system/managed file)

123- `config.toml` (user's base configuration)

124

125CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

126

127Cloud-managed requirements affect the requirements layer (not managed defaults). See the Admin-enforced requirements section above for precedence.

128

129### Locations

130

131- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

132- Windows/non-Unix: `~/.codex/managed_config.toml`

133

134If the file is missing, Codex skips the managed layer.

135

136### macOS managed preferences (MDM)

137

138On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

139

140- Preference domain: `com.openai.codex`

141- Keys:

142 - `config_toml_base64` (managed defaults)

143 - `requirements_toml_base64` (requirements)

144

145Codex parses these “managed preferences” payloads as TOML. For managed defaults (`config_toml_base64`), managed preferences have the highest precedence. For requirements (`requirements_toml_base64`), precedence follows the cloud-managed requirements order described above.

146

147### MDM setup workflow

148

149Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

150

1511. Build the managed payload TOML and encode it with `base64` (no wrapping).

1522. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

1533. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

1544. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

155

156Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

157

158### Example managed_config.toml

159

160```toml

161# Set conservative defaults

162approval_policy = "on-request"

163sandbox_mode = "workspace-write"

164

165[sandbox_workspace_write]

166network_access = false # keep network disabled unless explicitly allowed

167

168[otel]

169environment = "prod"

170exporter = "otlp-http" # point at your collector

171log_user_prompt = false # keep prompts redacted

172# exporter details live under exporter tables; see Monitoring and telemetry above

173```

174

175### Recommended guardrails

176

177- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

178- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

179- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

180- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

mcp.md +9 −1

Details

75- `enabled_tools` (optional): Tool allow list.75- `enabled_tools` (optional): Tool allow list.

76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).76- `disabled_tools` (optional): Tool deny list (applied after `enabled_tools`).

77 77

~~78If your OAuth provider requires a static callback URI, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.~~78If your OAuth provider requires a fixed callback port, set the top-level `mcp_oauth_callback_port` in `config.toml`. If unset, Codex binds to an ephemeral port.

80If your MCP OAuth flow must use a specific callback URL (for example, a remote devbox ingress URL or a custom callback path), set `mcp_oauth_callback_url`. Codex uses this value as the OAuth `redirect_uri` while still using `mcp_oauth_callback_port` for the callback listener port. Local callback URLs (for example `localhost`) bind on loopback; non-local callback URLs bind on `0.0.0.0` so the callback can reach the host.

79 81

80#### config.toml examples82#### config.toml examples

81 83

88MY_ENV_VAR = "MY_ENV_VALUE"90MY_ENV_VAR = "MY_ENV_VALUE"

89```91```

90 92

93```toml

94# Optional MCP OAuth callback overrides (used by `codex mcp login`)

95mcp_oauth_callback_port = 5555

96mcp_oauth_callback_url = "https://devbox.example.internal/callback"

97```

91```toml99```toml

92[mcp_servers.figma]100[mcp_servers.figma]

93url = "https://mcp.figma.com/mcp"101url = "https://mcp.figma.com/mcp"

multi-agent.md +140 −14

Details

31 31

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 33

34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.

34To see it in action, try the following prompt on your project:36To see it in action, try the following prompt on your project:

35 37

36```38```

47 49

48- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.50- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.

49- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.

52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).

50 53

51## Approvals and sandbox controls54## Approvals and sandbox controls

52 55

68 71

69Codex ships with built-in roles:72Codex ships with built-in roles:

70 73

~~71- `default`~~74- `default`: general-purpose fallback role.

~~72- `worker`~~75- `worker`: execution-focused role for implementation and fixes.

~~73- `explorer`~~76- `explorer`: read-heavy codebase exploration role.

77- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).

74 78

75Each agent role can override your default configuration. Common settings to override for an agent role are:79Each agent role can override your default configuration. Common settings to override for an agent role are:

76 80

84| --- | --- | --- | --- |88| --- | --- | --- | --- |

85| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |

86| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |

87| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |92| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |

88| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |93| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

90**Notes:**95**Notes:**

91 96

92- Unknown fields in `[agents.<name>]` are rejected.97- Unknown fields in `[agents.<name>]` are rejected.

98- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

93- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.

100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.

94- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.101- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

95- If Codex can’t load a role config file, agent spawns can fail until you fix the file.102- If Codex can’t load a role config file, agent spawns can fail until you fix the file.

96- Any configuration not set by the agent role will be inherited from the parent session.103- Any configuration not set by the agent role will be inherited from the parent session.

97 104

98### Example agent roles105### Example agent roles

99 106

100Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.107The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.

108

109#### Example 1: PR review team

110

111This pattern splits review into three focused roles:

112

113- `explorer` maps the codebase and gathers evidence.

114- `reviewer` looks for correctness, security, and test risks.

115- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

101 116

102Example `~/.codex/config.toml`:117Project config (`.codex/config.toml`):

103 118

104```119```

105[agents.default]120[agents]

106description = "General-purpose helper."121max_threads = 6

122max_depth = 1

123

124[agents.explorer]

125description = "Read-only codebase explorer for gathering evidence before changes are proposed."

126config_file = "agents/explorer.toml"

107 127

108[agents.reviewer]128[agents.reviewer]

109description = "Find security, correctness, and test risks in code."129description = "PR reviewer focused on correctness, security, and missing tests."

110config_file = "agents/reviewer.toml"130config_file = "agents/reviewer.toml"

111 131

112[agents.explorer]132[agents.docs_researcher]

113description = "Fast codebase explorer for read-heavy tasks."133description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

114config_file = "agents/custom-explorer.toml"134config_file = "agents/docs-researcher.toml"

135```

136

137`agents/explorer.toml`:

138

139```

140model = "gpt-5.3-codex-spark"

141model_reasoning_effort = "medium"

142sandbox_mode = "read-only"

143developer_instructions = """

144Stay in exploration mode.

145Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

146Prefer fast search and targeted file reads over broad scans.

147"""

115```148```

116 149

117Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):150`agents/reviewer.toml`:

118 151

119```152```

120model = "gpt-5.3-codex"153model = "gpt-5.3-codex"

121model_reasoning_effort = "high"154model_reasoning_effort = "high"

122developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."155sandbox_mode = "read-only"

156developer_instructions = """

157Review code like an owner.

158Prioritize correctness, security, behavior regressions, and missing test coverage.

159Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

160"""

161```

162

163`agents/docs-researcher.toml`:

164

165```

166model = "gpt-5.3-codex-spark"

167model_reasoning_effort = "medium"

168sandbox_mode = "read-only"

169developer_instructions = """

170Use the docs MCP server to confirm APIs, options, and version-specific behavior.

171Return concise answers with links or exact references when available.

172Do not make code changes.

173"""

174

175[mcp_servers.openaiDeveloperDocs]

176url = "https://developers.openai.com/mcp"

177```

178

179This setup works well for prompts like:

180

181```

182Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

123```183```

124 184

125Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):185#### Example 2: frontend integration debugging team

186

187This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

188

189Project config (`.codex/config.toml`):

190

191```

192[agents]

193max_threads = 6

194max_depth = 1

195

196[agents.explorer]

197description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

198config_file = "agents/explorer.toml"

199

200[agents.browser_debugger]

201description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

202config_file = "agents/browser-debugger.toml"

203

204[agents.worker]

205description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

206config_file = "agents/worker.toml"

207```

208

209`agents/explorer.toml`:

126 210

127```211```

128model = "gpt-5.3-codex-spark"212model = "gpt-5.3-codex-spark"

129model_reasoning_effort = "medium"213model_reasoning_effort = "medium"

130sandbox_mode = "read-only"214sandbox_mode = "read-only"

215developer_instructions = """

216Map the code that owns the failing UI flow.

217Identify entry points, state transitions, and likely files before the worker starts editing.

218"""

219```

220

221`agents/browser-debugger.toml`:

222

223```

224model = "gpt-5.3-codex"

225model_reasoning_effort = "high"

226sandbox_mode = "workspace-write"

227developer_instructions = """

228Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

229Use browser tooling for screenshots, console output, and network evidence.

230Do not edit application code.

231"""

232

233[mcp_servers.chrome_devtools]

234url = "http://localhost:3000/mcp"

235startup_timeout_sec = 20

236```

237

238`agents/worker.toml`:

239

240```

241model = "gpt-5.3-codex"

242model_reasoning_effort = "medium"

243developer_instructions = """

244Own the fix once the issue is reproduced.

245Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

246"""

247

248[[skills.config]]

249path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

250enabled = false

251```

252

253This setup works well for prompts like:

254

255```

256Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.

131```257```

rules.md +1 −1

Details

43carefully before accepting it.43carefully before accepting it.

44 44

45Admins can also enforce restrictive `prefix_rule` entries from45Admins can also enforce restrictive `prefix_rule` entries from

~~46[`requirements.toml`](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml).~~46[`requirements.toml`](https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml).

47 47

48## Understand rule fields48## Understand rule fields

49 49

security.md +20 −159

Details

13 13

14Codex uses different sandbox modes depending on where you run it:14Codex uses different sandbox modes depending on where you run it:

15 15

16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. You can expand access intentionally (for example, to install dependencies or allow specific domains) when needed. Network access is always enabled during the setup phase, which runs before the agent has access to your code.16- **Codex cloud**: Runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data. Uses a two-phase runtime model: setup runs before the agent phase and can access the network to install specified dependencies, then the agent phase runs offline by default unless you enable internet access for that environment. Secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

17- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.17- **Codex CLI / IDE extension**: OS-level mechanisms enforce sandbox policies. Defaults include no network access and write permissions limited to the active workspace. You can configure the sandbox, approval policy, and network settings based on your risk tolerance.

18 18

19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.19In the `Auto` preset (for example, `--full-auto`), Codex can read files, make edits, and run commands in the working directory automatically.

20 20

21Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.21Codex asks for approval to edit files outside the workspace or to run commands that require network access. If you want to chat or plan without making changes, switch to `read-only` mode with the `/permissions` command.

22 22

~~23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change.~~23Codex can also elicit approval for app (connector) tool calls that advertise side effects, even when the action isn’t a shell command or file change. Destructive app/MCP tool calls always require approval when the tool advertises a destructive annotation, even if it also advertises other hints (for example, read-only hints).

24 24

25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)25## Network access [Elevated Risk](https://help.openai.com/articles/20001061)

26 26

73 73

74If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.74If you need Codex to read files, make edits, and run commands with network access without approval prompts, use `--sandbox danger-full-access` (or the `--dangerously-bypass-approvals-and-sandbox` flag). Use caution before doing so.

75 75

76For a middle ground, `approval_policy = { reject = { ... } }` lets you auto-reject specific approval prompt categories (sandbox escalation, execpolicy-rule prompts, or MCP elicitations) while keeping other prompts interactive.

76### Common sandbox and approval combinations78### Common sandbox and approval combinations

77 79

95# Always ask for approval mode97# Always ask for approval mode

96approval_policy = "untrusted"98approval_policy = "untrusted"

97sandbox_mode = "read-only"99sandbox_mode = "read-only"

100allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

98 101

99# Optional: Allow network in workspace-write mode102# Optional: Allow network in workspace-write mode

100[sandbox_workspace_write]103[sandbox_workspace_write]

101network_access = true104network_access = true

105

106# Optional: granular approval prompt auto-rejection

107# approval_policy = { reject = { sandbox_approval = true, rules = false, mcp_elicitations = false } }

102```108```

103 109

104You can also save presets as profiles, then select them with `codex --profile <name>`:110You can also save presets as profiles, then select them with `codex --profile <name>`:

130 136

131Codex enforces the sandbox differently depending on your OS:137Codex enforces the sandbox differently depending on your OS:

132 138

133- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected.139- **macOS** uses Seatbelt policies and runs commands using `sandbox-exec` with a profile (`-p`) that corresponds to the `--sandbox` mode you selected. When restricted read access enables platform defaults, Codex appends a curated macOS platform policy (instead of broadly allowing `/System`) to preserve common tool compatibility.

134- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`).140- **Linux** uses `Landlock` plus `seccomp` by default. You can opt into the alternative Linux sandbox pipeline with `features.use_linux_sandbox_bwrap = true` (or `-c use_linux_sandbox_bwrap=true`). In managed proxy mode, the bwrap pipeline routes egress through a proxy-only bridge and fails closed if it cannot build valid loopback proxy routes; landlock-only flows do not use that bridge behavior.

135- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, you can enable an [experimental sandbox](https://developers.openai.com/codex/windows#windows-experimental-sandbox) implementation.141- **Windows** uses the Linux sandbox implementation when running in [Windows Subsystem for Linux (WSL)](https://developers.openai.com/codex/windows#windows-subsystem-for-linux). When running natively on Windows, Codex uses a [Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox) implementation.

136 142

137If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:143If you use the Codex IDE extension on Windows, it supports WSL directly. Set the following in your VS Code settings to keep the agent inside WSL whenever it’s available:

138 144

144 150

145This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).151This ensures the IDE extension inherits Linux sandbox semantics for commands, approvals, and filesystem access even when the host OS is Windows. Learn more in the [Windows setup guide](https://developers.openai.com/codex/windows).

146 152

147The native Windows sandbox is experimental and has important limitations. For example, it can’t prevent writes in directories where the `Everyone` SID already has write permissions (for example, world-writable folders). See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-experimental-sandbox) for details and mitigation steps.153When running natively on Windows, configure the native sandbox mode in `config.toml`:

154

155```

156[windows]

157sandbox = "unelevated" # or "elevated"

158```

159

160See the [Windows setup guide](https://developers.openai.com/codex/windows#windows-sandbox) for details.

148 161

149When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.162When you run Linux in a containerized environment such as Docker, the sandbox may not work if the host or container configuration doesn’t support the required `Landlock` and `seccomp` features.

150 163

230 243

231## Managed configuration244## Managed configuration

232 245

233Enterprise admins can control local Codex behavior in two ways. For the exact key list, see the [`requirements.toml` section in Configuration Reference](https://developers.openai.com/codex/config-reference#requirementstoml):246Enterprise admins can configure Codex security settings for their workspace in [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration). See that page for setup and policy details.

~~234~~

235- **Requirements**: admin-enforced constraints that users can’t override.

236- **Managed defaults**: starting values applied when Codex launches. Users can still change settings during a session; Codex reapplies managed defaults the next time it starts.

~~237~~

238### Admin-enforced requirements (requirements.toml)

~~239~~

240Requirements constrain security-sensitive settings (approval policy, sandbox mode, web search mode, and optionally which MCP servers you can enable). If a user explicitly selects a disallowed value (via `config.toml`, CLI flags, profiles, or in-session UI), Codex rejects the change. If a value isn’t explicitly set and the default conflicts with requirements, Codex falls back to a requirements-compliant default. If you configure an `mcp_servers` approved list, Codex enables an MCP server only when both its name and identity match an approved entry; otherwise, Codex turns it off.

~~241~~

242#### Locations

~~243~~

244- Linux/macOS (Unix): `/etc/codex/requirements.toml`

245- macOS MDM: preference domain `com.openai.codex`, key `requirements_toml_base64`

~~246~~

247#### Cloud requirements (Business and Enterprise)

~~248~~

249When you sign in with ChatGPT on a Business or Enterprise plan, Codex can also

250fetch admin-enforced requirements from the Codex service. This applies across

251Codex surfaces, including the TUI, `codex exec`, and `codex app-server`.

~~252~~

253Cloud requirements are currently best-effort. If the fetch fails or times out,

254Codex continues without the cloud layer.

~~255~~

256Requirements layer in this order (higher wins):

~~257~~

258- macOS managed preferences (MDM; highest precedence)

259- Cloud requirements (ChatGPT Business or Enterprise)

260- `/etc/codex/requirements.toml`

~~261~~

262Cloud requirements only fill unset requirement fields, so higher-precedence

263managed layers still win when both specify the same constraint.

~~264~~

265For backwards compatibility, Codex also interprets legacy `managed_config.toml` fields `approval_policy` and `sandbox_mode` as requirements (allowing only that single value).

~~266~~

267#### Example requirements.toml

~~268~~

269This example blocks `--ask-for-approval never` and `--sandbox danger-full-access` (including `--yolo`):

~~270~~

271```

272allowed_approval_policies = ["untrusted", "on-request"]

273allowed_sandbox_modes = ["read-only", "workspace-write"]

274```

~~275~~

276You can also constrain web search mode:

~~277~~

278```

279allowed_web_search_modes = ["cached"] # "disabled" remains implicitly allowed

280```

~~281~~

282`allowed_web_search_modes = []` effectively allows only `"disabled"`.

283For example, `allowed_web_search_modes = ["cached"]` prevents live web search even in `danger-full-access` sessions.

~~284~~

285#### Enforce command rules from requirements

~~286~~

287Admins can also enforce restrictive command rules from `requirements.toml`

288using a `[rules]` table. These rules merge with regular `.rules` files, and the

289most restrictive decision still wins.

~~290~~

291Unlike `.rules`, requirements rules must specify `decision`, and that decision

292must be `"prompt"` or `"forbidden"` (not `"allow"`).

~~293~~

294```

295[rules]

296prefix_rules = [

297 { pattern = [{ token = "rm" }], decision = "forbidden", justification = "Use git clean -fd instead." },

298 { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }], decision = "prompt", justification = "Require review before mutating history." },

299]

300```

~~301~~

302To restrict which MCP servers Codex can enable, add an `mcp_servers` approved list. For stdio servers, match on `command`; for streamable HTTP servers, match on `url`:

~~303~~

304```

305[mcp_servers.docs]

306identity = { command = "codex-mcp" }

~~307~~

308[mcp_servers.remote]

309identity = { url = "https://example.com/mcp" }

310```

~~311~~

312If `mcp_servers` is present but empty, Codex disables all MCP servers.

~~313~~

314### Managed defaults (managed\_config.toml)

~~315~~

316Managed defaults merge on top of a user’s local `config.toml` and take precedence over any CLI `--config` overrides, setting the starting values when Codex launches. Users can still change those settings during a session; Codex reapplies managed defaults the next time it starts.

~~317~~

318Make sure your managed defaults meet your requirements; Codex rejects disallowed values.

~~319~~

320#### Precedence and layering

~~321~~

322Codex assembles the effective configuration in this order (top overrides bottom):

~~323~~

324- Managed preferences (macOS MDM; highest precedence)

325- `managed_config.toml` (system/managed file)

326- `config.toml` (user’s base configuration)

~~327~~

328CLI `--config key=value` overrides apply to the base, but managed layers override them. This means each run starts from the managed defaults even if you provide local flags.

~~329~~

330Cloud requirements affect the requirements layer (not managed defaults). See

331[Admin-enforced requirements](https://developers.openai.com/codex/security#admin-enforced-requirements-requirementstoml)

332for their precedence.

~~333~~

334#### Locations

~~335~~

336- Linux/macOS (Unix): `/etc/codex/managed_config.toml`

337- Windows/non-Unix: `~/.codex/managed_config.toml`

~~338~~

339If the file is missing, Codex skips the managed layer.

~~340~~

341#### macOS managed preferences (MDM)

~~342~~

343On macOS, admins can push a device profile that provides base64-encoded TOML payloads at:

~~344~~

345- Preference domain: `com.openai.codex`

346- Keys:

347 - `config_toml_base64` (managed defaults)

348 - `requirements_toml_base64` (requirements)

~~349~~

350Codex parses these “managed preferences” payloads as TOML and applies them with the highest precedence.

~~351~~

352### MDM setup workflow

~~353~~

354Codex honors standard macOS MDM payloads, so you can distribute settings with tooling like `Jamf Pro`, `Fleet`, or `Kandji`. A lightweight deployment looks like:

~~355~~

3561. Build the managed payload TOML and encode it with `base64` (no wrapping).

3572. Drop the string into your MDM profile under the `com.openai.codex` domain at `config_toml_base64` (managed defaults) or `requirements_toml_base64` (requirements).

3583. Push the profile, then ask users to restart Codex and confirm the startup config summary reflects the managed values.

3594. When revoking or changing policy, update the managed payload; the CLI reads the refreshed preference the next time it launches.

~~360~~

361Avoid embedding secrets or high-churn dynamic values in the payload. Treat the managed TOML like any other MDM setting under change control.

~~362~~

363### Example managed\_config.toml

~~364~~

365```

366# Set conservative defaults

367approval_policy = "on-request"

368sandbox_mode = "workspace-write"

~~369~~

370[sandbox_workspace_write]

371network_access = false # keep network disabled unless explicitly allowed

~~372~~

373[otel]

374environment = "prod"

375exporter = "otlp-http" # point at your collector

376log_user_prompt = false # keep prompts redacted

377# exporter details live under exporter tables; see Monitoring and telemetry above

378```

~~379~~

380### Recommended guardrails

~~381~~

382- Prefer `workspace-write` with approvals for most users; reserve full access for controlled containers.

383- Keep `network_access = false` unless your security review allows a collector or domains required by your workflows.

384- Use managed configuration to pin OTel settings (exporter, environment), but keep `log_user_prompt = false` unless your policy explicitly allows storing prompt contents.

385- Periodically audit diffs between local `config.toml` and managed policy to catch drift; managed layers should win over local flags and files.

windows.md +28 −23

Details

2 2

3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 4

5When you run Codex natively on Windows, the agent mode uses an experimental Windows sandbox to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-experimental-sandbox).5When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).

6 6

7Instead, you can use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2). WSL2 gives you a Linux shell, Unix-style semantics, and tooling that match many tasks that models see in training.7If you prefer to have Codex use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) (WSL2), [read the instructions](#windows-subsystem-for-linux) below.

9## Windows sandbox

11Native Windows sandbox support includes two modes that you can configure in `config.toml`:

13```

14[windows]

15sandbox = "unelevated" # or "elevated"

16```

18How `elevated` mode works:

20- Uses a Restricted Token approach with filesystem ACLs to limit which files the sandbox can write to.

21- Runs commands as a dedicated Windows Sandbox User.

22- Limits network access by installing Windows Firewall rules.

24### Grant sandbox read access

26When a command fails because the Windows sandbox can't read a directory, use:

28```text

29/sandbox-add-read-dir C:\absolute\directory\path

30```

32The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

8 33

9## Windows Subsystem for Linux34## Windows Subsystem for Linux

10 35

81 ```106 ```

82- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.107- If you need Windows access to files, they’re under `\wsl$\Ubuntu\home<user>` in Explorer.

83 108

~~84## Windows experimental sandbox~~109## Troubleshooting and FAQ

~~86The Windows sandbox support is experimental. How it works:~~

~~88- Launches commands inside a restricted token derived from an AppContainer profile.~~

~~89- Grants only specifically requested filesystem capabilities by attaching capability security identifiers to that profile.~~

~~90- Disables outbound network access by overriding proxy-related environment variables and inserting stub executables for common network tools.~~

92Its primary limitation is that it can’t prevent file writes, deletions, or creations in any directory where the Everyone SID already has write permissions (for example, world-writable folders). When using the Windows sandbox, Codex scans for folders where Everyone has write access and recommends that you remove that access.

~~94### Grant sandbox read access~~

~~96When a command fails because the Windows sandbox can't read a directory, use:~~

~~98```text~~

~~99/sandbox-add-read-dir C:\absolute\directory\path~~

100```

~~101~~

102The path must be an existing absolute directory. After the command succeeds, later commands that run in the sandbox can read that directory during the current session.

~~103~~

104### Troubleshooting and FAQ

105 110

106#### Installed extension, but it’s unresponsive111#### Installed extension, but it’s unresponsive

107 112

OpenAI - Codex Docs Changes 2026-02-23 18:27 UTC → 2026-02-27 18:15 UTC