Codex App Server

Tags

Install Options

Works With

Source

Skill Preview

# Codex App Server

Embed Codex into a host product using the same protocol used by OpenAI's rich Codex clients. This skill is adaptable across Electron, Swift, Next.js, and other hosts by choosing the right transport and bridge pattern for each environment.

## Start Here

1. Decide whether the request needs App Server or the Codex SDK.
2. Re-check the official docs if the request depends on the latest auth or protocol behavior.
3. Pick the closest bundled starter from `assets/` for the target host.
4. Generate version-matched schemas with `scripts/generate-schemas.sh` before building a typed client.

## Choose the Right Surface

- Use App Server when the host product needs embedded authentication, conversation history, approvals, streamed agent events, review mode, rate limits, or a custom UI around threads and turns.
- Use the Codex SDK for automation, CI, server-side jobs, or non-interactive workflows.
- Prefer `stdio` first for local desktop hosts that can spawn `codex app-server`. Use WebSocket when the host cannot manage a child process, when the UI is browser-based, or when a separate sidecar/service boundary is the cleaner architecture.
- Treat WebSocket and `experimentalApi` features as opt-in. They are useful, but they are not the safest production default.
- Desktop hosts like Electron and macOS Swift apps can usually use managed ChatGPT login comfortably because the browser flow returns to a localhost callback owned by app-server.
- Browser-first web apps usually need a server-side bridge or host-managed tokens. The documented managed ChatGPT flow returns an `authUrl` with a localhost callback, which is a poor default fit for a pure browser deployment.

## Workflow

1. Generate schemas from the same `codex` version you will run:

```bash
./scripts/generate-schemas.sh ./schemas
```

2. Start from the right asset:
- `assets/node-stdio-starter` for a greenfield Node/TS client.
- `assets/existing-app-auth-bridge` for an existing app that already owns auth, routing, or UI state.
- `assets/electron-main-process` for Electron main/preload/renderer boundaries.
- `assets/nextjs-web-sidecar` for a Next.js server-side bridge that keeps app-server off the browser bundle.
- `assets/swift-bridge-patterns` for Swift desktop and sidecar-based WebSocket patterns.

3. Implement the initialize handshake:
- Open the transport.
- Send `initialize` with `clientInfo`.
- Wait for the response.
- Send `initialized`.
- Do not send other requests before this handshake completes.

4. Manage threads:
- `thread/start` for a new conversation.
- `thread/resume` to continue an existing thread.
- `thread/fork` when the user wants a branch of existing history.
- `thread/read` and `thread/list` for history views that should not resume execution.

5. Manage turns:
- `turn/start` to submit user input.
- `turn/steer` for follow-up input on an in-flight turn.
- `turn/interrupt` to cancel.
- Keep reading notifications until `turn/completed`.

6. Render item streams correctly:
- Treat `item/started` and `item/completed` as the authoritative item state.
- Append deltas for `agentMessage`, `reasoning`, `plan`, and command output in order.
- Model the UI around `Thread`, `Turn`, and `ThreadItem`, not just plain chat messages.

7. Implement approvals:
- Render server-initiated approval requests for command execution, file changes, and `tool/requestUserInput`.
- Scope approval UI by `threadId` and `turnId`.
- Default to the narrowest approval option unless the user explicitly wants broader session permissions.

8. Implement auth:
- Use `apiKey` mode when the host app wants OpenAI API-key auth.
- Use managed `chatgpt` mode when app-server should own browser login and token refresh.
- Use `chatgptAuthTokens` when the host app already owns ChatGPT auth and can supply fresh `idToken` and `accessToken`.
- If the server sends `account/chatgptAuthTokens/refresh`, respond quickly with fresh tokens or the original request will fail.

9. Surface account state:
- Use `ac