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