app-server.md +51 −18
21Requests include `method`, `params`, and `id`:21Requests include `method`, `params`, and `id`:
22 22
23```json23```json
2424{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.1-codex" } }{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.4" } }
25```25```
26 26
27Responses echo the `id` with either `result` or `error`:27Responses echo the `id` with either `result` or `error`:
99 },99 },
100});100});
101send({ method: "initialized", params: {} });101send({ method: "initialized", params: {} });
102102send({ method: "thread/start", id: 1, params: { model: "gpt-5.1-codex" } });send({ method: "thread/start", id: 1, params: { model: "gpt-5.4" } });
103```103```
104 104
105## Core primitives105## Core primitives
123 123
124Clients must send a single `initialize` request per transport connection before invoking any other method on that connection, then acknowledge with an `initialized` notification. Requests sent before initialization receive a `Not initialized` error, and repeated `initialize` calls on the same connection return `Already initialized`.124Clients must send a single `initialize` request per transport connection before invoking any other method on that connection, then acknowledge with an `initialized` notification. Requests sent before initialization receive a `Not initialized` error, and repeated `initialize` calls on the same connection return `Already initialized`.
125 125
126126The server returns the user agent string it will present to upstream services. Set `clientInfo` to identify your integration.The server returns the user agent string it will present to upstream services plus `platformFamily` and `platformOs` values that describe the runtime target. Set `clientInfo` to identify your integration.
127 127
128`initialize.params.capabilities` also supports per-connection notification opt-out via `optOutNotificationMethods`, which is a list of exact method names to suppress for that connection. Matching is exact (no wildcards/prefixes). Unknown method names are accepted and ignored.128`initialize.params.capabilities` also supports per-connection notification opt-out via `optOutNotificationMethods`, which is a list of exact method names to suppress for that connection. Matching is exact (no wildcards/prefixes). Unknown method names are accepted and ignored.
129 129
159 },159 },
160 "capabilities": {160 "capabilities": {
161 "experimentalApi": true,161 "experimentalApi": true,
162162 "optOutNotificationMethods": [ "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
163 "codex/event/session_configured",
164 "item/agentMessage/delta"
165 ]
166 }163 }
167 }164 }
168}165}
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`.201- `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. Returned `thread` objects include runtime `status`.202- `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.203- `thread/loaded/list` - list the thread ids currently loaded in memory.
204- `thread/name/set` - set or update a thread's user-facing name for a loaded thread or a persisted rollout; emits `thread/name/updated`.
207- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.205- `thread/archive` - move a thread's log file into the archived directory; returns `{}` on success and emits `thread/archived`.
208- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.206- `thread/unsubscribe` - unsubscribe this connection from thread turn/item events. If this was the last subscriber, the server unloads the thread and emits `thread/closed`.
209- `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`.
210- `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.
211- `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`).
212- `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`.
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."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."
214- `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`.
215- `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"`.
216- `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.
217- `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.
218- `command/exec/write` - write `stdin` bytes to a running `command/exec` session or close `stdin`.
219- `command/exec/resize` - resize a running PTY-backed `command/exec` session.
220- `command/exec/terminate` - stop a running `command/exec` session.
218- `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`.
219- `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.
220- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).223- `collaborationMode/list` - list collaboration mode presets (experimental, no pagination).
221- `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`).
225- `plugin/list` - list discovered plugin marketplaces and plugin state, including install/auth policy metadata, marketplace errors, featured plugin ids, and the development-only `forceRemoteSync` option.
226- `plugin/read` - read one plugin by marketplace path and plugin name, including bundled skills, apps, and MCP server names.
227- `plugin/install` - install a plugin from a marketplace path.
228- `plugin/uninstall` - uninstall an installed plugin.
222- `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.
223- `skills/config/write` - enable or disable skills by path.230- `skills/config/write` - enable or disable skills by path.
224- `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.
225- `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.
226- `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.
227234- `mcpServerStatus/list` - list MCP servers, tools, resources, and auth status (cursor + limit pagination).- `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.
228- `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`.
229- `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).
230- `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.
231239- `externalAgentConfig/detect` - detect migratable external-agent artifacts with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).- `externalAgentConfig/detect` - detect external-agent artifacts that can be migrated with `includeHome` and optional `cwds`; each detected item includes `cwd` (`null` for home).
232- `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).
233- `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.
234- `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.
235- `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).
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.
236 245
237## Models246## Models
238 247
315 324
316```json325```json
317{ "method": "thread/start", "id": 10, "params": {326{ "method": "thread/start", "id": 10, "params": {
318327 "model": "gpt-5.1-codex", "model": "gpt-5.4",
319 "cwd": "/Users/me/project",328 "cwd": "/Users/me/project",
320 "approvalPolicy": "never",329 "approvalPolicy": "never",
321 "sandbox": "workspaceWrite",330 "sandbox": "workspaceWrite",
450`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:459`thread/unsubscribe` removes the current connection's subscription to a thread. The response status is one of:
451 460
452- `unsubscribed` when the connection was subscribed and is now removed.461- `unsubscribed` when the connection was subscribed and is now removed.
453462- `notSubscribed` when the connection was not subscribed to that thread.- `notSubscribed` when the connection wasn't subscribed to that thread.
454463- `notLoaded` when the thread is not loaded.- `notLoaded` when the thread isn't loaded.
455 464
456If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.465If this was the last subscriber, the server unloads the thread and emits a `thread/status/changed` transition to `notLoaded` plus `thread/closed`.
457 466
498{ "id": 25, "result": {} }507{ "id": 25, "result": {} }
499```508```
500 509
510### Run a thread shell command
511
512Use `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.
513
514This 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.
515
516If 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.
517
518```json
519{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
520{ "id": 26, "result": {} }
521```
522
523### Clean background terminals
524
525Use `thread/backgroundTerminals/clean` to stop all running background terminals associated with a thread. This method is experimental and requires `capabilities.experimentalApi = true`.
526
527```json
528{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
529{ "id": 27, "result": {} }
530```
531
501### Roll back recent turns532### Roll back recent turns
502 533
503Use `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.534Use `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.
504 535
505```json536```json
506537{ "method": "thread/rollback", "id": 26, "params": { "threadId": "thr_b", "numTurns": 1 } }{ "method": "thread/rollback", "id": 28, "params": { "threadId": "thr_b", "numTurns": 1 } }
507538{ "id": 26, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }{ "id": 28, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }
508```539```
509 540
510## Turns541## Turns
570 "writableRoots": ["/Users/me/project"],601 "writableRoots": ["/Users/me/project"],
571 "networkAccess": true602 "networkAccess": true
572 },603 },
573604 "model": "gpt-5.1-codex", "model": "gpt-5.4",
574 "effort": "medium",605 "effort": "medium",
575 "summary": "concise",606 "summary": "concise",
576 "personality": "friendly",607 "personality": "friendly",
713- The server rejects empty `command` arrays.744- The server rejects empty `command` arrays.
714- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).745- `sandboxPolicy` accepts the same shape used by `turn/start` (for example, `dangerFullAccess`, `readOnly`, `workspaceWrite`, `externalSandbox`).
715- When omitted, `timeoutMs` falls back to the server default.746- When omitted, `timeoutMs` falls back to the server default.
747- Set `tty: true` for PTY-backed sessions, and use `processId` when you plan to follow up with `command/exec/write`, `command/exec/resize`, or `command/exec/terminate`.
748- Set `streamStdoutStderr: true` to receive `command/exec/outputDelta` notifications while the command is running.
716 749
717### Read admin requirements (`configRequirements/read`)750### Read admin requirements (`configRequirements/read`)
718 751
773 806
774- Exact-match only: `item/agentMessage/delta` suppresses only that method.807- Exact-match only: `item/agentMessage/delta` suppresses only that method.
775- Unknown method names are ignored.808- Unknown method names are ignored.
776809- Applies to both legacy (`codex/event/*`) and v2 (`thread/*`, `turn/*`, `item/*`, etc.) notifications.- Applies to the current `thread/*`, `turn/*`, `item/*`, and related v2 notifications.
777- Doesn't apply to requests, responses, or errors.810- Doesn't apply to requests, responses, or errors.
778 811
779### Fuzzy file search events (experimental)812### Fuzzy file search events (experimental)
1149 1182
1150### Detect and import external agent config1183### Detect and import external agent config
1151 1184
11521185Use `externalAgentConfig/detect` to discover migratable external-agent artifacts, then pass the selected entries to `externalAgentConfig/import`.Use `externalAgentConfig/detect` to discover external-agent artifacts that can be migrated, then pass the selected entries to `externalAgentConfig/import`.
1153 1186
1154Detection example:1187Detection example:
1155 1188
1189{ "id": 64, "result": {} }1222{ "id": 64, "result": {} }
1190```1223```
1191 1224
11921225Supported `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.Supported `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 don’t overwrite existing skill directories.
1193 1226
1194## Auth endpoints1227## Auth endpoints
1195 1228