app-server.md Codex Docs, 2026-03-27 00:39 UTC → 2026-04-21 12:30 UTC

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

208- `thread/status/changed` - notification emitted when a loaded thread's runtime `status` changes.208- `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.209- `thread/compact/start` - trigger conversation history compaction for a thread; returns `{}` immediately while progress streams via `turn/*` and `item/*` notifications.

210- `thread/shellCommand` - run a user-initiated shell command against a thread. This runs outside the sandbox with full access and doesn't inherit the thread sandbox policy.

211- `thread/backgroundTerminals/clean` - stop all running background terminals for a thread (experimental; requires `capabilities.experimentalApi`).

210- `thread/rollback` - drop the last N turns from the in-memory context and persist a rollback marker; returns the updated `thread`.212- `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."213- `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/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.214- `turn/steer` - append user input to the active in-flight turn for a thread; returns the accepted `turnId`.

213- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.215- `turn/interrupt` - request cancellation of an in-flight turn; success is `{}` and the turn ends with `status: "interrupted"`.

214- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.216- `review/start` - kick off the Codex reviewer for a thread; emits `enteredReviewMode` and `exitedReviewMode` items.

215- `command/exec` - run a single command under the server sandbox without starting a thread/turn.217- `command/exec` - run a single command under the server sandbox without starting a thread/turn.

216- `command/exec/write` - write stdin bytes to a running `command/exec` session or close stdin.218- `command/exec/write` - write `stdin` bytes to a running `command/exec` session or close `stdin`.

217- `command/exec/resize` - resize a running PTY-backed `command/exec` session.219- `command/exec/resize` - resize a running PTY-backed `command/exec` session.

218- `command/exec/terminate` - terminate a running `command/exec` session.220- `command/exec/terminate` - stop a running `command/exec` session.

219- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.221- `model/list` - list available models (set `includeHidden: true` to include entries with `hidden: true`) with effort options, optional `upgrade`, and `inputModalities`.

220- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.222- `experimentalFeature/list` - list feature flags with lifecycle stage metadata and cursor pagination.

221- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).

222- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).224- `skills/list` - list skills for one or more `cwd` values (supports `forceReload` and optional `perCwdExtraUserRoots`).

223- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata.225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace load errors, featured plugin ids, and local, Git, or remote plugin source metadata.

224- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.226- `plugin/read` - read one plugin by marketplace path or remote marketplace name and plugin name, including bundled skills, apps, and MCP server names when those details are available.

227- `plugin/install` - install a plugin from a marketplace path or remote marketplace name.

228- `plugin/uninstall` - uninstall an installed plugin.

225- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.229- `app/list` - list available apps (connectors) with pagination plus accessibility/enabled metadata.

226- `skills/config/write` - enable or disable skills by path.230- `skills/config/write` - enable or disable skills by path.

227- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.231- `mcpServer/oauth/login` - start an OAuth login for a configured MCP server; returns an authorization URL and emits `mcpServer/oauthLogin/completed` on completion.

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

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

230- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).234- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination). Use `detail: "full"` for full data or `detail: "toolsAndAuthOnly"` to omit resources.

235- `mcpServer/resource/read` - read a single MCP resource through an initialized MCP server.

231- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.236- `windowsSandbox/setupStart` - start Windows sandbox setup for `elevated` or `unelevated` mode; returns quickly and later emits `windowsSandbox/setupCompleted`.

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

233- `config/read` - fetch the effective configuration on disk after resolving configuration layering.238- `config/read` - fetch the effective configuration on disk after resolving configuration layering.

234- `externalAgentConfig/detect` - detect migratable external-agent artifacts with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).239- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).

235- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).240- `externalAgentConfig/import` - apply selected external-agent migration items by passing explicit `migrationItems` with `cwd` (`null` for home).

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

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

238- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).243- `configRequirements/read` - fetch requirements from `requirements.toml` and/or MDM, including allow-lists, pinned `featureRequirements`, and residency/network requirements (or `null` if you haven't set any up).

239- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.244- `fs/readFile`, `fs/writeFile`, `fs/createDirectory`, `fs/getMetadata`, `fs/readDirectory`, `fs/remove`, and `fs/copy` - operate on absolute filesystem paths through the app-server v2 filesystem API.

240 245 

246Plugin summaries include a `source` union. Local plugins return

247`{ "type": "local", "path": ... }`, Git-backed marketplace entries return

248`{ "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }`,

249and remote catalog entries return `{ "type": "remote" }`. For remote-only

250catalog entries, `PluginMarketplaceEntry.path` can be `null`; pass

251`remoteMarketplaceName` instead of `marketplacePath` when reading or installing

252those plugins.

253 

241## Models254## Models

242 255 

243### List models (`model/list`)256### List models (`model/list`)

454`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:467`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:

455 468 

456- `unsubscribed` when the connection was subscribed and is now removed.469- `unsubscribed` when the connection was subscribed and is now removed.

457- `notSubscribed` when the connection was not subscribed to that thread.470- `notSubscribed` when the connection wasn't subscribed to that thread.

458- `notLoaded` when the thread is not loaded.471- `notLoaded` when the thread isn't loaded.

459 472 

460If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.473If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.

461 474 

502{ "id": 25, "result": {} }515{ "id": 25, "result": {} }

503```516```

504 517 

518### Run a thread shell command

519 

520Use `thread/shellCommand` for user-initiated shell commands that belong to a thread. The request returns immediately with `{}` while progress streams through standard `turn/*` and `item/*` notifications.

521 

522This API runs outside the sandbox with full access and doesn't inherit the thread sandbox policy. Clients should expose it only for explicit user-initiated commands.

523 

524If the thread already has an active turn, the command runs as an auxiliary action on that turn and its formatted output is injected into the turn's message stream. If the thread is idle, app-server starts a standalone turn for the shell command.

525 

526```json

527{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }

528{ "id": 26, "result": {} }

529```

530 

531### Clean background terminals

532 

533Use `thread/backgroundTerminals/clean` to stop all running background terminals associated with a thread. This method is experimental and requires `capabilities.experimentalApi = true`.

534 

535```json

536{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }

537{ "id": 27, "result": {} }

538```

539 

505### Roll back recent turns540### Roll back recent turns

506 541 

507Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.542Use `thread/rollback` to remove the last `numTurns` entries from the in-memory context and persist a rollback marker in the rollout log. The returned `thread` includes `turns` populated after the rollback.

508 543 

509```json544```json

510{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }545{ "method": "thread/rollback", "id": 28, "params": { "threadId": "thr_b", "numTurns": 1 } }

511{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }546{ "id": 28, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

512```547```

513 548 

514## Turns549## Turns

1155 1190 

1156### Detect and import external agent config1191### Detect and import external agent config

1157 1192 

1158Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.1193Use `externalAgentConfig/detect` to discover external-agent artifacts that can be migrated, then pass the selected entries to `externalAgentConfig/import`.

1159 1194 

1160Detection example:1195Detection example:

1161 1196 

1195{ "id": 64, "result": {} }1230{ "id": 64, "result": {} }

1196```1231```

1197 1232 

1198Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, and `MCP_SERVER_CONFIG`. Detection returns only items that still have work to do. For example, AGENTS migration is skipped when `AGENTS.md` already exists and is non-empty, and skill imports do not overwrite existing skill directories.1233Supported `itemType` values are `AGENTS_MD`, `CONFIG`, `SKILLS`, `PLUGINS`,

1234and `MCP_SERVER_CONFIG`. For `PLUGINS` items, `details.plugins` lists each

1235`marketplaceName` and the `pluginNames` Codex can try to migrate. Detection

1236returns only items that still have work to do. For example, Codex skips AGENTS

1237migration when `AGENTS.md` already exists and is non-empty, and skill imports

1238don't overwrite existing skill directories.

1239 

1240When detecting plugins from `.claude/settings.json`, Codex reads configured

1241marketplace sources from `extraKnownMarketplaces`. If `enabledPlugins` contains

1242plugins from `claude-plugins-official` but the marketplace source is missing,

1243Codex infers `anthropics/claude-plugins-official` as the source.

1199 1244 

1200## Auth endpoints1245## Auth endpoints

1201 1246