prodex

GitHub release downloads

prodex는 할당량 인식(quota-aware) 프로필 라우팅 기능을 갖춘 다중 계정, 다중 공급자 Codex 래퍼입니다.

하나의 명령줄에서 여러 Codex 계정과 지원되는 공급자 백엔드를 사용할 수 있습니다. OpenAI/Codex 프로필은 할당량 인식을 통해 라우팅되며, 사용 가능한 여러 프로필이 있을 경우 자동으로 순환(auto-rotate)됩니다. 또한, 공급자 어댑터 덕분에 prodex s를 사용하여 Gemini, Anthropic, Copilot, Kiro, DeepSeek 및 로컬 OpenAI 호환 서버에 대해 Codex 프런트엔드를 실행할 수 있습니다.

목차

• Why prodex
• Requirements
• Supported providers
• Installation
• Optional tools
• Quick start
• 데일리 명령어: prodex s
• Commands
• Modes
• Sub-agents
• Harness modes
• Profiles
• Local model support
• Utilities and diagnostics
• Advanced behavior
• Documentation
• Support

Why prodex

다음과 같은 경우 prodex를 사용하세요:

• 하나의 CLI에서 여러 Codex 계정을 사용하고 싶을 때
• 할당량이 소진되면 다른 적격 계정으로 순환(rotate)하고 싶을 때
• 프런트엔드를 변경하지 않고 비(非)OpenAI 공급자에 대해 Codex/Super를 실행하고 싶을 때
• 프로필 auth.json의 계정 자격 증명을 분리하여 유지하고 싶을 때
• 세션을 생성한 프로필에 연결된 상태로 유지하고 싶을 때
• 지원되는 래퍼를 통해 Codex 및 Super 모드를 실행하고 싶을 때

만약 단 하나의 Codex 계정만 사용하며 할당량 순환이 필요하지 않다면, prodex가 필요하지 않을 가능성이 높습니다.

Requirements

OpenAI/Codex 할당량 인식 라우팅을 위해서는 최소한 하나 이상의 로그인된 Prodex 프로필이 필요합니다. 로컬 --url 실행과 일부 공급자 API 키를 이용한 실행은 영구 저장되는 프로필 없이도 실행될 수 있습니다.

지원되는 공급자(Supported providers)

Prodex는 두 가지 공급자 경로를 지원합니다:

• 프로필 기반 라우팅 (Profile-backed routing): Prodex가 선택, 로테이션 및 검사할 수 있는 영구 저장된 프로필입니다. 이는 공급자 API가 허용하는 경우에 해당됩니다.
• 런타임 공급자 실행 (Runtime provider launch): prodex s gemini, prodex s deepseek, 또는 prodex s --provider ...를 사용하여 해당 세션 동안 임시 공급자 브리지를 통해 Codex를 시작합니다.

prodex gateway는 비-Codex 클라이언트를 위해 공급자 브리지를 독립적인 OpenAI 호환 서비스로 노출합니다:

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

이 게이트웨이는 선택된 업스트림(upstream)이 지원하는 경우, /v1/responses, /v1/chat/completions, /v1/embeddings, /v1/images/*, /v1/audio/*, /v1/batches, /v1/rerank, /v1/a2a, /v1/messages, 그리고 /v1/models 엔드포인트에서 서비스를 제공합니다. 응답에 x-prodex-call-id를 추가하고, request 및 response 단계 모두에 대해 로컬 요청 상세 정보와 gateway_spend 이벤트를 런타임 로그에 기록하며, 이러한 이벤트를 범용적(generic), OTel, Datadog 또는 Langfuse 형태의 페이로드로 JSONL이나 HTTP를 통해 내보낼 수 있습니다. 모델 별칭/폴백 체인(model aliases/fallback chains)을 위해 카탈로그 기반 정책 라우팅 전략(fallback, round-robin, least-busy, lowest-cost, lowest-latency, rpm, tpm, first)을 지원하며, 영구적으로 기록되는 요청/사용량 및 모델/예산/RPM/TPM 제한과 함께 정적 가상 키(static virtual keys)를 강제할 수 있습니다. 파일(file), SQLite, Postgres 또는 Redis 기반의 게이트웨이 관리/사용량/원장(ledger)/SCIM 상태를 지원하며, 호출 전후 및 출력물에 대해 키워드/모델, 로컬 PII(개인 식별 정보) 마스킹, Presidio, 그리고 외부 웹훅 가드레일(guardrails)을 적용할 수 있습니다. Admin-token, 신뢰 프록시 SSO(Single Sign-On), 또는 OIDC/JWT 베어러 요청을 통해 사용량을 조회하고, 생성된 토큰 키를 만들고, 관리되는 키를 순환/비활성화/업데이트/삭제하며, SCIM 호환 /v1/prodex/gateway/scim/v2/Users를 통해 SSO 사용자를 프로비저닝(provision)할 수 있습니다. 또한 /v1/prodex/gateway/keys 및 /v1/prodex/gateway/usage에서 사용량을 검사하고, /v1/prodex/gateway/ledger에서 응답 상태/출력 토큰 조정과 함께 최근 청구 원장 기록을 읽고, /v1/prodex/gateway/ledger/summary에서 집계된 청구 총액을 읽으며, /v1/prodex/gateway/ledger.csv와 /v1/prodex/gateway/ledger/summary.csv에서 청구 CSV를 내보낼 수 있습니다. Prometheus 텍스트 메트릭은 /v1/prodex/gateway/metrics에서 스크래핑하고, /v1/prodex/gateway/providers에서 제공자 어댑터 계약(provider adapter contracts)을 검사하거나 prodex gateway providers --json으로 오프라인에서 검사할 수 있습니다. 활성 관측 가능성 및 가드레일 구성을 /v1/prodex/gateway/observability와 /v1/prodex/gateway/guardrails에서 검사하고, 체크인된 게이트웨이 OpenAPI 문서는 /v1/prodex/gateway/openapi.json에서 가져올 수 있으며, 내장형 게이트웨이를 열 수 있습니다.

관리자 대시보드는 /v1/prodex/gateway/admin에서 접근할 수 있으며, 이 문서는 게이트웨어가 문서화한 라우트(routes)를 설명하는 것이지, 완전한 업스트림 OpenAPI 또는 프로바이더 의미론을 다루는 것은 아닙니다. 또한 /v1/a2a는 로컬 prodex super --sub-agent 실행과는 별개입니다. 정책/환경 기반 키는 읽기 전용(read-only) 상태를 유지하며, SCIM 사용자는 SSO/OIDC 폴백을 위해 테넌트(tenant)/팀(team)/프로젝트(project)/사용자(user)/예산(budget) 범위를 가질 수 있습니다. 관리자가 관리하는 키와 SCIM 사용자 변경 사항은 prodex audit 이벤트를 발생시키고, 추가적인 관리 평면 토큰(admin-plane tokens)은 admin 또는 읽기 전용의 viewer가 될 수 있으며, 선택적으로 가상 키 접두사(virtual-key prefix)에 테넌트/팀/프로젝트/사용자/예산 범위를 추가할 수 있습니다. 기본값 설정은 policy.toml 파일의 [gateway] 섹션에서 수행하고, 프로바이더 카탈로그 편집은 node scripts/catalog/provider-catalog-check.mjs로 검증합니다. 생성된 프로바이더 매트릭스는 docs/provider-capabilities.md에 있습니다.

게이트웨이는 [gateway.request_constraints] 하에서 선택적 모델 인식 요청 제약 조건(model-aware request constraints)을 강제할 수 있습니다. 호환성 기본값은 강제를 비활성화하고 크기가 큰 출력 요청을 변경하지 않습니다. 관리자/뷰어 주체(principals)는 대시보드의 라우트 워크벤치(Route Workbench) 또는 POST /v1/prodex/gateway/routes/explain를 사용하여 업스트림 트래픽을 보내거나 할당량, 결제, 친화성(affinity), 서킷(circuit), 승인(admission), 또는 영구 실행 상태(persisted runtime state)를 변경하지 않고 동일한 경계가 지정된 플래너 추적(bounded planner trace)을 검사할 수 있습니다. 설명 페이로드와 프롬프트 내용은 기록되거나 저장되지 않습니다.

게이트웨이 가상 키 실시간 WebSocket 세션은 32 KiB의 제한된 프레임, 5분의 세션 상한선, 사전 토큰 예약(upfront token reservation), 프레임별 계정 처리(per-frame accounting), 그리고 최종 사용량 조정(terminal usage reconciliation)을 사용합니다. 관리되는 프로바이더/프로필은 업그레이드 전에 고정되며, 정책 거부 또는 토큰 소진 시 세션이 회전 없이 종료됩니다.

거버넌스 정책/분류/프로바이더 레지스트리 생명 주기 엔드포인트(lifecycle endpoints)는 SQLite 또는 PostgreSQL 상태를 필요로 합니다. 파일 및 Redis는 문서화된 관리/사용 표면(admin/usage surfaces)을 위한 호환성 백엔드로 남아 있으며, 거버넌스 생명 주기 작업에 대해서는 501 governance_policy_operation_unsupported를 반환합니다. 은행 모드(bank mode)는 PostgreSQL을 필요로 합니다.

Enterprise OTLP export endpoints는 OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 또는 OTEL_EXPORTER_OTLP_ENDPOINT에서 절대 경로의 http:// 또는 https:// URL이어야 하며, 공백, 사용자 정보(userinfo), 쿼리 문자열(query strings), 또는 프래그먼트가 포함되어서는 안 됩니다. 컬렉터 자격 증명은 OTEL_EXPORTER_OTLP_HEADERS에 넣어주세요. 또한, prodex-control-plane plan-http-control-plane 요청 파일은 최상위 principal 필드와 비(非)자격 증명 HTTP 헤더를 사용해야 합니다. 왜냐하면 Authorization 헤더는 거부되기 때문입니다.

[gateway.adaptive_routing]은 선택적(opt-in)입니다. enabled = true로 설정할 경우, Prodex는 모델별 제한된 결과/지연 시간 창을 유지하며 신선한 사전 커밋 별칭 폴백만 재정렬할 수 있습니다. shadow_mode = true는 선택 변경 없이 추천 내용을 기록합니다. 하드 연속성 친화도(Hard continuation affinity), 할당량 필터링(quota filtering), 그리고 미스트림 회전 불가 경계(no-mid-stream-rotation boundary)는 여전히 권위적입니다. 선택적인 exploration_rate는 요청별로 결정론적이며 0.0부터 1.0 사이로 제한됩니다.

JavaScript 클라이언트는 /v1/responses와 게이트웨이 키, 사용량, 청구 원장(billing ledger), 메트릭 및 OpenAPI 관리 호출을 위해 @christiandoxa/prodex-gateway-sdk를 사용할 수 있습니다.

자동 로테이트 프록시는 의도적으로 보수적입니다. 요청 또는 스트림이 커밋되기 직전에만 로테이션을 수행하며, previous_response_id, 턴 상태(turn-state), 세션 친화성(session affinity)을 유지하고, 스트리밍 도중에 로테이션하지 않습니다. 새로운 작업을 위해 명시적인 계정 할당량 실패는 해당 프로필을 제외하고 모든 남아 있는 적격 프로필을 거쳐 최종 업스트림 할당량 응답이 노출되기 전에 계속됩니다. 커밋 전 전송 소진(Pre-commit transport exhaustion)은 로컬 503 service_unavailable를 반환하기 전에 동일한 유한 풀을 시도합니다. 일반적인 429 응답, 하드 친화성 지속(hard-affinity continuations), 그리고 커밋된 출력물은 오류를 숨기기 위해서만 재재생되지 않습니다. 명시적인 임시 속도 제한은 경계가 있는(bounded) Retry-After 백오프를 사용하며, 공급자 전체의 과부하(provider-wide overload)는 별도의 재시도 가능한 상태로 유지되며 할당량 소진으로 보고되지 않습니다. OpenAI 용량은 모델 인지적입니다: 백엔드가 Luna Reserve를 명시적으로 승인할 때, 일반 Luna 할당량은 차단되고 매핑된 gpt-reserve 버킷이 준비되면, Prodex는 요청된 모델을 gpt-5.6-luna로 유지하지만 숨겨진 Reserve 경로를 업스트림으로 전송합니다. Sol, Terra, 재사용된 WebSocket 세션 및 지속(continuations)은 절대 Reserve로 전환되지 않습니다. Reserve 활성화는 리셋 크레딧을 사용하지 않습니다. 일반 및 Reserve Luna 용량이 모두 사용할 수 없는 경우, Prodex는 다른 공개 OpenAI 모델로 대체하는 대신 로테이션하거나 업스트림 할당량 응답을 노출합니다. 기본적으로 Prodex는 리셋 크레딧을 자동 사용하지 않습니다. --auto-redeem으로 OpenAI/Codex 런타임 경로를 시작하면, Prodex는 주간 사용 한도 창(weekly usage-limit window)이 소진되고, 할당량 풀의 다른 어떤 프로필도 주간 할당량이 남아있지 않고, 주간 리셋이 이미 임박하지 않은 경우에만 얻은 리셋 크레딧을 하나 사용할 수 있으며, 그 후 로테이션하기 전에 동일한 프로필을 재시도할 수 있습니다. 여전히 단순히 중요하거나 얇은 창(critical/thin windows) 또는 5시간 전용 소진에 대해서는 사용하지 않습니다.

또한 prodex redeem <profile>을 실행하여 지정된 OpenAI/Codex 프로필에 대한 명시적 리셋 크레딧 소비 요청을 하나 보낼 수 있습니다. 상위 백엔드에서 해당 수동 요청이 적용되는지, nothing-to-reset을 보고하는지, 아니면 크레딧 없음/이미 사용됨을 보고할지 결정합니다. OpenAI/Codex는 기본 할당량 인식 풀로 유지됩니다. Antigravity CLI, 가져온 Copilot 프로필, Anthropic OAuth 프로필, DeepSeek API 키, 로컬 OpenAI 호환 URL, 그리고 Bedrock/커스텀 Codex 제공업체들은 prodex quota 뷰를 가집니다. Anthropic, DeepSeek, API 키 Gemini, API 키 Copilot, Antigravity CLI, 로컬 URL, 그리고 Bedrock/커스텀 Codex 제공업체는 OpenAI 할당량 사전 검사를 건너뜁니다.

런타임 프록시 설계 계약:

• Prodex는 범용 LLM SDK가 아닌 범위가 지정된(scoped) Codex 게이트웨이로 유지되어야 합니다.
• 프로필 선택은 정책, prodex info, prodex doctor, 그리고 런타임 로그를 통해 가시적이어야 합니다.
• 사전 커밋 재시도 및 폴백 경로는 요청별로 제한을 유지해야 합니다.
• 런타임 핫 패스는 광범위한 디스크 읽기, 할당량 조사(quota probes), 또는 블로킹 상태 저장소를 피해야 합니다.
• 할당량, 예산, 전송, 그리고 로컬 압력 신호는 별도로 분류되어야 합니다.
• 선택, 승인(admission), 친화도(affinity), 백오프(backoff), 그리고 첫 청크 이벤트는 런타임 로그에 구조화되어야 합니다.
• Codex 의미론을 변경하지 않는 한 상위 HTTP/WebSocket 연결 재사용이 유지되어야 합니다.
• 비밀 정보는 프로필별로 격리되고 진단 과정에서 마스킹(redacted)됩니다. Prodex가 소유한 변형(mutations)은 로컬 감사 이벤트를 발생시키며; 불변의 규정 준수 보존, 비상 증거(break-glass evidence), SIEM 내구성, 그리고 재해 복구는 배포/거버넌스 책임으로 남습니다. 로컬 감사 이벤트와 Super/sub-agent 오버레이가 이러한 배포 제어를 입증하지는 않습니다.

설치

이 명령어들은 최신 공개 릴리스를 설치합니다.

macOS 또는 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