Operator admin UI

Codex Pooler’s admin UI is the browser workspace for people who run a self-hosted instance. It helps operators prepare capacity, issue client credentials, inspect routing health, and review metadata about activity.

The admin UI is metadata-only. Operators can see route names, Pool labels, upstream labels, model names, statuses, timings, token counts, safe error codes, and audit summaries. They don’t see raw prompt text, generated content, payload contents, file contents, media contents, credentials, session material, provider secrets, or raw Pool API keys.

Roles and visibility

The first account created during bootstrap is an instance owner. Owners can manage the whole instance, including Pools, operators, global jobs, and system settings.

Instance admins work inside assigned Pools. They can manage Pool-scoped upstreams, Pool API keys, request logs, and audit logs for those Pools. If an admin isn’t assigned to a Pool, the Pool-scoped pages show empty states instead of global data.

Historical request logs and audit logs for archived or deleted Pools are owner-only. This keeps old metadata available for accountability without exposing global history to admins who no longer own that Pool.

Pools

Pools are the main routing boundary. A Pool groups upstream account assignments, routing policy, model access, and the Pool API keys used by clients.

Use the dedicated Pools page for a detailed walkthrough of Pool cards, traffic indicators, footer links, routing settings, and dialog actions. At a high level, Pools answer operator questions such as:

1. Which Pools exist and who can operate them
2. Which upstreams are assigned to each Pool
3. Whether routing policy allows new client work
4. Which models and limits the Pool is expected to serve
5. Whether a Pool should stay active, be paused, or be archived

A Pool API key represents the Pool, not a single upstream. Runtime clients send the key to /backend-api or the narrow OpenAI-compatible /v1 surface, then Codex Pooler chooses an eligible upstream based on Pool policy, model support, health, limit evidence, and session continuity.

Upstreams

An upstream is a Codex account identity or Pool assignment that Codex Pooler can route eligible work to. Operators use the upstreams page to add accounts, check readiness, pause accounts, and review account status.

Use the dedicated Upstreams page for a detailed walkthrough of account cards, import dialogs, quota readiness, card actions, and the upstream cockpit. At a high level, Upstreams answer operator questions such as:

1. Which accounts are available to route Pool traffic
2. Which accounts are assigned to each Pool
3. Whether quota, freshness, or reauthorization blocks an account
4. Which account actions are available for recovery or lifecycle changes

Safe upstream metadata can include labels, assignment state, model support, quota window state, freshness state, stored account identifiers, and last observed routing status. Secret material is stored behind the upstream secret store. The UI doesn’t show provider credentials after import.

Common upstream states mean:

1. active, the account can be considered for eligible Pool traffic
2. paused, the account stays configured but isn’t selected for new traffic
3. reauth_required, the account needs operator attention before it can route work again
4. refreshing, the account is updating provider credentials or quota evidence

Pool API keys

Pool API keys are bearer credentials for runtime clients. Create one for each client, environment, or automation boundary that should use a Pool.

Use the dedicated API keys page for a detailed walkthrough of Pool registries, the policy wizard, one-time secret handling, rotation, and lifecycle actions.

The raw key is shown only once when created or rotated. After that, operators see lifecycle metadata such as display name, safe prefix, Pool, status, last-used and expiry state, model-policy warnings, notes, actions, and timestamps. Use it to rotate stale keys, pause a client, or confirm which Pool a client is allowed to use.

The API keys page is not an analytics surface. Use Stats for aggregate request, token, and cost analytics. Use Request logs for request-level investigation, including the API key label or safe prefix when available.

Pool API keys are separate from operator browser sessions and MCP tokens. Don’t use a Pool API key for admin UI sign-in or the operator MCP endpoint.

Invites and operators

Owners can invite operators and assign Pool access. Use invites for onboarding people who need browser access, then keep ongoing permissions on the operator record.

Use the dedicated Invites page for Pool onboarding links, delivery state, invite outcomes, and invite lifecycle actions.

Use the dedicated Operators page for local admin accounts, roles, Pool assignments, TOTP state, password resets, and account lifecycle actions.

Invite and operator pages should be treated as account-management surfaces. They show masked identity metadata, status, role, Pool assignments, and authentication setup state. They don’t reveal passwords, temporary credentials, TOTP secrets, MCP tokens, or raw emails beyond the UI’s safe display format.

Request logs

Request logs show routing and accounting metadata for runtime traffic. They are meant for operational questions, not content review.

Use the dedicated Request logs page for a detailed walkthrough of filters, table columns, status metadata, usage lines, and safe-error boundaries.

Request logs can help answer:

1. Which Pool received traffic
2. Which route family handled the request
3. Which model was requested
4. Whether the request succeeded, failed, retried, or was rejected
5. How long the request took
6. Which upstream assignment was selected, when that metadata is visible to the operator
7. Whether usage or cost reporting metadata is available

Request logs don’t show raw prompt text, generated content, payload contents, uploaded file contents, media contents, websocket contents, credentials, session material, or raw idempotency keys.

Audit logs

Audit logs track administrative changes and security-relevant events as metadata. They help owners and assigned admins understand who changed what, when it happened, and whether it succeeded.

Use the dedicated Audit logs page for a detailed walkthrough of filters, table columns, the event details drawer, and redacted detail fields.

Audit records can include actor class, masked actor identity, action, target kind, outcome, time, Pool label, request correlation metadata, and sanitized detail summaries. They don’t expose raw change blobs, secret settings, raw credentials, prompt text, provider payloads, or private identifiers.

Use audit logs to confirm operator changes such as Pool edits, upstream lifecycle changes, key creation or rotation, invite changes, operator permission updates, system settings changes, and MCP gate changes.

Jobs

The jobs page is owner-facing. It shows background work metadata so owners can see whether scheduled and queued maintenance tasks are healthy.

Use the dedicated System jobs page for a detailed walkthrough of worker cards, manual enqueue actions, live target markers, failure panels, filters, the explorer table, and the job detail drawer.

Job metadata can include worker name, queue, state, attempt count, timestamps, and safe error class. It is a status surface, not a deep recovery guide, and it doesn’t reveal job args that contain secrets or raw client content.

Typical job areas include catalog refresh, pricing import, account reconciliation, alert evaluation, token refresh, usage rollup rebuilds, and runtime cleanup. A failed or retrying job usually means an owner should check the affected product area, for example upstream quota freshness, Pool catalog state, alert rules, or request accounting.

System settings

System settings are owner-facing controls for instance behavior. They cover runtime limits, route admission, diagnostics, ingress trust, circuit thresholds, model metadata, pricing catalog settings, operator email, MCP service gates, metrics authentication, and SMTP delivery.

Secret settings are write-only. The UI may show fingerprints, key versions, status, or validation results, but not raw secret values. New settings apply to new runtime work after the settings cache reloads; in-flight requests and already-open streams keep the values they started with.