wolfy-j/codex-endpoint

Optional, owner-operated Codex CLI compatibility endpoint and dashboard for a Codex Personal Pool.

[!WARNING] Personal-use only. This package is designed for one owner and that owner's clients. It is not recommended or supported for multi-user, team, shared-subscription, credential-sharing, public-gateway, or hosted-service environments.

codex-endpoint extends wolfy-j/codex-lb with a Codex-compatible Responses API on an existing host public router and a redacted operational dashboard. It does not open a port, create a listener, or run a standalone proxy.

What it provides

• Dynamic POST /api/public/codex/responses and GET /api/public/codex/models routes on an injected public host router.
• Named, independently revocable client keys issued from the authenticated dashboard and revealed only once.
• Durable enable/disable state and a selected Codex Personal Pool provider profile.
• A codex-pool-dashboard web component and /codex host navigation item for redacted allowance, credit, token-activity, and traffic views.
• A single reconciler that creates the compatibility routes only while the endpoint is enabled and restores that projection after a host restart.
• A boot-supervised, in-runtime WebSocket bridge with one transient worker per Codex session. It preserves native previous_response_id continuation and input-delta reuse without another listener or sidecar.

Installation and setup

Install wolfy-j/codex-endpoint alongside wolfy-j/codex-lb. The module depends on the Codex provider and expects a host that supplies its normal database, authenticated API router, public API router, process host, provider profile resolver, and web-component service.

After installation:

1. Create and authorize a Codex Personal Pool profile with wolfy-j/codex-lb.
2. Open the host's Codex Pool dashboard, select the profile, and enable the endpoint.
3. In Client keys, issue a named key for the machine or agent and copy it immediately. The plaintext cannot be retrieved again.
4. Save that key in an owner-only file on the client and use the dashboard's ready-to-copy Codex provider block. It configures the public base URL, wire_api = "responses", requires_openai_auth = false, and Codex command authentication that reads the key file.

The dashboard and key-management APIs use the host's normal authenticated session. The public compatibility routes use only a dedicated client key. A pre-existing CODEX_ENDPOINT_API_KEY remains accepted as a migration fallback but is no longer required for newly connected clients.

Security and intended use

This is a single-owner integration, not a shared gateway or multi-tenant service. Client keys are distinct from Codex OAuth credentials and are never sent upstream. Only SHA-256 hashes are stored; the plaintext appears in the authenticated browser once at issuance. OAuth credentials remain within codex-lb's private credential store.

The endpoint is disabled by default. When disabled, its dynamic public routes do not exist. Outside the one-time client-key creation response, the dashboard receives only redacted operational data and key prefixes; it never receives prompts, response bodies, OAuth tokens, raw auth files, stored token hashes, or recoverable client credentials.

Session workers keep only structural request/output hashes and an opaque upstream response ID in memory. Client disconnect, socket loss, credential or profile change, supervisor shutdown, and idle expiry all discard that state.

License

MIT. See LICENSE.