0xrsydn/research
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add codex-app-server-byo-auth research topic

Browse source
This commit is contained in:
hermes 2026-08-10 03:38:10 +00:00
commit 579057e977
4 changed files with 178 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

63
codex-app-server-byo-auth/analysis.md Normal file
View file

@ -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.

69
codex-app-server-byo-auth/index.md Normal file
View file

@ -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.

22
codex-app-server-byo-auth/next-steps.md Normal file
View file

@ -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?

24
codex-app-server-byo-auth/sources.md Normal file
View file

@ -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