DOCSEARCHbyAlgolia
Submit Docs

CodexManager Documentation

repository·main·Indexed 25 days ago

https://github.com/qxcnm/codex-manager

A management suite and gateway for Codex accounts featuring a desktop interface (Tauri) and a local OpenAI-compatible API. It provides tools for account pool management, usage tracking, platform key rotation, and a local gateway for CLI tools and agents. Key features include support for multiple routing strategies (ordered, balanced), zstd request compression, and a plugin/skill system via Rhai integration.

Tokens
75.3K
Snippets
124
Records
465
Agent score
73%

What's inside CodexManager

  1. Overview of Service version components

    main

    The Service version of CodexManager consists of three main components:

    • codexmanager-service: Provides a local OpenAI-compatible gateway.
    • codexmanager-web: Provides the browser-based management page and hosts /api/runtime and /api/rpc proxies.
    • codexmanager-start: A one-click launcher that starts both the service and web components.

  2. Overview of CodexManager Features

    main

    CodexManager is a local desktop and service-process account pool manager and gateway relay designed for Codex workflows. Key capabilities include:

    • Account Pool Management: Organize accounts using groups, tags, ordering, and notes. Supports ban recognition and filtering.
    • Batch Operations: Import/export accounts via multi-file or recursive folder imports.
    • Usage Tracking: Monitor usage across 5-hour and 7-day windows, including specialized buckets like Code Review / Spark.
    • Platform Key Management: Create, disable, or delete keys. Administrators can bind keys to specific account groups and rotate them within authorized pools.
    • Aggregate API: Set up and test third-party relay upstreams with priority ordering.
    • Plugin & Skill System: Supports built-in, private, and custom plugins via Rhai integration. Skills can be installed from GitHub, skills.sh search results, or ZIP files.
    • Local Gateway: Provides an OpenAI-compatible endpoint for Codex CLI, Gemini CLI, Claude Code, and other tools. Supports custom bind/listen settings, upstream proxies, and SSE keepalive (enabled by default).
    • Image Generation: Automatically injects the image_generation tool for /v1/responses and supports /v1/images/generations and /v1/images/edits using gpt-image-2 as the default model.

  3. Overview of CodexManager

    main
    CodexManager is a local desktop application and service process designed to manage Codex accounts, usage, and platform keys. It acts as a unified account pool manager and provides local gateway capabilities to serve as an OpenAI-compatible entry point for tools like Codex CLI, Gemini CLI, Claude Code, and other third-party applications.

  4. Understand the HTTP Bridge module structure

    main

    The http_bridge module in codexmanager-service is organized into several specialized sub-modules to handle different aspects of gateway observability and response processing. The main orchestration logic resides in delivery.rs, while other concerns are delegated as follows:

    • delivery.rs: Handles HTTP response delivery, upstream branching, streaming orchestration, failover/deactivation handling, and compact response delivery wrappers.
    • body_conversion.rs: Manages compatibility JSON/SSE body conversion and adapter content-type decisions (e.g., Anthropic, OpenAI, Gemini, and Chat Completions).
    • compact_errors.rs: Handles compact/non-success body classification and normalized error message construction (including Cloudflare challenge detection).
    • images.rs: Provides helper payloads for image generation responses.
    • metadata.rs: Manages upstream response metadata extraction (e.g., request-id, CF-Ray), debug metadata, and stream diagnostics logging.
    • manual_chunked.rs: Handles manual HTTP/1.1 chunked response writing.

  5. Understand the System Internal Interface Layers

    main

    The system exposes interfaces through four distinct layers depending on the client type and communication method. Use the appropriate layer based on your integration target:

    • Tauri Commands: The primary entry point for desktop applications. Parameter names follow the Rust #[tauri::command] definitions.
    • JSON-RPC Methods: Internal methods exposed by the service process, typically accessed via POST /rpc.
    • Direct Local Commands: Local commands available exclusively to the desktop client that do not require RPC communication.
    • HTTP Routes: Server-side interfaces exposed directly by the service or web processes.

  6. Understand CodexManager operating modes

    main

    CodexManager operates in two distinct modes depending on your deployment needs:

    1. Desktop mode: A full application experience using a Tauri Desktop shell combined with a local service process. This is ideal for end-users wanting a GUI.
    2. Service Mode: A headless or web-based deployment consisting of a standalone service and a Web UI. This can be run on servers, via Docker, or in environments without a desktop GUI.

  7. Core Features of CodexManager

    main

    Account Pool Management

    • Grouping, tagging, sorting, and remarks.
    • Ban identification and filtering.
    • Batch import/export (supports multi-file import and recursive folder import for JSON).

    Usage & Authentication

    • Displays usage windows (Standard 5h + 7d, 7d single window, and official add-on windows like Code Review/Spark).
    • Supports chatgpt.com browser authorization and Device Code login.

    Platform Key & Model Management

    • Platform Keys: Generate random or custom fixed keys. Supports binding to specific account groups and filtering by account plans.
    • Model Management: Uses 'Model Directory V2' as the source of truth. Supports builtin/custom models, tiered pricing, and instructions policy.

    Gateway & API Capabilities

    • Local Gateway: Provides a unified OpenAI-compatible entry point for Codex CLI, Gemini CLI, Claude Code, etc.
    • Gemini Support: Forwards requests to /v1/responses and supports SSE, tools, MCP, and skills.
    • Image Generation: Automatically injects image_generation tool into /v1/responses (default model: gpt-image-2). Supports /v1/images/generations and /v1/images/edits.
    • Aggregate API: Manages third-party upstream providers with connectivity testing.

  8. Verify changes before submission

    main

    Before submitting a Pull Request, perform the following verification steps based on your scope of changes:

    Frontend changes:

    pnpm -C apps run test
pnpm -C apps run build
pnpm -C apps run test:ui

    Rust/Server-side changes:

    cargo test --workspace

    Desktop/Packaging changes: Run a dry run of the rebuild script:

    pwsh -NoLogo -NoProfile -File scripts/rebuild.ps1 -DryRun

    Protocol Adaptation changes: If you modify crates/service/src/gateway/, crates/service/src/http/, or crates/service/src/lib.rs, you must perform regression testing on:

    • /v1/chat/completions
    • /v1/responses
    • Streaming and non-streaming returns
    • tool_calls and tool-related paths
    pnpm -C apps run test
cargo test --workspace

  10. Run CodexManager from source

    main

    To run a local development build with an embedded UI, use the provided shell script. This script builds the frontend using pnpm and then compiles the service, web, and start components.

    ./scripts/run-service-app.sh

    Flags:

    • --debug: Use a debug Rust build for faster iteration.
    • --clean-dist: Remove apps/out before building.
    • --no-open: Do not open the browser automatically.

    Note: You can override the embedded UI by setting the CODEXMANAGER_WEB_ROOT environment variable to a specific static directory.