From 579057e977672723d25f8f4ec2b744ef21597ba0 Mon Sep 17 00:00:00 2001 From: hermes Date: Mon, 10 Aug 2026 03:38:10 +0000 Subject: [PATCH] Add codex-app-server-byo-auth research topic --- codex-app-server-byo-auth/analysis.md | 63 ++++++++++++++++++++++ codex-app-server-byo-auth/index.md | 69 +++++++++++++++++++++++++ codex-app-server-byo-auth/next-steps.md | 22 ++++++++ codex-app-server-byo-auth/sources.md | 24 +++++++++ 4 files changed, 178 insertions(+) create mode 100644 codex-app-server-byo-auth/analysis.md create mode 100644 codex-app-server-byo-auth/index.md create mode 100644 codex-app-server-byo-auth/next-steps.md create mode 100644 codex-app-server-byo-auth/sources.md diff --git a/codex-app-server-byo-auth/analysis.md b/codex-app-server-byo-auth/analysis.md new file mode 100644 index 0000000..5534ee5 --- /dev/null +++ b/codex-app-server-byo-auth/analysis.md @@ -0,0 +1,63 @@ +# Analysis — Codex App Server: Embeddable Agent Protocol & BYO Auth + +> Part of [[codex-app-server-byo-auth/index|Codex App Server — Embeddable Agent Protocol & BYO Auth]] + +## Protocol deep-dive + +### Transports and lifecycle +- Default transport is stdio (newline-delimited JSON). WebSocket and unix socket are alternatives; **WebSocket is explicitly experimental and unsupported for production workloads** (docs: "The app-server command and WebSocket transport are experimental and aren't supported for production workloads"). +- Every connection: `initialize` (with `clientInfo` identifying your product) → `initialized` notification → then any method. Requests before initialization get `Not initialized`. +- Core primitives: **Thread** (a conversation), **Turn** (one user request + agent work), **Item** (units: user message, agent message, command run, file change, tool call). +- Lifecycle: `thread/start` (or `resume`/`fork`), `turn/start`, then read streamed notifications (`item/*`, `turn/completed`), optionally `turn/steer` mid-flight, `turn/interrupt` to cancel. +- Capabilities opt-in: `experimentalApi: true` unlocks gated methods/fields (e.g. `thread/backgroundTerminals/*`, `process/spawn`). `requestAttestation` opt-in for desktop hosts. +- Bindings: `codex app-server generate-ts` / `generate-json-schema` produce per-version exact schemas — no drift between your types and the protocol. + +### Auth modes (the core of this research) +`account/login/start` accepts: +1. **`chatgpt`** (managed browser flow) — Codex owns OAuth, persists + auto-refreshes tokens. `useHostedLoginSuccessPage`, `appBrand` options. +2. **`chatgptDeviceCode`** — same managed lifecycle, but the user approves via a device code on another device. **Best for web** — no account on your side needed. +3. **`chatgptAuthTokens`** (experimental) — host app already owns the user's ChatGPT auth: supply `accessToken`, `chatgptAccountId`, optional `chatgptPlanType`; app-server requests fresh tokens from you on 401. You own the refresh loop. +4. **`apiKey`** — classic BYOK. +5. **Bedrock** (`amazonBedrock`) — AWS credential chain or Codex-managed key. +- `account/updated` notification reports auth mode changes + `planType`; `account/read` reports account/plan details; `account/rateLimits/read` + `account/usage/read` let your app surface the user's plan limits. + +## The BYOK harness pattern + +### "Sign in with ChatGPT" ≠ identity provider +- Google/GitHub sign-in → identity (email, profile). ChatGPT sign-in via app-server → model capability ("run Codex workloads billed to this user's ChatGPT plan"). No email/profile returned; `chatgptAccountId` is OpenAI-side only. +- Composable pattern: gmail/github = identity layer; ChatGPT = optional model-access layer. + +### The no-sign-in + BYOK shape +Works for both local and hosted apps. The one design decision that matters: **where does the key live?** + +| Shape | Key placement | Notes | +| --- | --- | --- | +| Local/desktop app | Client-side (localStorage/file), never leaves machine | Cleanest; BYOK-as-auth works perfectly, no server secrets | +| Hosted web, no sign-in | User's browser (localStorage, per-session) OR your DB | DB = you hold third-party secrets (security surface); browser = per-session, simpler | +| Hosted + device-code | Token stays in Codex's own credential store, not yours | Best "no-account" web option | + +### Adapter pattern (maps to user's Effect Layer/DI) +One provider interface, multiple implementations: +- `ApiKeyProvider` (OpenRouter/OpenAI key) +- `ChatGptAuthProvider` (app-server device-code or external tokens) +The harness (agent loop, tools, UI) is provider-agnostic — same as the user's Service + Layer adapter composition pattern from the job-aggregator/law-retrieval projects. + +## Architecture shapes + +### A. Desktop-embedded (stable, recommended first) +- Each user runs their own `codex app-server` process locally (stdio or unix socket), app connects over the local transport. +- Key/auth stored client-side. No server secrets. WebSocket not needed. +- Best fit: local tools, CLI-adjacent products, developer apps. + +### B. Hosted multi-tenant (more work, experimental transport) +- Per-user `codex app-server` processes on your infra, bridged over wss (WebSocket is experimental/unsupported for prod — this is the main risk). +- Key placement decision is critical: your DB (security surface) vs user's browser vs Codex-managed device-code tokens. +- Compliance: `clientInfo.name` feeds OpenAI's Compliance Logs Platform; contact OpenAI to get on a known-clients list for enterprise use. +- Capacity: each user's ChatGPT plan rate limits apply (`account/rateLimits/read` to surface them). + +## Risks / caveats +- **Gray-area posture**: Anthropic banned the Claude-equivalent BYO-subscription pattern; OpenAI currently tolerates this via the official protocol, but that posture can change. +- **Transport**: WebSocket experimental — hosted production means real engineering (per-user processes + bridge), not a drop-in. +- **Capacity**: user's plan bounds capacity; `account/rateLimitResetCredit/consume` exists but is user-side. +- **Compliance**: identify your client; enterprise integrations should be on OpenAI's known-clients list. +- **Not identity**: can't use `chatgptAccountId` as your user key. diff --git a/codex-app-server-byo-auth/index.md b/codex-app-server-byo-auth/index.md new file mode 100644 index 0000000..a3830d2 --- /dev/null +++ b/codex-app-server-byo-auth/index.md @@ -0,0 +1,69 @@ +--- +title: Codex App Server — Embeddable Agent Protocol & BYO Auth +description: Research into the Codex app-server JSON-RPC protocol — threads/turns/streaming, the three auth modes (ChatGPT managed, external tokens, API key), and the BYOK harness pattern for building no-sign-in apps where users bring their own model access (OpenRouter key or ChatGPT/Codex auth). +status: active +category: technical +tags: [codex, app-server, byok, byo-auth, oauth, agent-protocol, json-rpc, harness, chatgpt, openrouter] +draft: true +created: 2026-08-10 +updated: 2026-08-10 +origin: buzz://d8a718be-031f-4a6e-9f5c-a55466641654/65b5070a316c48eaa673e0ac8961118c280a26f9cb523c06fcefde74daf503a4 +--- + +# 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|Sources]]. + +## Detail Files + +- [[codex-app-server-byo-auth/sources|Sources]] — primary docs + community references +- [[codex-app-server-byo-auth/analysis|Analysis]] — protocol deep-dive, auth modes, BYOK pattern, architecture shapes +- [[codex-app-server-byo-auth/next-steps|Next Steps]] — build considerations, compliance, open questions + +## Related Research + +- [[durable-agent-runtime/index|Durable Agent Runtimes & Harness Engineering]] — 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. diff --git a/codex-app-server-byo-auth/next-steps.md b/codex-app-server-byo-auth/next-steps.md new file mode 100644 index 0000000..df04042 --- /dev/null +++ b/codex-app-server-byo-auth/next-steps.md @@ -0,0 +1,22 @@ +# Next Steps — Codex App Server: Embeddable Agent Protocol & BYO Auth + +> Part of [[codex-app-server-byo-auth/index|Codex App Server — Embeddable Agent Protocol & BYO Auth]] + +## Decisions pending + +- [ ] Pick the target app shape first: local/desktop (stable, recommended) vs hosted multi-tenant (experimental transport, more work) +- [ ] For hosted: decide key placement — user's browser (localStorage) vs your DB vs Codex-managed device-code tokens +- [ ] For hosted: contact OpenAI for the known-clients list / compliance assessment before building for enterprise + +## Build considerations + +- [ ] Prototype the device-code flow with a minimal app-server client (Node/TS) to validate the no-sign-in UX +- [ ] Design the provider adapter interface (Effect Layer): `ApiKeyProvider` vs `ChatGptAuthProvider` +- [ ] Evaluate per-version bindings (`generate-ts` / `generate-json-schema`) for type safety +- [ ] Consider Codex SDK for any CI/headless automation needs (separate from app-server embedding) + +## Open questions + +- [ ] Does OpenAI's BYO-ChatGPT posture change over time? (monitor; Anthropic precedent exists) +- [ ] What's the real token-refresh behavior of `chatgptAuthTokens` mode in production? +- [ ] Rate-limit surfacing: which plan limits matter per target user base? diff --git a/codex-app-server-byo-auth/sources.md b/codex-app-server-byo-auth/sources.md new file mode 100644 index 0000000..fb4ef18 --- /dev/null +++ b/codex-app-server-byo-auth/sources.md @@ -0,0 +1,24 @@ +# Sources — Codex App Server: Embeddable Agent Protocol & BYO Auth + +> Part of [[codex-app-server-byo-auth/index|Codex App Server — Embeddable Agent Protocol & BYO Auth]] + +## Primary + +- [Codex App Server docs (learn.chatgpt.com)](https://learn.chatgpt.com/docs/app-server) — the authoritative protocol documentation: transports, message schema, lifecycle, core primitives, auth modes, account/rate-limit/usage APIs +- [Codex GitHub repo — app-server source](https://github.com/openai/codex/tree/main/codex-rs/app-server) — open-source implementation (`openai/codex/codex-rs/app-server`) +- [Codex CLI customization docs](https://learn.chatgpt.com/docs/guide/cli-customization) — related client-side config +- [Codex logs reference (ChatGPT admin API)](https://chatgpt.com/admin/api-reference/Logs:-Codex) — Compliance Logs Platform context for `clientInfo.name` + +## Protocol / auth reference (verified 2026-08-10) + +- Transports: `stdio` (default, JSONL), `websocket` (`ws://IP:PORT`, experimental + unsupported for prod), `unix://`, `off` +- Auth modes (`account/login/start`): `chatgpt` (browser flow), `chatgptDeviceCode` (device-code flow), `chatgptAuthTokens` (experimental — host-owned tokens), `apiKey`, plus Bedrock (`amazonBedrock`) +- Core methods: `initialize`, `thread/start|resume|fork|read|list|archive|delete`, `turn/start|steer|interrupt`, `command/exec`, `review/start`, `account/read`, `account/rateLimits/read`, `account/usage/read`, `account/sendAddCreditsNudgeEmail` +- Bindings: `codex app-server generate-ts` and `generate-json-schema` produce exact per-version schemas + +## Context / related + +- Workspace note: `RESEARCH/CODEX_APP_SERVER.md` — first-pass research with the full caveat set +- Vault topic: `durable-agent-runtime` — harness libraries family (nanocodex, Codex, pi), code-as-tool-interface +- OpenClaw — community tool that routes users' ChatGPT subscriptions through a Codex-shaped client (BYO-ChatGPT precedent) +- Anthropic's ban of the Claude-equivalent BYO-subscription pattern — the gray-area precedent