prodex：支持多账号、多提供商的 Codex 包装器

prodex is a multi-account, multi-provider Codex wrapper with quota-aware profile routing.

Use multiple Codex accounts and supported provider backends from one command line. OpenAI/Codex profiles get quota-aware routing and can auto-rotate when multiple eligible profiles exist; provider adapters let prodex s launch the Codex front end against Gemini, Anthropic, Copilot, Kiro, DeepSeek, and local OpenAI-compatible servers.

Contents

• Why prodex
• Requirements
• Supported providers
• Installation
• Optional tools
• Quick start
• Daily command: prodex s
• Commands
• Modes
• Sub-agents
• Harness modes
• Profiles
• Local model support
• Utilities and diagnostics
• Advanced behavior
• Documentation
• Support

Why prodex

Use prodex if you want to:

• use multiple Codex accounts from one CLI
• rotate to another eligible account when quota runs out
• launch Codex/Super against non-OpenAI providers without changing front ends
• keep profile auth.json account credentials separated
• keep sessions attached to the profile that created them
• run Codex and Super mode through the supported wrapper

If you only use one Codex account and do not need quota rotation, you probably do not need prodex.

Requirements

For OpenAI/Codex quota-aware routing, you need at least one logged-in Prodex profile. Local --url launches and some provider API-key launches can run without a persisted profile.

Tool requirements

Supported providers

Prodex supports two provider paths:

• Profile-backed routing: persisted profiles that Prodex can select, rotate, and inspect where provider APIs allow it.
• Runtime provider launch: prodex s gemini, prodex s deepseek, or prodex s --provider ... starts Codex with a temporary provider bridge for that session.

Supported provider matrix

prodex gateway exposes the provider bridge as a standalone OpenAI-compatible service for non-Codex clients:

Gateway quickstart

PRODEX_GATEWAY_TOKEN=change-me GEMINI_API_KEY=... prodex gateway --provider gemini
auth_header="Authorization: Bearer $PRODEX_GATEWAY_TOKEN"
curl http://127.0.0.1:4000/v1/responses \
  -H "$auth_header" \
  -H "Content-Type: application/json" \
  -d '{"model":"prodex-fast","input":"hello"}'

Gateway capabilities (advanced)

The gateway serves /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/images/*, /v1/audio/*, /v1/batches, /v1/rerank, /v1/a2a, /v1/messages, and /v1/models where the selected upstream supports them. It adds x-prodex-call-id to responses, writes local request detail plus gateway_spend events for both request and response phases to runtime logs, can export those events to JSONL or HTTP using generic, OTel, Datadog, or Langfuse-shaped payloads, supports catalog-backed policy routing strategies (fallback, round-robin, least-busy, lowest-cost, lowest-latency, rpm, tpm, first) for model aliases/fallback chains, can enforce static virtual keys with persisted request/spend usage plus model/budget/RPM/TPM limits, supports file, SQLite, Postgres, or Redis-backed gateway admin/usage/ledger/SCIM state, and can apply keyword/model, local PII redaction, Presidio, and external webhook guardrails before calls and on outputs. Admin-token, trusted-proxy SSO, or OIDC/JWT bearer requests can list usage, create generated-token keys, rotate/disable/update/delete admin-managed keys, provision SSO users through SCIM-compatible /v1/prodex/gateway/scim/v2/Users, inspect usage at /v1/prodex/gateway/keys and /v1/prodex/gateway/usage, read recent billing ledger records with response-status/output-token reconciliation at /v1/prodex/gateway/ledger, read aggregated billing totals at /v1/prodex/gateway/ledger/summary, export billing CSV from /v1/prodex/gateway/ledger.csv and /v1/prodex/gateway/ledger/summary.csv, scrape Prometheus text metrics at /v1/prodex/gateway/metrics, inspect provider adapter contracts at /v1/prodex/gateway/providers or offline with prodex gateway providers --json, inspect active observability and guardrail configuration at /v1/prodex/gateway/observability and /v1/prodex/gateway/guardrails, fetch the checked-in gateway OpenAPI document at /v1/prodex/gateway/openapi.json, and open the built-in gateway admin dashboard at /v1/prodex/gateway/admin; the document describes the gateway's documented routes, not complete upstream OpenAPI or provider semantics, and /v1/a2a is separate from local prodex super --sub-agent execution. Policy/env-backed keys remain read-only, SCIM users can carry tenant/team/project/user/budget scopes for SSO/OIDC fallback, admin-managed key and SCIM user mutations emit prodex audit events, and additional admin-plane tokens can be admin or read-only viewer with optional virtual-key prefix plus tenant/team/project/user/budget scopes. Configure defaults under [gateway] in policy.toml; validate provider catalog edits with node scripts/catalog/provider-catalog-check.mjs. The generated provider matrix lives in docs/provider-capabilities.md.

The gateway can enforce optional model-aware request constraints under [gateway.request_constraints]; compatibility defaults leave enforcement disabled and oversized output requests unchanged. Admin/viewer principals can use the dashboard Route Workbench or POST /v1/prodex/gateway/routes/explain to inspect the same bounded planner trace without sending upstream traffic or mutating quota, billing, affinity, circuit, admission, or persisted runtime state. Explain payloads and prompt content are not logged or stored.

Gateway virtual-key realtime WebSocket sessions use bounded 32 KiB frames, a five-minute session ceiling, an upfront token reservation, per-frame accounting, and terminal usage reconciliation. One governed provider/profile is fixed before upgrade; policy denial or token exhaustion closes the session without rotation.

Governance policy/classification/provider-registry lifecycle endpoints require SQLite or PostgreSQL state. File and Redis remain compatibility backends for the documented admin/usage surfaces and return 501 governance_policy_operation_unsupported for governance lifecycle operations; bank mode requires PostgreSQL.

Enterprise OTLP export endpoints from OTEL_EXPORTER_OTLP_LOGS_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT must be absolute http:// or https:// URLs without whitespace, userinfo, query strings, or fragments; put collector credentials in OTEL_EXPORTER_OTLP_HEADERS. prodex-control-plane plan-http-control-plane request files must use the top-level principal field and non-credential HTTP headers, because Authorization headers are rejected.

[gateway.adaptive_routing] is opt-in. With enabled = true, Prodex keeps bounded per-model outcome/latency windows and can reorder only fresh pre-commit alias fallbacks; shadow_mode = true records the recommendation without changing selection. Hard continuation affinity, quota filtering, and the no-mid-stream-rotation boundary remain authoritative. Optional exploration_rate is deterministic per request and bounded from 0.0 to 1.0.

JavaScript clients can use @christiandoxa/prodex-gateway-sdk for /v1/responses plus gateway key, usage, billing ledger, metrics, and OpenAPI admin calls.

Provider behavior details (advanced)

The auto-rotate proxy is intentionally conservative. It rotates only before a request or stream is committed, preserves previous_response_id, turn-state, and session affinity, and does not rotate mid-stream. For fresh work, an explicit account-quota failure excludes that profile and continues through every remaining eligible profile before the final upstream quota response is exposed. Pre-commit transport exhaustion tries the same finite pool before returning local 503 service_unavailable; generic 429 responses, hard-affinity continuations, and committed output are never replayed merely to hide an error. An explicit temporary rate limit uses bounded Retry-After backoff, while provider-wide overload remains a separate retryable state and is not reported as quota exhaustion. OpenAI capacity is model-aware: when the backend explicitly authorizes Luna Reserve, ordinary Luna quota is blocked, and the mapped gpt-reserve bucket is ready, Prodex keeps the requested model as gpt-5.6-luna but sends the hidden Reserve route upstream. Sol, Terra, reused WebSocket sessions, and continuations never switch to Reserve. Reserve activation does not redeem reset credits. If regular and Reserve Luna capacity are unavailable, Prodex rotates or exposes the upstream quota response without substituting another public OpenAI model. Prodex does not auto-redeem reset credits by default. If you launch an OpenAI/Codex runtime path with --auto-redeem, Prodex may redeem one earned reset credit only when the weekly usage-limit window is exhausted, no other profile in the quota pool still has weekly quota remaining, and the weekly reset is not already imminent, then retries the same profile before rotating. It still does not redeem for merely critical/thin windows or 5h-only exhaustion. You can also run prodex redeem <profile> to send one explicit reset-credit consume request for a named OpenAI/Codex profile; the upstream backend decides whether that manual request applies, reports nothing-to-reset, or reports no-credit/already-redeemed. OpenAI/Codex remains the default quota-aware pool. Antigravity CLI, imported Copilot profiles, Anthropic OAuth profiles, DeepSeek API keys, local OpenAI-compatible URLs, and Bedrock/custom Codex providers have prodex quota views. Anthropic, DeepSeek, API-key Gemini, API-key Copilot, Antigravity CLI, local URLs, and Bedrock/custom Codex providers skip OpenAI quota preflight.

Runtime proxy design contract:

• Prodex stays a scoped Codex gateway, not a general-purpose LLM SDK.
• Profile selection must be visible through policy, prodex info, prodex doctor, and runtime logs.
• Pre-commit retry and fallback paths must stay bounded per request.
• Runtime hot paths must avoid broad disk reads, quota probes, or blocking state saves.
• Quota, budget, transport, and local pressure signals must stay classified separately.
• Selection, admission, affinity, backoff, and first-chunk events must be structured in runtime logs.
• Upstream HTTP/WebSocket connection reuse should be preserved where it does not change Codex semantics.
• Secrets remain profile-isolated and redacted in diagnostics. Prodex-owned mutations emit local audit events; immutable compliance retention, break-glass evidence, SIEM durability, and disaster recovery remain deployment/governance responsibilities. Local audit events and Super/sub-agent overlays do not prove those deployment controls.

Installation

These commands install the latest published release.

macOS or Linux:

curl -fsSL https://github.com/christiandoxa/prodex/releases/latest/download/install.sh | sh

Windows PowerShell:

irm https://github.com/christiandoxa/prodex/releases/latest/download/install.ps1 | iex

Managed profiles require Windows symbolic-link permission. Enable Developer Mode, grant SeCreateSymbolicLinkPrivilege, or run Prodex as an administrator before importing or creating a profile. Prodex checks this before migrating profile state and reports an actionable error when permission is unavailable.

Installer verification and legacy migration

Both installers verify their downloaded assets against the release SHA256SUMS file. The release workflow malware-scans final assets and verifies installer provenance.

Set PRODEX_INSTALL_DIR to choose another binary directory. Standalone installs do not include or install Codex: install the official Codex CLI and verify codex --version, or set PRODEX_CODEX_BIN to its executable. Prodex requires Codex 0.153.2 or newer with app-server, skips the exact binaries bundled by Prodex 0.426.1, and does not delete or replace them. Existing npm or Cargo installations can run prodex update once to migrate; the migration leaves profiles, sessions, configuration, and Codex files untouched.

The npm package installs the Prodex wrapper and platform binary only; it requires the official Codex CLI separately. Cargo installations are not a supported user installation channel; contributors should use normal workspace commands such as cargo build.

Optional tools

Prodex Super keeps a deliberately small optional stack:

• Caveman for an optional response-style plugin.
• RTK for noisy shell output.
• Codebase Memory MCP for structural code navigation.
• Playwright MCP for browser inspection and automation.
• Ponytail for minimal-implementation guidance.
• Presidio for opt-in PII redaction.

Caveman is externally installed and validated; Smart Context is built into the Codex runtime proxy, not guaranteed for native opaque CLIs. Every default Codex-based prodex s or prodex playwright launch adds the installed compatible Playwright MCP package to its temporary overlay when Node.js 18+ and npx pass launch-time validation. Prodex does not require one exact optional-tool version at runtime: missing tools are skipped, compatible releases at or above each minimum are accepted, and an installed-but-incompatible tool fails with an upgrade instruction. Release qualification still tracks the latest stable references. See Optional Tools for minimum versions, latest-stable references, managed paths, and validation rules.

prodex s expose exec snapshots the same launch-resolved optional-tool stack when the endpoint starts and advertises the usable entries in MCP initialize instructions and the prodex_super_exec tool metadata. Remote callers can use explicit program: "optional:<tool>" aliases without guessing installation paths: optional:rtk and optional:codebase-memory-mcp run their validated executables directly, optional:playwright-mcp runs the validated Playwright MCP package through npx --no-install, and optional:caveman, optional:ponytail, optional:playwright, and optional:presidio launch the corresponding Prodex Super integration. Presidio is advertised only while both configured services pass a bounded health probe. Ordinary program names and absolute paths keep their existing behavior and are never silently remapped.

Install and verify the Super tools

Caveman (Prodex-vetted 3.1.0 checkout):

export PRODEX_OPTIMIZERS_HOME="${PRODEX_OPTIMIZERS_HOME:-${XDG_DATA_HOME:-$HOME/.local/share}/prodex-optimizers}"
install -d "$PRODEX_OPTIMIZERS_HOME/caveman"
git clone --no-checkout https://github.com/JuliusBrussee/caveman \
  "$PRODEX_OPTIMIZERS_HOME/caveman/3.1.0"
git -C "$PRODEX_OPTIMIZERS_HOME/caveman/3.1.0" config core.autocrlf false
git -C "$PRODEX_OPTIMIZERS_HOME/caveman/3.1.0" checkout --detach \
  8af1f1b9b1346bca0722a1556f119b4e6675cc96
cat >"$PRODEX_OPTIMIZERS_HOME/caveman/3.1.0/prodex-tool.json" <<'JSON'
{
  "schema_version": 1,
  "id": "caveman",
  "version": "3.1.0",
  "source": "https://github.com/JuliusBrussee/caveman",
  "commit": "8af1f1b9b1346bca0722a1556f119b4e6675cc96",
  "tree_sha256": "2ca3549a88da2fc49b2abda20c90a1a8701f56833e2b19e60bdcede3ce68b316"
}
JSON

prodex capability super-doctor --json
prodex caveman --dry-run

The target directory must not already exist. Prodex validates the commit metadata and complete tree digest before activating Caveman. Caveman 3.1.0 documents telemetry as enabled by default for its CLI and agent hooks; its skill-only integration sends no telemetry. Use Caveman's documented caveman telemetry off or DO_NOT_TRACK=1 controls when running its CLI/plugin hooks if telemetry is not desired.

RTK (latest stable 0.51.0, externally managed):

brew install rtk
# or
rtk_dir="$(mktemp -d)"
trap 'rm -rf "$rtk_dir"' EXIT
curl -fsSLo "$rtk_dir/checksums.txt" \
  https://github.com/rtk-ai/rtk/releases/download/v0.51.0/checksums.txt
curl -fsSLo "$rtk_dir/rtk.tar.gz" \
  https://github.com/rtk-ai/rtk/releases/download/v0.51.0/rtk-x86_64-unknown-linux-musl.tar.gz
(cd "$rtk_dir" && grep '  rtk-x86_64-unknown-linux-musl.tar.gz$' checksums.txt | sha256sum --check)
tar -xzf "$rtk_dir/rtk.tar.gz" -C "$rtk_dir"
install -m 0755 "$rtk_dir/rtk" "$HOME/.local/bin/rtk"

rtk --version
rtk gain
prodex capability super-doctor

Use the matching archive and checksum row from the official v0.51.0 release on other architectures. Finish any process using the old executable before an explicit upgrade; Prodex never replaces RTK during startup.

Codebase Memory MCP (latest stable 0.11.0):

cbm_install_dir="$(mktemp -d)"
trap 'rm -rf "$cbm_install_dir"' EXIT
curl -fsSLo "$cbm_install_dir/install.sh" \
  https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/v0.11.0/install.sh
CBM_DOWNLOAD_URL=https://github.com/DeusData/codebase-memory-mcp/releases/download/v0.11.0 \
  bash "$cbm_install_dir/install.sh" --skip-config
codebase-memory-mcp daemon status || true
prodex capability super-doctor

Prodex accepts daemon-capable Codebase Memory MCP builds (0.9.1-rc.1 or newer, plus development builds) so parallel Codex sessions share one coordination daemon, indexing jobs, watchers, and cache. A separate lightweight stdio frontend per Codex process is expected; daemon status exits nonzero with daemon: not running before the first session starts it. Legacy builds that would duplicate heavy indexing work are skipped unless updated. Prodex leaves CBM_CACHE_DIR unset so parent and sub-agent sessions join the account-wide canonical daemon; an explicit user override is inherited unchanged and must stay consistent across every CBM client.

Playwright MCP (minimum supported 0.0.79; current latest-stable reference 0.0.83):

node --version
npx --version
npm install -g @playwright/mcp@latest
npx --no-install @playwright/mcp install-browser chrome
npx --no-install @playwright/mcp --version
prodex capability super-doctor
prodex playwright --dry-run

The browser install command above installs the Chrome channel used by Prodex's default MCP configuration. On Linux hosts missing browser system libraries, rerun it with --with-deps. Playwright starts through npx in headless, isolated mode, so concurrent Prodex terminals do not share browser login state. It prompts before tools marked as writes. Playwright MCP is not a security boundary.

Prodex preserves inherited [mcp_servers.playwright] entries. Add a custom entry to the base profile's config.toml to change flags, use a persistent/headed browser, or set enabled = false; the temporary Super overlay will not replace it.

Ponytail (Prodex-vetted 4.13.0 checkout):

export PRODEX_OPTIMIZERS_HOME="${PRODEX_OPTIMIZERS_HOME:-${XDG_DATA_HOME:-$HOME/.local/share}/prodex-optimizers}"
install -d "$PRODEX_OPTIMIZERS_HOME/ponytail"
git clone --no-checkout https://github.com/DietrichGebert/ponytail \
  "$PRODEX_OPTIMIZERS_HOME/ponytail/4.13.0"
git -C "$PRODEX_OPTIMIZERS_HOME/ponytail/4.13.0" config core.autocrlf false
git -C "$PRODEX_OPTIMIZERS_HOME/ponytail/4.13.0" checkout --detach \
  08e952d7a8057a57ce561ff1330d093fd92eec67
cat >"$PRODEX_OPTIMIZERS_HOME/ponytail/4.13.0/prodex-tool.json" <<'JSON'
{
  "schema_version": 1,
  "id": "ponytail",
  "version": "4.13.0",
  "source": "https://github.com/DietrichGebert/ponytail",
  "commit": "08e952d7a8057a57ce561ff1330d093fd92eec67",
  "tree_sha256": "4187a87a014975e268d1e6a0ea553382e7d53232a2f2ea741941c0b1c412dd2f"
}
JSON

prodex capability super-doctor --json
prodex ponytail --dry-run

The target directory must not already exist. Prodex validates the commit metadata and complete tree digest, then activates Ponytail only in the temporary overlay for that session. The base Codex profile remains unchanged.

Presidio English services:

docker run -d --name presidio-analyzer \
  --label com.prodex.presidio.managed=true \
  --label com.prodex.presidio.service=presidio-analyzer \
  -p 127.0.0.1:5002:3000 \
  ghcr.io/data-privacy-stack/presidio-analyzer:2.2.364@sha256:ae8f6f111ac2f04e3fec552f7f80edd0dcbfa2dd69ee1b9e030475be31669885
docker run -d --name presidio-anonymizer \
  --label com.prodex.presidio.managed=true \
  --label com.prodex.presidio.service=presidio-anonymizer \
  -p 127.0.0.1:5001:3000 \
  ghcr.io/data-privacy-stack/presidio-anonymizer:2.2.364@sha256:e567013893ebc80994e3799f6f55c86aa1f0b0fadb779571ab346f0ec45365c1
prodex presidio enable --language-mode fixed --languages en
prodex presidio doctor --json

The standard Analyzer image is English-only. Indonesian detection requires an Analyzer configured with Indonesian NLP models and recognizers before enabling --language-mode auto --languages en,id.

Verify the optional stack:

prodex capability super-doctor --presidio --strict
prodex s --no-presidio --dry-run
prodex s --presidio --dry-run

Quick start

Import your current Codex login

If your current Codex home is already logged in:

prodex profile import-current main

Create profiles from scratch

prodex login
prodex profile add second
prodex login second
prodex login --with-claude
prodex login --with-antigravity

Interactive prodex login asks for the login method before starting a browser. Choose ChatGPT browser login, device-code login, API-key login, Claude sign-in through Claude Code OAuth, or Antigravity CLI sign-in through agy auth login. The Codex-fronted Gemini bridge uses an API key; supported Vertex AI authentication belongs only to the native Gemini CLI. Antigravity login is global to the agy CLI and does not create a Prodex profile. For API-key profiles, you can also set an OpenAI-compatible backend URL:

printf '%s\n' "$OPENAI_API_KEY" | prodex login --with-api-key --base-url http://localhost:11434/v1

Migration note: endpoint and base-URL inputs are credential-free. Runtime and quota --base-url values, Super --url, CODEX_CHATGPT_BASE_URL, stored OpenAI-compatible profile URLs, Presidio Analyzer/Anonymizer URLs, and gateway webhook/HTTP telemetry endpoints must be absolute http or https URLs with a host and no userinfo, password, query, or fragment. Move credentials to the existing API-key, auth-token, bearer-token environment, or secret-file inputs. Legacy embedded-credential URLs now fail closed before a request, log, broker registry, or child launch plan is created instead of being normalized or partially stripped.

Check profiles and quota

prodex profile list
prodex quota --all
prodex session list

Start Codex through Prodex

prodex

Or run a one-off prompt:

prodex exec "review this repo"

Import a Claude Code account

prodex profile import claude
prodex profile import claude --name claude-main --activate

This imports the current Claude Code OAuth credentials from CLAUDE_CONFIG_DIR or ~/.claude into a Prodex-managed Anthropic profile. You can also use prodex login --with-claude to sign in through Claude Code directly.

Import a Copilot CLI account

prodex profile import copilot
prodex profile import copilot --name copilot-main --activate

When you import a Copilot profile, Prodex does not move the Copilot token into Prodex-managed storage. It only records the provider identity and API endpoint in its own metadata.

Import a Kiro CLI account

prodex profile import kiro
prodex profile import kiro --name kiro-main --activate

This reads the installed Kiro CLI state from the local auth database, snapshots the current Kiro auth payload into the managed Prodex profile, and refreshes a Kiro model catalog snapshot for later --provider kiro or --cli kiro launches. Override the detected CLI binary with PRODEX_KIRO_BIN when needed.

Daily command: prodex s

prodex s is the daily alias for prodex super. It enables:

• Caveman and Ponytail.
• RTK shell-output guidance.
• Codebase Memory MCP when installed.
• Playwright MCP when Node.js 18+ and npx are available.
• Smart Context Autopilot on Codex/provider-bridge paths.
• optional Presidio redaction.

prodex s
prodex s exec "review this repo"
prodex s doctor --strict
prodex s doctor --presidio --strict

Super launch details

Select or require tools explicitly when needed:

prodex super --tool caveman --require-tool rtk
prodex super --presidio

Interactive Super launches render a terminal Presidio opt-in screen. Pass --presidio or --no-presidio for non-interactive launches. Ordinary interactive prodex s still selects the main agent and provider, then reuses the remembered provider-scoped model and effort without reopening those pickers. Super is the explicit YOLO entrypoint: it launches Codex with approval and sandbox bypass, bypasses hook-trust confirmation, and trusts the current workspace for that invocation without changing persisted Codex configuration. Use prodex run for the normal approval and workspace-trust flow.

On Codex/provider-bridge paths, Smart Context preserves continuation metadata and critical signals while applying deterministic, validated context rewriting. Native opaque CLIs are outside that rewrite boundary. See docs/smart-context.md for its safety model and rollout controls.

Managed optimizer roots are checked in this order: PRODEX_OPTIMIZERS_HOME, $XDG_DATA_HOME/prodex-optimizers, then ~/.local/share/prodex-optimizers.

OpenAI profile diagnostic

prodex ping openai snapshots every configured eligible OpenAI profile and sends the minimal user text hello through the normal Prodex OpenAI/Codex request path, pinning each probe so one account cannot hide behind another. On an interactive terminal it opens a Ratatui Prodex Ping selector for the OpenAI model and reasoning effort before any probe is sent. Pass --model MODEL and/or --effort LEVEL to preselect either value. --json and non-interactive invocations never open the selector, so scripts and CI cannot hang waiting for terminal input. It reports each completed response or typed failure, continues after failures, and exits non-zero unless every requested profile succeeds. A valid completed model response is enough; the response does not need to say pong. Use prodex ping openai --profile NAME for one explicit profile or prodex ping openai --json for the aggregate machine-readable result. Human and JSON output include the requested reasoning effort. This report keeps requested and effective model fields separate; when Codex JSONL does not expose the effective model, it reports unavailable instead of guessing. It reports credential validation, first completed model-message latency, and terminal completion latency separately. This is an application-level provider diagnostic, not ICMP, DNS, TCP, TLS, or /models connectivity testing.

Sub-agents

prodex s can delegate bounded tasks to fresh child Prodex processes. Main and child providers remain separate; Presidio is inherited explicitly; recursion is disabled; and the official shell-free launcher enforces the active-child limit across separate launcher processes.

Sub-agent configuration, runtime enforcement, and MVP boundaries

prodex s --sub-agent --no-presidio
prodex s --sub-agent --sub-agent-max-concurrency default
prodex s --sub-agent --sub-agent-max-concurrency 8
prodex s --presidio --sub-agent --sub-agent-provider kiro \
  --sub-agent-model gpt-5.6-luna \
  --sub-agent-model-reasoning-effort max \
  --sub-agent-max-concurrency 16
prodex s 00000000-0000-7000-8000-000000000042 \
  --sub-agent --sub-agent-max-concurrency=23

Interactive fresh-launch order is Presidio, main-agent provider, required main provider configuration, sub-agent opt-in, then child provider, local URL when needed, model, catalog-backed or standard effort, and maximum active sub-agents. Answering no skips every child screen. Explicit parent or child values skip their screens; non-TTY launches never open a TUI.

The fresh main-agent picker uses the canonical provider registry and offers OpenAI, Anthropic Claude, GitHub Copilot, DeepSeek, Google Gemini, Kiro, and Prodex Local. --provider, --url, an explicit Codex model_provider override, or provider affinity on a resumed session intentionally skips or locks that picker. In particular, -c 'model_provider="openai"' explicitly selects OpenAI; omit it to choose interactively.

Fresh dry runs report the same remembered provider-scoped model and reasoning effort as a live launch. Explicit launch values still win, while resumed threads keep their own persisted settings.

The built-in concurrency default is 4. Presets are 4, 8, 16, and 32; custom values accept 1 through 64. This limits simultaneous child processes, not total tasks. When every exclusive lock slot is active, the launcher fails immediately and tells the main agent to wait for a child before retrying. Child exit, failed spawn, cancellation, and launcher termination release the OS-backed slot.

The complete instruction block is injected into the temporary effective AGENTS.override.md or AGENTS.md; SUB_AGENTS.md is diagnostic, not a lone @path reference. Child tasks travel through bounded private task files and an argument vector built from the current Prodex executable, so quotes, newlines, Unicode, shell metacharacters, and executable paths with spaces survive without shell evaluation. Parent UUIDs are never inherited.

OpenAI's canonical picker includes gpt-5.6-luna and its max effort metadata. All provider pickers scroll, merge the full offline catalog deterministically, and keep arbitrary nonempty custom model IDs unchanged.

This remains an MVP delegation surface, not a centralized semantic scheduler. Prodex does not claim automatic task decomposition, runtime-enforced file ownership, a global cancellation tree, distributed supervision, A2A child transport, remote model discovery, or automatic worktree allocation.

See Sub-agents for the exact CLI, dry-run, instruction, launcher, concurrency, resume-affinity, and isolation contracts.

Commands

The current CLI intentionally keeps only the supported profile, quota, session, diagnostic, run, Super, gateway, and ping surfaces. Retired top-level setup, capability, audit, context, cleanup, gui, dashboard, caveman, rtk, playwright, ponytail, presidio, redeem, claude, and standalone/public expose paths are not compatibility aliases and must not be resurrected. Optional tools are selected through Super's typed --tool and --require-tool flags.

Most used commands

prodex
prodex s
prodex exec "review this repo"
prodex ping openai
prodex quota --all
prodex profile list
prodex session list

Run Codex

prodex
prodex run
prodex run --profile main
prodex run --dry-run
prodex exec "review this repo"
prodex delete 00000000-0000-7000-8000-000000000042

Codex-owned TUI commands such as /usage, /goal, /import, and /delete stay upstream Codex behavior. Prodex preserves their request metadata through the proxy and does not add a competing command surface. If an active goal reaches Codex's usage_limited state while the TUI remains open, Prodex waits for another quota-ready OpenAI profile, gracefully relaunches the same session, releases its old affinity, and invokes /goal resume; --no-auto-rotate disables this recovery. The CLI form prodex delete <session> passes through to Codex and, after a successful delete, prunes matching Prodex session affinity metadata.

Run Super mode

prodex s
prodex s exec "review this repo"
prodex super
prodex super --profile main
prodex super --dry-run

Check quota

prodex quota
prodex quota --once
prodex quota --provider openai
prodex quota --all
prodex quota --all --once
prodex quota --all --auth no-auth --once
prodex quota --all --provider deepseek --once
prodex quota --all --provider local --base-url http://127.0.0.1:8131/v1 --once
prodex quota --all --provider agy --once
prodex status

Bare prodex quota opens the detailed live view across every profile, equivalent to prodex quota --all --detail. Provider and auth filters imply that default pool scope, so prodex quota --provider openai works without --all. Explicit --all without --detail retains the compact aggregate view; --profile and --raw retain their single-profile behavior.

prodex status opens a btop-inspired live terminal dashboard combining the active/runtime profile, 5-hour and weekly quota/reset/runway, historical token usage and cache efficiency, and aggregate Prodex process CPU, resident memory, disk I/O, and network socket queues. Press r to refresh immediately and q or Esc to exit. prodex status --once emits one snapshot for scripts. Resource counters use Linux /proc; non-Linux systems show those fields as unavailable while quota and token panels continue working.

The detailed live pool view (prodex quota or prodex quota --all --detail) accepts s to cycle sort modes and f to cycle the provider filter through all, openai, gemini, anthropic, copilot, kiro, deepseek, local, and agy. Add --provider openai, --provider gemini, --provider anthropic, --provider copilot, --provider kiro, --provider deepseek, --provider local, or --provider agy to start locked to a single provider. The table compacts to the current terminal width while preserving status and remaining-quota visibility; its live height keeps the sorted top rows and reports how many profiles are hidden.

Reset-credit redemption, desktop GUI, and other retired paths are intentionally not part of the 0.430.x CLI. Use the quota/status views and normal Codex/Super launches instead.

Sessions

prodex session list
prodex session current
prodex session current --parent-only

Update Prodex

prodex update --help
prodex update

prodex update checks the running version against the latest release before downloading anything. It is a no-op when already current, never automatically downgrades a newer local build, and downloads only a newer checksum-verified GitHub Release binary on macOS, Linux, and Windows. Existing npm or legacy Cargo installations migrate to the standalone path. Update notices state that both legacy installation channels are unsupported and direct them to this command.

More Codex command examples

prodex run 00000000-0000-7000-8000-000000000042
printf 'context from stdin' | prodex run exec "summarize this"

Unknown top-level Codex subcommands remain managed Codex launches.

For example:

prodex remote-control

is equivalent to:

prodex run remote-control

unless Prodex explicitly owns that command.

Codex runtime feature overrides and app-server compatibility (advanced)

Prodex keeps recent Codex runtime switches as Codex-owned behavior by rendering launch flags into codex -c ... overrides on prodex run, prodex caveman, and prodex super:

prodex run --web-search indexed
prodex run --web-search cached
prodex run --web-search live
prodex run --web-search disabled

prodex run --rollout-budget-tokens 100000
prodex run --rollout-budget-tokens 100000 --rollout-budget-reminders 75000,50000,25000

prodex run --current-time-reminder
prodex run --current-time-reminder --current-time-reminder-interval 2
prodex run --respect-system-proxy

Codex rust-v0.153.2 thread classification remains transparent passthrough. --thread-source accepts arbitrary upstream feature strings, applies to newly created and forked threads, and is never treated as a Prodex profile or routing signal:

prodex exec --thread-source automated_review "review this repository"
prodex run exec --thread-source automated_review "review this repository"
prodex caveman exec --thread-source automated_review "review this repository"
prodex s --no-presidio --no-sub-agent exec --thread-source automated_review "review this repository"
prodex exec fork THREAD_ID --thread-source automated_review "continue the review"

Prodex preserves the value and its position in Codex argv. It does not inject Codex's user default. Resume helpers omit the option so prodex exec resume THREAD_ID retains the thread's persisted source. Codex rust-v0.153.2 enables retained-image budgeting during remote compaction by default; use the normal Codex configuration surface when an explicit override is needed:

prodex -c features.compaction_image_budget=true exec "review this repository"
prodex run -c features.compaction_image_budget=true exec "review this repository"
prodex caveman -c features.compaction_image_budget=true exec "review this repository"
prodex s --no-presidio --no-sub-agent -c features.compaction_image_budget=true exec "review this repository"
prodex s --provider gemini -c features.compaction_image_budget=true exec "review this repository"
prodex -c features.compaction_image_budget=false exec "review this repository"

Generated Prodex provider/default overrides precede passthrough arguments. Explicit user -c arguments retain their order, so a later explicit override wins; unspecified state leaves the Codex 0.153.2 default enabled, while explicit true or false is preserved exactly. Codex owns retained-image accounting, image/label boundary atomicity, and the no-backfill rule. Prodex only preserves the configuration and /responses/compact image, label, audio, text, metadata, developer-message, and unknown JSON structures.

Detached memory traffic carries thread_source: "memory_consolidation" in x-codex-turn-metadata and the matching nested client_metadata entry. Prodex preserves both opaquely, including unknown metadata fields and pre-commit retries. This classification is metadata, not a Prodex affinity, selection, rotation, quota, or governance mode. In the explicit JSON-RPC broker, upstream threadSource is an optional free-form string on thread/start and thread/fork; thread/resume receives no generated source.

--web-search maps to Codex's top-level web_search = "disabled" | "cached" | "indexed" | "live" setting. In Super provider mode, an explicit --web-search is appended after the provider default, so it overrides the default bridge choice. Codex 0.148.0 allows compatible custom providers to use its standalone search endpoint; Prodex enables that capability automatically for the governed OpenAI-through-Prodex provider. Other custom providers must set model_providers.<id>.supports_standalone_web_search = true only when their endpoint implements that contract.

--rollout-budget-tokens enables Codex's [features.rollout_budget] config. If no reminder thresholds are supplied, Prodex provides valid 75%, 50%, and 25% remaining-token thresholds for the selected limit. Use --rollout-budget-sampling-weight and --rollout-budget-prefill-weight only when you need Codex's weighted accounting knobs.

--current-time-reminder enables Codex's [features.current_time_reminder] config. The default system clock source is owned by Codex. --current-time-clock-source external is intended for Codex app-server clients that implement the upstream currentTime/read request.

--respect-system-proxy enables Codex's [features.respect_system_proxy] config when the official upstream Codex supports it. Codex 0.148.0 routes auth, model, plugin, MCP, remote-exec, and Responses traffic through its shared proxy-aware HTTP client path so supported system proxy, PAC, WPAD, static proxy, and bypass decisions can be honored. --no-respect-system-proxy renders an explicit false override for sessions that need the upstream default direct/env-proxy behavior.

These runtime feature overrides require a Prodex build with mojo-core; builds without it reject the requested overrides during launch planning.

Codex multiAgentMode is an app-server/thread setting, not a normal TUI config.toml launch override. Prodex therefore does not invent a competing CLI config flag. Launch prodex app-server or prodex run app-server and pass upstream multiAgentMode values (none, explicitRequestOnly, or proactive) through the Codex app-server API.

prodex mcp-server, prodex app-server, and prodex exec-server preserve Codex command-server stdio and protocol arguments. Prodex performs runtime preparation silently: it selects the profile CODEX_HOME and routes model HTTP traffic through the same runtime proxy when rotation, pressure controls, or governance require it, without writing launch notices into the protocol stream. The JSON-RPC-aware app-server broker remains an explicit opt-in for validating the stdio frames themselves.

Codex 0.149 commands remain Codex-owned passthrough: prodex queue --thread THREAD --message TEXT reaches codex queue, and prodex agents opens Codex's shared task dashboard. In-session /cd, /pwd, and /cwd are likewise handled by Codex; Prodex consumes turn-time working-directory metadata instead of freezing the launch directory.

Codex plugin catalog commands are managed passthrough by default:

prodex plugin list
prodex plugin marketplace

Modes

Normal Codex — managed Codex launch

prodex
prodex run
prodex run --profile main
prodex exec "review this repo"

Optional tools — selected by Super

prodex doctor --install
prodex super --tool rtk --tool ponytail
prodex super --require-tool rtk --dry-run

Optional tools remain external and are activated only for the Super invocation. Use prodex doctor --install for bounded prerequisite checks; standalone optimizer commands are retired.

Super mode — daily optional-tool stack

prodex s
prodex s exec "review this repo"
prodex s --model gpt-5.3-codex
ANTHROPIC_API_KEY=... prodex s --provider anthropic --model claude-sonnet-4-6
prodex profile import copilot
prodex s --provider copilot --model gpt-5.3-codex
DEEPSEEK_API_KEY=... prodex s deepseek --model deepseek-v4-pro
prodex s gemini
prodex super
prodex super --profile main
prodex super --dry-run
prodex super 00000000-0000-7000-8000-000000000042

prodex s is the short alias for prodex super. --dry-run reports the resolved binary, provider, model, profile, proxy mode, and redacted arguments for both Codex-fronted and native --cli gemini, copilot, kiro, and agy launches without reading launch credentials or starting the child. Without --provider or --url, --model selects the standard Codex model. With either bridge option, it selects that provider's model.

This is my daily mode. It enables validated tools that are installed and launches Codex with Super's approval, sandbox, hook-trust, and workspace-trust bypasses for that invocation.

Playwright MCP is available to Super when Node.js 18+ and npx pass launch-time path validation. Use prodex doctor --install or --require-tool playwright for an offline probe. Codex Apps are disabled by default in Super; pass a later -c features.apps=true override when needed.

Super also enables Smart Context Autopilot on the Codex/provider-bridge path; native opaque CLIs are not automatically rewritten.

Provider launch examples and bridge behavior (advanced)

Use --provider anthropic when you want the Codex/Super front end with Anthropic upstream:

prodex login --with-claude
prodex s --provider anthropic --model claude-sonnet-4-6

If --api-key is omitted, Prodex uses the Anthropic profile created by prodex login --with-claude or prodex profile import claude. API-key mode still reads ANTHROPIC_API_KEY; ANTHROPIC_API_KEYS may contain multiple comma-, semicolon-, or newline-separated keys for round-robin request rotation and pre-commit retry on auth/quota/rate/temporary failures. This path injects a temporary prodex-anthropic Codex provider, exposes a local /v1/responses adapter to Codex, forwards to Anthropic's OpenAI-compatible chat API, and keeps quota preflight disabled. prodex quota --all --provider anthropic shows OAuth readiness for Anthropic profiles; set ANTHROPIC_ADMIN_KEY when you want Anthropic Admin rate-limit groups included.

Provider-backed Super launches consume supported provider API-key environment variables in the local Prodex proxy and remove them from the spawned Codex environment. Child MCP servers or tools that previously relied on inheriting those variables must configure their own credential source explicitly.

Use --provider copilot when you want the Codex/Super front end with GitHub Copilot upstream:

prodex profile import copilot
prodex s --provider copilot --model gpt-5.3-codex
prodex s --provider copilot --cli copilot --model gpt-5.3-codex

Without --api-key, Prodex uses imported Copilot CLI profiles, resolves the stored Copilot OAuth token before launch, refreshes the Copilot model catalog, can rotate fresh native Responses requests across multiple eligible profiles, and binds streaming response IDs back to the owning profile for continuations. GITHUB_COPILOT_API_KEY, GITHUB_COPILOT_API_KEYS, or --api-key can be used when you already have a usable Copilot API bearer token; plural keys may be comma-, semicolon-, or newline-separated and can rotate before commit on auth/quota/rate/temporary failures.

Add --cli copilot to keep the native GitHub Copilot CLI front end while routing its OpenAI Responses traffic through the same local Prodex adapter. Prodex configures Copilot's documented custom-provider environment for OpenAI Responses over HTTP, sends only a synthetic local key to the child, and keeps imported account or API-key credentials inside the proxy. PRODEX_COPILOT_BIN overrides the copilot executable.

Use --provider kiro or --cli kiro when you want the Codex/Super front end or native Kiro CLI with imported Kiro credentials:

prodex profile import kiro
prodex s --provider kiro --model claude-sonnet-4.5
prodex super --cli kiro --profile kiro-main

prodex profile import kiro reads the installed Kiro CLI auth database (~/.local/share/kiro-cli/data.sqlite3 or the Amazon Q compatibility location when present), snapshots the current credential payload into kiro_auth.json, and stores a model catalog snapshot for runtime routing. --provider kiro routes Codex through Prodex's local text-only Kiro ACP adapter; ACP owns its tool inventory, while Prodex forwards the prompt, model, and supported reasoning effort and rejects generation controls that ACP cannot enforce. Before Kiro starts, Prodex preserves the shared Codebase Memory MCP server but disables its check_index_coverage tool in Kiro's MCP config because that tool's top-level JSON Schema composition is rejected by Kiro/Bedrock; the remaining Codebase Memory tools and canonical account daemon stay shared. The Anthropic Messages compatibility route accepts its required token-limit field but cannot enforce that limit through ACP. --cli kiro launches the native Kiro CLI from the imported snapshot and forces its HTTP(S) transport through an authenticated loopback Prodex CONNECT tunnel; --no-proxy disables only an outer system proxy. Kiro's proprietary service payload remains end-to-end TLS encrypted, so native Kiro does not gain Smart Context, Presidio, response translation, or account rotation. Native Kiro rejects --presidio instead of silently ignoring it. Override binary discovery with PRODEX_KIRO_BIN when the installed launcher is not on PATH.

Use --provider deepseek when you want the Codex/Super front end with DeepSeek as the upstream model:

prodex s deepseek --model deepseek-v4-pro

If --api-key is omitted, Prodex reads DEEPSEEK_API_KEY; DEEPSEEK_API_KEYS may contain multiple comma-, semicolon-, or newline-separated keys for round-robin request rotation and pre-commit retry on auth/quota/rate/temporary failures. This path injects a temporary prodex-deepseek Codex provider, exposes a local /v1/responses adapter to Codex, forwards ordinary turns to DeepSeek's OpenAI-format chat API, and keeps quota preflight disabled. Prodex also injects a one-model Codex catalog for the selected DeepSeek model, so /model stays on that model and offers the DeepSeek-compatible high/xhigh effort choices. prodex quota --all --provider deepseek reads the same DEEPSEEK_API_KEY(S) environment and fetches DeepSeek /user/balance. Available Super optimizer tools remain local Prodex overlay additions around Codex. /responses/compact is handled by a bounded deterministic local summary when the selected provider has no semantic compact implementation.

The DeepSeek catalog includes deepseek-v4-pro and deepseek-v4-flash; deepseek-chat and deepseek-reasoner remain compatibility aliases for existing configs.

DeepSeek compatibility is translated, not native Responses. Prodex maps Codex text turns, function/MCP/local shell/apply-patch style tools, tool_choice, reasoning effort, JSON object mode, stop sequences, token limits (max_output_tokens, max_tokens, and max_completion_tokens), sampling, logprobs, streaming usage, and DeepSeek cache hit/miss usage into compatible shapes. Request metadata, client_metadata, prompt_cache_key, and prompt_cache_retention are preserved in local response metadata instead of being forwarded upstream. JSON schema requests are degraded to DeepSeek json_object mode and marked in response metadata because DeepSeek's OpenAI Chat route does not provide native JSON Schema enforcement. Web search is explicit and configurable: [deepseek] web_search_mode = "auto" uses DeepSeek's documented Anthropic-compatible /anthropic/v1/messages route only when a web-search tool is present, translates function and web-search tools, authenticates with x-api-key, and maps search calls, sources, usage, text, and streaming events back to Responses. "anthropic" explicitly selects the same native search route, "off" rejects web-search tools, and "openai_chat" retains best-effort web_search_options forwarding with retry fallback. Gateway/profileless launches can use PRODEX_DEEPSEEK_WEB_SEARCH_MODE. DeepSeek function tools are bounded by the upstream 128-tool limit; Prodex must fail rather than silently truncate if that ceiling is reached, translated duplicate tool names are rejected instead of being dropped, and named tool_choice must target a translated function tool. Tool declarations must also be translatable: function/custom tools require names, namespace tools require a named namespace with named function entries, MCP toolsets that declare inventories require a server name plus allowed/enabled tools, and DeepSeek function names must use only letters, numbers, underscores, or dashes within the upstream 64-character limit. When DeepSeek thinking is enabled, Prodex omits explicit tool_choice for upstream compatibility and records the omitted value in DeepSeek response metadata. Reasoning content, refusal text, annotations, logprobs, and finish reasons are preserved in DeepSeek response metadata. Reasoning summaries are not advertised for DeepSeek, and reasoning.summary fails clearly. Image, document, audio, and video message content is rejected because this adapter targets DeepSeek's text/tool surfaces. Deprecated frequency_penalty and presence_penalty are not mapped because current DeepSeek docs mark them unsupported/ignored. parallel_tool_calls=true is compatible with DeepSeek's one-or-more tool-call behavior, but parallel_tool_calls=false is rejected because the OpenAI Chat route has no equivalent control to enforce it. Responses-only controls that DeepSeek cannot honor, including non-empty include, store=false, background responses, truncation=auto, per-message cache_control, text.verbosity, legacy functions/function_call, logit_bias, and max_tool_calls, fail clearly instead of being dropped.

DeepSeek troubleshooting: if JSON mode appears to stream whitespace or stalls, make sure the prompt explicitly asks for JSON; Prodex adds a minimal adapter instruction when JSON mode is requested, but model-facing task instructions still matter. A DeepSeek 400 in openai_chat web-search mode means the best-effort forwarding shape was not accepted; return to auto, use off, or remove the web-search tool. Strict tool failures usually mean a schema keyword outside DeepSeek's beta strict subset, a missing required property, or an object schema that cannot be made additionalProperties = false.

DeepSeek compatibility matrix:

Strict DeepSeek function calling is opt-in because DeepSeek documents it on the beta endpoint. Add this to the selected Codex profile config:

[deepseek]
strict_tools = true
beta_base_url = "https://api.deepseek.com/beta"

Gateway/profileless launches can use PRODEX_DEEPSEEK_STRICT_TOOLS=1 and optional PRODEX_DEEPSEEK_BETA_BASE_URL. When enabled, Prodex routes rewritten DeepSeek /responses traffic through the beta base URL, sets every translated function tool to strict: true, forces strict object schemas to require all properties with additionalProperties = false, and rejects unsupported strict schema keywords or types clearly. DeepSeek beta chat prefix completion and FIM /completions use separate protocols outside this adapter; prefix, prompt, and suffix completion-style requests fail fast instead of being rewritten as chat.

Use --provider gemini when you want the Codex/Super front end with Gemini upstream:

GEMINI_API_KEY=example-key prodex s gemini
prodex s gemini --cli gemini
prodex s gemini --cli agy
GEMINI_API_KEY=example-key prodex s gemini --model gemini-2.5-pro

Prodex's third-party Google Gemini OAuth login and Code Assist credential reuse are unsupported and disabled. Existing OAuth profiles remain parseable but fail with guidance to migrate the Codex bridge to a Gemini API key, or to use Vertex AI only through the native Gemini CLI; Prodex never silently falls back. With --api-key, GEMINI_API_KEY(S), or GOOGLE_API_KEY(S), Prodex converts Codex Responses requests to Chat Completions and sends them through Google's documented OpenAI-compatible endpoint. Streaming, function calls, continuations, and supported Gemini reasoning values are converted back into Codex Responses semantics. Plural key variables may rotate before commit on auth, quota, rate, or temporary failures. The default model is auto; checked-in and configured Gemini model catalogs remain available without a live discovery request.

prodex s gemini --cli gemini launches the native Google Gemini CLI instead of Codex and leaves supported authentication, including Vertex AI, and transport to that CLI or environment. Prodex does not inject the removed OAuth client. Set PRODEX_GEMINI_BIN to override the gemini executable.

prodex s gemini --cli agy launches the native Antigravity CLI with --dangerously-skip-permissions so tool permission prompts are auto-approved. Antigravity CLI owns its authentication through the system keyring/Google Sign-In and does not expose an endpoint or token override, so Prodex account auto-rotation and Presidio proxying are not available on this path. It works without a Prodex profile and rejects --presidio instead of silently ignoring it. Set PRODEX_AGY_BIN to override the agy executable.

The Gemini bridge also maps native Gemini computerUse, code execution, grounding/citation/URL-context metadata, generated images, video metadata, multimodal file inputs, log-probability metadata, tool-use and cached-token accounting, safety metadata, and Gemini finish reasons into Codex-compatible request, response, and SSE shapes. Citations are emitted as a separate completed output item after Gemini supplies a finish reason. Assistant followups retain native Gemini code, media, video, cache, and thought-signature parts without replaying citation display text as model history.

@path and bounded read_many_files context honor default binary/build/dependency exclusions plus ordered root .gitignore, .geminiignore, and custom ignore files, including later negation overrides. Large tool outputs are masked before replaying them into Gemini history and are written to PRODEX_GEMINI_TOOL_OUTPUT_DIR or the OS temp directory; set PRODEX_GEMINI_TOOL_OUTPUT_MASK_THRESHOLD=0 to disable this guard. Codex /responses/compact requests use a tool-free unary semantic-compaction turn and return Codex replacement history. If semantic compaction fails before commit, Prodex preserves HTTP 200 continuity with a bounded lossy local summary and marks it with x-prodex-compact-mode: local-fallback, provider, degraded, and bounded reason headers. Semantic success uses x-prodex-compact-mode: semantic. Prometheus output counts both modes and bounded fallback reasons. Invalid pre-commit Gemini streams are retried with bounded backoff before model fallback.

Gemini CLI compatibility helpers accept inline gemini_memory / gemini_policy / gemini_session request metadata, file-based gemini_*_file imports, and PRODEX_GEMINI_SESSION_FILE or PRODEX_GEMINI_CHECKPOINT_FILE import paths. Gemini memory is loaded by default from ~/.gemini/GEMINI.md, ancestor GEMINI.md files, .gemini/memory/MEMORY.md, and .gemini/memory/INBOX.md; set PRODEX_GEMINI_DISABLE_MEMORY=1, PRODEX_GEMINI_DISABLE_CONTEXT_FILES=1, or request metadata gemini_load_memory=false to opt out. Host-file imports are local-CLI-only: gateway and in-process gateway requests cannot read request-selected or implicit Gemini files from the service host. Gemini settings are read in CLI precedence order from system defaults, global, ancestor project, cwd-local, and system override settings, honoring GEMINI_CLI_HOME, GEMINI_CLI_SYSTEM_SETTINGS_PATH, and GEMINI_CLI_SYSTEM_DEFAULTS_PATH; extension manifests and extension policy TOML files are also read when present to apply Gemini tool allow/exclude, hard command-specific tool-call blocking, and defaultApprovalMode behavior.

Before Codex launches, the Gemini provider projects Gemini CLI settings and extension surfaces into the active CODEX_HOME: system/global/project mcpServers and extension mcpServers become generated Codex [mcp_servers.gemini_*] entries with settings taking precedence over extension servers of the same Gemini name; system/global/project and extension command hooks are merged into hooks.json for Codex /hooks review; ~/.gemini/commands, project .gemini/commands, and extension commands/*.toml become Codex custom prompts with Gemini command aliases preserved where possible; extension skills/*/SKILL.md are copied into generated Codex skill folders under .agents/skills; and extension agents/*.md become generated Codex custom agents under agents/*.toml. Generated files use exact Prodex ownership markers, normalized name collisions receive deterministic numeric suffixes, and rejected existing user files are preserved. Built-in /prompts:gemini-refresh, /prompts:gemini-memory-show, /prompts:gemini-memory-refresh, /prompts:gemini-memory-inbox, /prompts:gemini-remember, /prompts:gemini-checkpoint-create, /prompts:gemini-checkpoint-restore, /prompts:gemini-checkpoint-export, and /prompts:gemini-rewind cover reload/admin, memory, and checkpoint workflows. Generated helper scripts in CODEX_HOME/bin include prodex-gemini-refresh, prodex-gemini-checkpoint-create, and prodex-gemini-checkpoint-restore; workspace checkpoints include staged, unstaged, and untracked non-ignored files while excluding the checkpoint directory itself. Set PRODEX_GEMINI_EXTENSIONS=none or an allow-list of extension names to control extension loading, PRODEX_GEMINI_EXTENSION_DIRS to add extension roots, or PRODEX_GEMINI_DISABLE_CLI_COMPAT=1 to skip the launch-time Codex surface projection.

Gemini Live realtime websocket translation remains available for anonymous/personal compatible callers, authenticated gateway virtual keys, and credentialed adapter tests, mapping Codex audio, transcript, text, function-call, function-result, interruption, cancellation, housekeeping, and turn-completion events to and from Gemini BidiGenerateContent. One governed Gemini auth/profile is selected before upgrade and remains fixed for the bounded session; virtual-key usage is reserved, accounted per text frame, and reconciled when the session ends. Codex 0.140.0 removed the upstream TUI voice controls, so this bridge should not be treated as a normal Codex TUI voice feature. PRODEX_GEMINI_LIVE_MODEL overrides the default Live model, while PRODEX_GEMINI_LIVE_URL is available for a custom or test Live endpoint. prodex doctor --runtime recognizes provider bridge and Gemini markers such as local_rewrite_provider_model_fallback, local_rewrite_gemini_quota_rotate, local_rewrite_gemini_invalid_stream_retry, and local_rewrite_gemini_live_error.

Run cargo test --locked -q -p prodex-provider-core gemini_provider_core_ && cargo test --locked -q -p prodex-app --lib gemini_ after changing Gemini request, response, SSE, semantic compact, exact-output, tool-schema, or Live translation. Run PRODEX_LIVE_GEMINI=1 node scripts/ci/gemini-live-smoke.mjs for a credentialed end-to-end Gemini adapter smoke request; set PRODEX_BIN or PRODEX_LIVE_GEMINI_MODEL to override the binary or model. Add PRODEX_LIVE_GEMINI_EXTENDED=1 for command-output-only, file edit, apply_patch, reference-repo clone/inspection, optional-tool update discipline, semantic compact, and explicit exec resume checks. Add PRODEX_LIVE_GEMINI_MCP=1 and/or PRODEX_LIVE_GEMINI_MULTIMODAL=1 when the local environment should also exercise MCP and image-input paths.

Presidio internals (advanced)

Super renders a Ratatui opt-in screen before launch. Empty input or n keeps Presidio disabled; use --presidio or --no-presidio for non-interactive launches.

The runtime reads Analyzer, Anonymizer, language, and fail_mode settings from presidio.toml:

enabled = true
analyzer_url = "http://localhost:5002"
anonymizer_url = "http://localhost:5001"
language_mode = "auto"
languages = ["en", "id"]
fail_mode = "open"
timeout_ms = 10000
max_response_bytes = 4194304
max_concurrency = 8

Enterprise modes additionally require private/on-prem endpoints or exact trusted_hosts entries. Redirects and environment proxy settings are ignored so inspected content cannot leave the approved endpoint boundary.

With the default loopback URLs, Prodex auto-starts only the pinned, labeled containers shown above; set PRODEX_PRESIDIO_AUTO_START=0 to disable this. It refuses to start an existing predictable-name container whose ownership label, image digest, or loopback port binding differs; recreate older latest-based containers explicitly.

The standard Presidio Analyzer image is English-only. Indonesian detection requires an Analyzer with Indonesian models and recognizers. Presidio quality depends on that service configuration.

Claude Code — managed Claude Code state

prodex claude -- -p "summarize this repo"
prodex claude caveman
prodex claude caveman -- -p "summarize this repo briefly"
prodex claude --profile second caveman -- -p "review the latest diff briefly"
prodex claude --profile second -- -p --output-format json "show the latest diff"

prodex claude uses the normal Claude Code flow while keeping state under Prodex-managed configuration.

prodex claude caveman enables Caveman for that session while keeping state under the Prodex-managed CLAUDE_CONFIG_DIR, not the global ~/.claude.

prodex claude is only supported with the default OpenAI/Codex provider.

Harness modes

A harness mode is model-facing request policy for a local provider bridge. Native remains the default.

Harness modes, examples, and evaluated-policy boundaries

Prodex supports native, minimal, and the explicit evaluation-backed evaluated mode. Omitting --harness selects native, so existing launches remain unchanged.

prodex s --provider anthropic --harness native
prodex s --provider anthropic --model claude-sonnet-4-6 --harness evaluated
prodex s deepseek --harness minimal
prodex s gemini --model gemini-3.1-pro-preview --harness evaluated
prodex super --url http://127.0.0.1:8131 --harness minimal
prodex gateway --provider gemini --harness native

Exact mode behavior and Evaluated policy boundaries

Native preserves existing request bytes, headers, responses, and streams. Minimal only prepends a versioned Prodex instruction to eligible canonical /v1/responses inference requests. Evaluated matches the already-selected provider/model against a versioned catalog; it never chooses or reroutes a provider/model, and unknown pairs are no-ops at the harness layer.

Current Evaluated policies translate supported Anthropic Responses traffic through native /v1/messages and reversibly map Gemini's canonical exec_command tool to run_shell_command, restoring the canonical name in typed buffered and SSE tool calls. Ambiguous tool aliases and unsupported/lossy Anthropic shapes fail closed instead of silently changing semantics.

The harness is fixed for the bridge or gateway lifetime. It does not change account affinity, pre-commit rotation, retries, approvals, tools, or streaming commit semantics. Harness selection never creates a second agent runtime: Codex still owns its agent loop, tools, sandbox, approvals, skills, hooks, reconnect behavior, and TUI.

See docs/harness-modes.md for exact scope, diagnostics, evaluation catalog behavior, and non-goals.

Profiles

Common profile commands

prodex profile list
prodex profile add second
prodex profile import-current main
prodex login second
prodex use --profile main
prodex logout --profile main

More profile commands

prodex profile import copilot
prodex profile import kiro
prodex profile export
prodex profile remove second
prodex profile remove --all

Password-protected exports now use the version-2 Argon2id envelope. Imports stay compatible with existing version-1 PBKDF2 bundles.

Imports require a current-user-owned private bundle below trusted directories. For an existing Unix bundle, correct its ownership and run chmod 600 backup.json, or re-export it. On Windows, the bundle must have a private current-user owner/DACL.

Local model support

Run Super mode against a local server

Prodex can launch Super mode against a local OpenAI-compatible server:

prodex super --url http://127.0.0.1:8131

You can use this with a local server such as llama-server.

By default, Prodex:

• injects a temporary prodex-local Codex provider
• appends /v1 when the URL has no path
• disables non-function native tools that local servers commonly reject
• advertises a conservative 16k local context window
• skips quota/proxy routing for that launch

Check local server reachability with:

prodex quota --all --provider local --base-url http://127.0.0.1:8131/v1 --once

The default local model id is:

unsloth/qwen3.5-35b-a3b

Override it with --model:

prodex super --url http://127.0.0.1:8131 --model local/qwen

Use --context-window and --auto-compact-token-limit if your local server is configured with a larger context window.

See LOCAL.md for self-hosted model setup and testing.

Utilities and diagnostics

Utility commands

prodex status
prodex status --once
prodex info
prodex log
prodex log stream
prodex log upstream
prodex doctor --install
prodex doctor --runtime
prodex doctor --bundle ./prodex-doctor.json --redacted
prodex doctor --repair-session-index
prodex doctor --install
prodex doctor --runtime --json

For full policy keys, environment overrides, and runtime log path resolution, see docs/runtime-policy.md.

When a support case appears to come from upstream Codex itself, run prodex run doctor --json (or codex doctor --json) in the same environment as Prodex. Codex 0.149.0 also diagnoses endpoint protection, network/proxy connectivity, desktop state, and update connectivity; those checks remain separate from Prodex's runtime-proxy doctor.

Advanced behavior

Shared Codex history

Managed Prodex profiles keep account credentials isolated per profile, but Codex-owned shared state uses the native Codex home by default.

On Unix-like systems, this is usually:

~/.codex

In practice, profile history.jsonl, sessions, archived_sessions, config.toml, managed_config.toml, environments.toml, plugins, skills, app-server plugin state, memory-extension state, remote-control enrollment, and Codex runtime SQLite files such as state_*, goals_*, logs_*, and memories_* link to the same Codex home that direct Codex uses. OpenAI/Codex profiles also share .credentials.json; Anthropic Claude profiles keep their Claude OAuth .credentials.json local to the profile.

Codex 0.140.0 defaults CLI auth credentials to the file store, so managed Prodex profiles continue to keep auth.json isolated per profile, including OpenAI, API-key, and Bedrock API-key auth JSON. MCP OAuth defaults to Codex auto; when it falls back to the file store, .credentials.json is shared with direct Codex for OpenAI/Codex profiles. Claude OAuth imports and logins retain .credentials.json as a private regular file in each Anthropic profile. An ambiguous legacy link from an Anthropic profile to shared Codex state is removed without copying or deleting its target; sign in or import again to establish fresh profile-local Claude credentials. OS keyring-backed MCP OAuth credentials remain Codex/OS-owned and are not part of Prodex profile export bundles.

Prodex-owned runtime broker capability secrets default to files and can use the native OS keyring instead:

[secrets]
backend = "keyring"
keyring_service = "prodex"

PRODEX_SECRET_BACKEND and PRODEX_SECRET_KEYRING_SERVICE override policy. The first keyring read migrates an existing broker capability file into an opaque, path-derived keyring account and removes the legacy file only after the keyring write succeeds. prodex info and prodex doctor --runtime --json report the effective backend. Codex-managed profile auth.json, Codex/MCP credentials, and production projected SecretRef files retain their existing ownership and are not moved into this keyring.

Prodex strips dynamic-loader injection variables such as LD_PRELOAD, LD_AUDIT, LD_LIBRARY_PATH, and DYLD_* from Codex child processes by default. Set PRODEX_ALLOW_UNSAFE_CHILD_ENV=1 only when intentionally debugging a custom local runtime environment.

Codex cloud-managed config bundle caches are identity/account scoped and remain profile-local. System-level Codex requirements and managed config files remain owned by upstream Codex and the operating system.

Prodex does not synthesize legacy Codex [profiles.*] behavior. File-based Codex profile config selected by --profile stays in shared Codex state, while Prodex-owned account selection remains in Prodex profile metadata.

Prodex also leaves packaged Codex runtime resources alone, including Codex 0.136.0 and newer bundled zsh runtime helpers under the Codex package layout. Do not set zsh_path through Prodex unless you are intentionally debugging direct Codex config.

This matches direct Codex behavior: logging out or switching accounts does not hide chat history.

Older Prodex state from $PRODEX_HOME/.codex is merged into the native Codex home on the next managed-profile launch.

Set PRODEX_SHARED_CODEX_HOME only when you intentionally want a different shared Codex root.

Bedrock and custom providers

Auto-rotate and quota checks apply to supported OpenAI/Codex profiles. prodex quota also supports Antigravity CLI quota snapshots, Anthropic OAuth profiles, imported Copilot accounts, DeepSeek API-key balances, local OpenAI-compatible health snapshots, supported Gemini API-key configurations, and configured custom providers. Disabled Gemini OAuth profiles receive migration guidance.

If a profile's config.toml sets model_provider to a non-OpenAI backend such as amazon-bedrock or Codex 0.148's built-in amazon-bedrock-runtime, prodex run and prodex caveman launch Codex directly without quota preflight or the local auto-rotate proxy. Prodex does not rewrite either provider ID.

Codex 0.149.0 raises the maximum context override for openai.gpt-5.6-sol, openai.gpt-5.6-terra, and openai.gpt-5.6-luna to 872,000 tokens and refreshes expired AWS credentials for Bedrock. Prodex preserves those model-specific limits and leaves AWS refresh, model IDs, reasoning effort, and service-tier behavior owned by the direct Codex launch.

Bedrock quota, credentials, regions, and provider errors are handled by Codex and the upstream provider, not by Prodex.

prodex quota shows the configured provider metadata for those profiles instead of failing the view.

Proxy behavior

Prodex respects system and environment proxy settings for upstream OpenAI quota, auth, and runtime HTTP by default, including:

HTTP_PROXY
HTTPS_PROXY
NO_PROXY

Runtime WebSocket upstream connections also honor HTTPS_PROXY and https_proxy via HTTP CONNECT and respect NO_PROXY and no_proxy.

The local Codex-to-Prodex broker connection always receives NO_PROXY entries for:

127.0.0.1
localhost
::1

This prevents a user proxy from intercepting the local runtime proxy.

Use --no-proxy on prodex run, prodex caveman, prodex super, or prodex claude only when you explicitly want Prodex upstream requests to bypass proxy settings.

Contributor notes

This repository is a Cargo workspace.

The binary crate stays at the root, while reusable leaf crates live under crates/ to reduce rebuild scope when those components change.

Contributor testing guidance lives in docs/testing.md, including the fast/serial split and runtime parallel-safety assumptions.

Documentation

• Documentation index — complete map of maintained documentation
• QUICKSTART.md — first successful launch
• LOCAL.md — self-hosted local model setup and testing
• docs/state-model.md — state ownership and persistence model
• docs/runtime-policy.md — runtime policy keys, environment overrides, and runtime log path resolution
• docs/deployment.md — Docker Compose scaffold for the standalone gateway
• docs/harness-modes.md — Harness Mode semantics, evaluated policies, scope, and diagnostics
• docs/sub-agents.md — Super sub-agent CLI, child command, and isolation contract
• docs/testing.md — contributor testing guidance

Support

If you find prodex useful and want to support its development, you can donate here: