Codex App Server — Embeddable Agent Protocol & BYO Auth

Summary

Research into Codex app-server, the open-source JSON-RPC protocol that Codex itself uses to power rich clients (VS Code extension, Desktop). It provides programmatic threads, turns, streamed events, approvals, and conversation history — plus first-class "bring your own ChatGPT" auth in three modes. Goal: understand whether it enables the pattern of an app with an internal harness where users BYOK (API key or ChatGPT/Codex auth) without requiring platform sign-in.

Research Question

Can codex app-server be used as the model-access layer for an app where users bring their own OpenAI/ChatGPT credentials — as a composable alternative to (or complement of) gmail/github sign-in — and what is the right architecture shape?

Scope

Protocol: transports, lifecycle, message schema, core primitives (thread/turn/item)
Auth: ChatGPT managed, ChatGPT external tokens, API key, Bedrock
BYOK harness pattern: no-sign-in app + user-provided model access
Excluded: Codex SDK (CI/headless automation path), model internals

Key Findings

app-server is the sanctioned embedding protocol: open source (openai/codex/codex-rs/app-server), JSON-RPC 2.0, transports stdio (default) / WebSocket (experimental, unsupported for prod) / unix socket / off.
Programmatic surface is complete: initialize → thread/start|resume|fork → turn/start|steer|interrupt → streamed notifications (item deltas, turn/completed), plus command/exec, process sessions (experimental), review/start, account/read, account/rateLimits/read, account/usage/read. Generates exact TypeScript/JSON-Schema bindings per Codex version.
Three auth modes (account/login/start):
1. chatgpt / chatgptDeviceCode — Codex owns OAuth, persists + auto-refreshes tokens; device-code is the best web flow; user's ChatGPT plan pays for calls
2. chatgptAuthTokens (experimental) — host app owns the user's ChatGPT auth lifecycle, supplies JWT + accountId + planType, refreshes on 401
3. apiKey — classic BYOK
"Sign in with ChatGPT" ≠ identity provider: it is a model-access grant, not an identity layer — no email/profile returned; chatgptAccountId is OpenAI-side only. Composable pattern: gmail/github = identity, ChatGPT = optional model capability.
BYOK harness pattern is viable: no-sign-in app + user-provided key/auth is the standard "agent-as-component with BYOK" shape. The key design decision is where the key lives: local app → client-side; hosted web → browser localStorage or your DB (security surface); hosted + device-code → token stays in Codex's credential store (best no-account web option).
Caveats: WebSocket transport experimental for prod (hosted platform = per-user app-server processes + wss bridge); OpenAI compliance gate (clientInfo.name → Compliance Logs Platform; enterprise should contact OpenAI for known-clients list); capacity = user's plan rate limits; gray-area posture (Anthropic banned the Claude equivalent; OpenAI currently tolerates via official protocol).

Sources

For the full reference list see codex-app-server-byo-auth/sources.

Detail Files

codex-app-server-byo-auth/sources — primary docs + community references
codex-app-server-byo-auth/analysis — protocol deep-dive, auth modes, BYOK pattern, architecture shapes
codex-app-server-byo-auth/next-steps — build considerations, compliance, open questions

durable-agent-runtime/index — harness libraries family (nanocodex, Codex, pi); code-as-tool-interface pattern
Workspace note: RESEARCH/CODEX_APP_SERVER.md

Discussion

Triggered 2026-08-10 from the #research channel: user asked whether codex app-server can be leveraged so people bring their own ChatGPT OAuth to a platform/app. Follow-up clarified: (1) it's a model-access grant not identity; (2) the BYOK harness pattern (no-sign-in app, user provides OpenRouter key or ChatGPT auth) is exactly the "agent-as-component with BYOK" shape, with the key-location decision being the crux. User approved logging this as a vault topic.

Next Steps

Decide target app shape (local/desktop vs hosted web) before building
If hosted: contact OpenAI for known-clients list / compliance assessment
Prototype device-code flow with a minimal app-server client (Node/TS)

Conclusion

Codex app-server is a complete embeddable agent protocol with first-class BYO-ChatGPT auth. The BYOK harness pattern (anonymous app + user-provided model access) is viable and maps cleanly onto the user's Effect Layer adapter pattern — one provider interface, multiple implementations (ApiKeyProvider, ChatGptAuthProvider). The main engineering decision is key placement; the main risk is OpenAI's gray-area posture on BYO-ChatGPT.

5.5 KiB Raw Permalink Blame History