# Quick Start
One OpenAI profile pool. Two CLIs.
Use `prodex` for Codex CLI. Use `prodex claude` for Claude Code. Both commands run on top of the same OpenAI-backed Prodex profile pool.
## Requirements
- An OpenAI account, plus at least one logged-in Prodex profile
- Codex CLI if you want to use `prodex`
- Claude Code (`claude`) if you want to use `prodex claude`
If you install `@christiandoxa/prodex` from npm, the Codex runtime dependency is installed for you. Claude Code is still a separate CLI and should already be installed when you use `prodex claude`.
## Install
Install from npm:
```bash
npm install -g @christiandoxa/prodex
```
Or install from [crates.io](https://crates.io/crates/prodex):
```bash
cargo install prodex
```
## Update
Check your installed version first:
```bash
prodex --version
```
The current local version in this repo is `0.3.0`:
```bash
npm install -g @christiandoxa/prodex@0.3.0
cargo install prodex --force --version 0.3.0
```
Dependency status in this repo:
- The npm runtime dependency is tracked from the workspace package manifest for `@openai/codex`
- Run `cargo update` whenever dependency metadata changes so the published lockfile stays in sync
- Versioned install snippets in this guide and `README.md` are synced from `Cargo.toml`
If you want to switch from a Cargo-installed binary to npm:
```bash
cargo uninstall prodex
npm install -g @christiandoxa/prodex
```
## 1. Create your first profile
If your shared Codex home already contains a login:
```bash
prodex profile import-current main
```
Or create a profile through the normal Codex login flow:
```bash
prodex login
prodex login --device-auth
```
If you want a fixed profile name first:
```bash
prodex profile add second
prodex login --profile second
```
## 2. Inspect the pool
```bash
prodex profile list
prodex profile export
prodex quota --all
prodex info
```
`prodex quota --all` refreshes live by default. Use `--once` when you want a single snapshot:
```bash
prodex quota --all --once
```
Backup or move profiles:
```bash
prodex profile export
prodex profile export backup.json
prodex profile import backup.json
```
`prodex profile export` exports all configured profiles by default and asks whether the bundle should use optional password protection.
## 3. Run Codex CLI with `prodex`
`prodex` without a subcommand is shorthand for `prodex run`.
```bash
prodex
prodex run
prodex run --profile second
prodex run 019c9e3d-45a0-7ad0-a6ee-b194ac2d44f9
prodex exec "review this repo"
Use this path when you want Codex CLI itself to be the front end. Prodex keeps transport behavior close to direct Codex while handling profile selection, quota preflight, continuation affinity, and safe pre-commit rotation.
## 4. Run Claude Code with `prodex claude`
```bash
prodex claude -- -p "summarize this repo"
prodex claude --profile second -- -p --output-format json "show the latest diff"
```
Use this path when you want Claude Code to be the front end while Prodex still routes requests through your OpenAI-backed profile pool.
What changes on this path:
- Claude Code talks to a local Anthropic-compatible Prodex proxy
- managed profiles link `CLAUDE_CONFIG_DIR` into shared Prodex Claude state
- the first managed Claude launch imports your existing `~/.claude` and `~/.claude.json` when present
- the initial Claude model follows the shared Codex `config.toml` model when available
- Claude's `opus`, `sonnet`, and `haiku` entries are pinned to representative GPT models
- Prodex seeds Claude's picker with the Prodex GPT catalog via Claude-native placeholder model IDs
- Claude `max` effort maps to OpenAI `xhigh` when the selected GPT model supports it
- supported picker entries use Claude-native placeholders so Claude can expose native effort controls
Useful overrides:
```bash
PRODEX_CLAUDE_BIN=/path/to/claude prodex claude -- -p "hello"
PRODEX_CLAUDE_MODEL=gpt-5.4 prodex claude -- -p "hello"
PRODEX_CLAUDE_MODEL=gpt-5.2 PRODEX_CLAUDE_REASONING_EFFORT=xhigh prodex claude -- -p "hello"
```
## 5. Switch profiles explicitly
```bash
prodex use --profile main
prodex current
```
## 6. Debug the runtime
```bash
prodex cleanup
prodex doctor
prodex audit
prodex audit --tail 20 --component profile
prodex doctor --quota
prodex doctor --runtime
prodex doctor --runtime --json
```
If a runtime session looks stalled, inspect the latest proxy log:
```bash
prodex doctor --runtime
tail -n 200 "$(cat /tmp/prodex-runtime-latest.path)"
```
That pointer path stays in `/tmp` only when the runtime log directory is still on the default setting. If you override the log directory, use `prodex doctor --runtime --json` to find the active `log_path` and live broker metrics.
Use `prodex cleanup` when you want to clear stale local runtime logs, temp login homes, dead broker artifacts, and old orphaned managed profile homes that are no longer tracked.
Use `prodex audit` when you want to inspect the local append-only audit log. It supports `--tail`, `--component`, `--action`, `--outcome`, and `--json`.
For managed local deployments, you can pin runtime logging and proxy tuning in `~/.prodex/policy.toml`:
```toml
version = 1
[runtime]
log_format = "json"
log_dir = "runtime-logs"
[secrets]
backend = "file"
# keyring_service = "prodex"
[runtime_proxy]
worker_count = 16
active_request_limit = 128
responses_active_limit = 96
```
Environment variables still override `policy.toml`.
## Enterprise Notes
Prodex is still a local-first tool, even after the current enterprise hardening work.
Current hardening includes:
- a secret-management abstraction for `auth.json` and export bundles, plus global secret-backend selection through policy or environment
- a stable broker metrics JSON endpoint at `/__prodex/runtime/metrics`
- a Prometheus broker metrics endpoint at `/__prodex/runtime/metrics/prometheus`
- `prodex info` and `prodex doctor --runtime --json` surfacing live metrics targets and the selected secret backend
- enterprise audit logging for profile, rotation, and admin events, separate from runtime session output and discoverable through `prodex info` or `prodex doctor --runtime --json`
- `prodex audit` for browsing the local append-only audit log without touching runtime proxy behavior
Known gaps today:
- local `auth.json` remains the compatibility source of truth for current Codex flows even when a non-file backend is selected
- no keychain, Vault, or KMS-backed secret storage implementation yet
- audit logs follow the resolved runtime log directory by default, or `PRODEX_AUDIT_LOG_DIR` when set
- no RBAC, SSO, SCIM, or central admin plane
- runtime observability is still centered on local logs plus `doctor --runtime --json`
- the profile pool is still owned per host, not by a shared service
- runtime-store modularization is still underway, so the state layer should be treated as an internal boundary rather than a stable integration surface
Useful markers:
- `runtime_proxy_queue_overloaded`
- `runtime_proxy_active_limit_reached`
- `runtime_proxy_lane_limit_reached`
- `profile_inflight_saturated`
- `profile_retry_backoff`
- `profile_transport_backoff`
- `profile_health`
- `precommit_budget_exhausted`
- `first_upstream_chunk`
- `first_local_chunk`
- `stream_read_error`