# CodexManager: a local account pool and gateway for the Codex CLI

> CodexManager stores multiple Codex CLI accounts in a local SQLite database, exposes them through a desktop app or a service process, and forwards requests through a local gateway on port 48760. The README is candid about which platforms the author actually verifies.

**qxcnm/Codex-Manager** — 一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。

- Repository: https://github.com/qxcnm/Codex-Manager
- Stars: 3,000 · Forks: 403
- Language: Rust
- License: MIT
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/qxcnm-codex-manager

## The problem CodexManager addresses: one CLI, many accounts

The Codex CLI authenticates as a single account. If you hold more than one, switching means editing credentials by hand, and running two sessions in parallel means keeping two sets of files straight. CodexManager treats accounts as a pool: it stores them locally, lets you pick one, and puts a gateway in front of the CLI so requests are forwarded rather than sent directly upstream. The README describes the product as a local desktop and service-process account pool manager for Codex.

The audience is narrow and identifiable. It is people who already use the Codex CLI and have accumulated accounts, plus anyone running it on a home server or NAS who wants the pool reachable from more than one machine. The disclaimer states the project is for learning and development purposes, that the author does not provide or distribute accounts, API keys or proxy services, and that users must follow the terms of the platforms involved. That is not boilerplate here: the tool's whole function is account handling, so the boundary matters.

## How the gateway and account pool are put together

The repository is a Cargo workspace. Cargo.toml lists six members: crates/core, crates/rusqlite, crates/service, crates/storage-seaorm, crates/start and crates/web. The Tauri desktop application sits in apps/src-tauri and is explicitly excluded from the workspace, which tells you the desktop shell and the headless service are built separately even though they share the same crates.

Two storage crates exist side by side, one named for rusqlite and one for SeaORM. The docker-compose file points the service at a single SQLite file, /data/codexmanager.db, so the practical deployment is one database on disk, not a client-server store. The service listens on port 48760 and the embedded web interface on port 48761, both configurable through environment variables. The gateway can print trace and error output to stdout, which the Compose file enables by default.

The workspace patches tokio-tungstenite and tungstenite to forks under the openai-oss-forks organisation, pinned to specific revisions. That is a real signal about the transport: the tool depends on WebSocket behaviour that upstream crates did not provide at the time, so the build pulls modified versions. Anyone auditing dependencies should treat those two patches as the first thing to look at, because a pinned fork revision does not move with upstream fixes.

The service also accepts a request gate wait timeout, commented in the Compose file as a mitigation for same key, path and model head-of-line waits. In other words, when several requests target the same account and model, the gateway serialises them, and the timeout bounds how long a request waits at that gate before giving up. The README does not document what happens to a request that exceeds the timeout, so treat that setting as a knob to test rather than a documented behaviour.

## Installing CodexManager with Docker Compose

The repository ships a docker-compose.yml that pulls a prebuilt image from an Aliyun registry. Create a directory, save the file below as docker-compose.yml, and run the two commands that follow. The service container runs as root because, as the file's own comment explains, NAS Docker panels often create bind-mounted folders with host-only ownership and expose no chown or chmod controls.

```yaml
services:
  codexmanager:
    container_name: codexmanager
    image: registry.cn-hangzhou.aliyuncs.com/kilimiao/codex-manager:latest
    pull_policy: always
    restart: unless-stopped
    user: "0:0"
    environment:
      CODEXMANAGER_SERVICE_ADDR: 0.0.0.0:48760
      CODEXMANAGER_WEB_ADDR: 0.0.0.0:48761
      CODEXMANAGER_WEB_NO_OPEN: "1"
      CODEXMANAGER_DB_PATH: /data/codexmanager.db
      CODEXMANAGER_RPC_TOKEN_FILE: /data/codexmanager.rpc-token
    volumes:
      - ./data:/data
    ports:
      - "48761:48761"
```

Then start it and watch the logs:

```bash
docker compose up -d
docker compose logs -f codexmanager
```

The web interface answers on port 48761. Note that only that port is published in the Compose file; the gateway on 48760 stays inside the container network, so a client on another host cannot reach it without adding a mapping. The RPC token is written to /data/codexmanager.rpc-token, which is what a local client uses to authenticate against the service. The README does not document the token format or a rotation procedure.

Building from source is possible because the workspace is standard Cargo, but the README does not give a build recipe, and the two patched WebSocket crates mean the build reaches out to GitHub for pinned revisions. If your environment blocks that, the build fails before it compiles anything of the project's own.

## Where CodexManager is the wrong tool

The README is unusually direct about verification. It states that the author has no Mac and no comparable hardware, that only the Windows desktop build is guaranteed usable, and that other platforms should be tested thoroughly before issues are filed. If you are deploying on macOS or Linux, you are the tester, not a supported user. That is a limitation of evidence, not of code, but it changes what you can expect when something breaks.

The README also states the product was built largely with AI assistance, at roughly 98 percent Codex and 2 percent Gemini. That is a provenance fact, not a quality judgement, but it pairs with the author's own note that there was not enough environment to verify every package. Combine the two and the honest reading is: the Windows desktop path is the one with a human behind it, and everything else is best-effort.

Rollback is undocumented. The README does not describe how to downgrade from v0.6.0, whether the SQLite schema migrates forward only, or what happens if you point an older binary at a database written by a newer one. If you pin the image tag rather than using latest, you keep the option open; if you follow the Compose file as written, pull_policy: always means every restart can move you forward. Back up /data/codexmanager.db before you upgrade, because that file is the entire state.

Finally, the disclaimer explicitly says not to use the project to bypass rate limits or service restrictions. If your reason for pooling accounts is to get around per-account limits, the project's own documentation tells you that is outside its intended use.

## How CodexManager differs from a plain OpenAI-compatible proxy

A generic API relay such as one of the services sponsoring this README forwards requests from many users to upstream providers and bills for it. It is a network service you point your client at, and the account handling happens on someone else's infrastructure. CodexManager inverts that: the accounts are yours, they live in a SQLite file on your disk, and the gateway runs on your machine or your NAS. Nothing leaves your host except the upstream calls the CLI would have made anyway.

The trade-off is operational. A hosted relay gives you someone to page when it breaks, and it works from any machine without setup. CodexManager gives you a local process, a token file, a database to back up, and a Compose file whose default runs the container as root. You own the failure modes. For a single developer with two or three accounts on one workstation, the local model is simpler and keeps credentials under your control. For a team that needs shared quota accounting and an SLA, a hosted relay is the better fit and CodexManager is not trying to be one.

## Maintenance, licensing and what an upgrade actually costs

The last push to the default branch was on 2026-09-23, and the most recent release, v0.6.0, was published on 2026-09-05. The repository is not archived. Releases have been frequent: v0.5.5 on 2026-08-23, v0.5.6 on 2026-09-02, then v0.6.0 three days later. That cadence cuts both ways. You get fixes quickly, and you also get version churn in a tool that holds your credentials in one file.

The licence is MIT, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of what the licence file says about obligations; it says nothing about the accounts you put in the pool, and the disclaimer already places that responsibility on you. Nothing here is legal advice, and the interaction between an MIT-licensed client and the terms of service of the upstream platform is not something the repository resolves.

Upgrade cost is dominated by two things. First, the patched WebSocket crates: when upstream tokio-tungstenite or tungstenite change, the pinned fork revisions do not follow, so the project has to rebase them. Second, the database. Because the Compose file uses pull_policy: always, an unattended restart can land you on a new schema with no documented way back. Pinning the image to a specific tag is the cheap insurance, and copying /data/codexmanager.db before each upgrade is the cheaper one.

## Conclusion

Adopt CodexManager if you run several Codex CLI accounts on one machine and want them behind a single local endpoint, and if you are on Windows, the only platform the README claims to verify. Do not adopt it if you need a documented rollback path, a signed macOS build, or a maintainer who can test every package; the README states the author has no Mac and limited hardware. Verify first that your Codex CLI version matches what the gateway expects, that /data is writable under your chosen UID, and that your use complies with the OpenAI terms the disclaimer names.

## FAQ

### Does CodexManager work on macOS or Linux?

The README states that only the Windows desktop build is guaranteed usable, and that the author lacks a Mac and comparable hardware to verify other platforms. Linux is served through the Docker Compose file, but the README asks users to test thoroughly before filing issues.

### What ports does CodexManager open?

The docker-compose.yml sets CODEXMANAGER_SERVICE_ADDR to 0.0.0.0:48760 for the gateway and CODEXMANAGER_WEB_ADDR to 0.0.0.0:48761 for the web interface. Only port 48761 is published in the Compose file.

### Where does CodexManager store its data?

The Compose environment sets CODEXMANAGER_DB_PATH to /data/codexmanager.db and writes the RPC token to /data/codexmanager.rpc-token. The ./data directory is bind-mounted into the container, so that folder holds the entire state.

### What licence does CodexManager use?

The repository is MIT licensed, which allows commercial and private use, modification and redistribution as long as the copyright and permission notices are kept. The README's disclaimer separately states that the author does not provide accounts, API keys or proxy services.

## Sources

- [Issues](https://github.com/qxcnm/Codex-Manager/issues)
- [License: MIT](https://github.com/qxcnm/Codex-Manager/blob/main/LICENSE)
- [qxcnm/Codex-Manager on GitHub](https://github.com/qxcnm/Codex-Manager)
- [README](https://github.com/qxcnm/Codex-Manager/blob/main/README.md)
- [Releases](https://github.com/qxcnm/Codex-Manager/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qxcnm-codex-manager