Skip to main content

codexLB-up

codexLB-up is a maintained fork of Soju06/codex-lb, a load balancer and OpenAI-compatible proxy for ChatGPT accounts with a usage dashboard. This distribution includes audited security and compatibility fixes. It is published independently by Lok3rn3t.

Install and run

Requires Python 3.13 or newer. Run the release in an isolated environment with uv:

uvx --from "codexLB-up==1.25.0" codex-lb

Or install it inside a dedicated Python virtual environment:

python -m pip install "codexLB-up==1.25.0"
codex-lb --help
codex-lb

The distribution name is codexLB-up; its commands remain codex-lb and codex-lb-db. Use a separate environment from the upstream codex-lb package, because both distributions provide the same Python modules and commands. The wheel and source distribution include the compiled dashboard.

Docker

Published images support Linux amd64 and arm64 and include the native egress worker. Stable releases publish exact version, major/minor, and latest tags.

docker volume create codex-lb-data
docker network inspect codex-lb-net >/dev/null 2>&1 || docker network create codex-lb-net
docker run -d --name codex-lb --restart unless-stopped \
  --network codex-lb-net \
  -p 2455:2455 -p 1455:1455 \
  -v codex-lb-data:/var/lib/codex-lb \
  ghcr.io/lok3rn3t/codexlb-up:1.25.0

Open the dashboard at http://localhost:2455. The volume stores the database, encryption key, and account data. Docker Compose examples are available in the repository.

Helm

The chart uses the fork image by default and is published to GHCR:

helm pull oci://ghcr.io/lok3rn3t/charts/codex-lb --version 1.25.0

Follow the chart installation guide for bundled or external PostgreSQL and cluster configuration.

Upgrading from the original beta.9

The supported source is upstream codex-lb==1.25.0b9, whose Docker tag is ghcr.io/soju06/codex-lb:1.25.0-beta.9. The target is ghcr.io/lok3rn3t/codexlb-up:1.25.0. Keep the existing database engine, data mounts, encryption key, environment, published ports, and Docker networks. There is no need to export and re-import accounts or create another database.

This is an application upgrade with existing schema updates, not a PostgreSQL major-version upgrade or a SQLite-to-PostgreSQL conversion. All 261 beta.9 migration files are retained unchanged. Three inherited revisions add SCIM storage, remove the retired subscription-overflow storage, and merge their revision heads. The old application must stop before those updates run; it cannot safely use the upgraded schema. Retired overflow fields are not retained in the live schema, so keep the backup if you used that withdrawn feature.

Single container with SQLite

These Bash commands cover the original upstream Docker quick start: a container named codex-lb, data at /var/lib/codex-lb, ports 2455/1455, and network codex-lb-net. If you customized the launch, use your existing ports and networks and include the same -e, --env-file, additional mounts, and other runtime options in both the upgrade and rollback commands. If your data directory or key lives elsewhere, back up those paths too. Do not replace custom settings with the examples.

Download the release before stopping the application. Inspect its mounts and save the container configuration locally; the saved configuration can contain secrets and must not be shared publicly.

set -e
docker pull ghcr.io/lok3rn3t/codexlb-up:1.25.0
docker inspect codex-lb --format '{{.Config.Image}}'
docker inspect codex-lb --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

umask 077
backup_dir="$(mktemp -d "$PWD/codex-lb-backup.XXXXXX")"
mkdir "$backup_dir/data"
docker inspect codex-lb > "$backup_dir/container.json"
docker inspect codex-lb --format '{{.Image}}' > "$backup_dir/image-id"
docker stop --time 60 codex-lb
docker cp -a codex-lb:/var/lib/codex-lb/. "$backup_dir/data/"
test -s "$backup_dir/data/store.db"
test -s "$backup_dir/data/encryption.key"
printf 'Backup saved to %s\n' "$backup_dir"

Keep the stopped original container as a reference. Reuse its volumes with --volumes-from, so the new application receives the actual existing data even if the volume has a different name. Add your original environment and other custom options here if applicable.

docker rename codex-lb codex-lb-upstream-backup
docker run -d --name codex-lb --restart unless-stopped \
  --network codex-lb-net \
  -p 2455:2455 -p 1455:1455 \
  --volumes-from codex-lb-upstream-backup \
  ghcr.io/lok3rn3t/codexlb-up:1.25.0

docker logs --tail 100 codex-lb
curl --fail --retry 30 --retry-delay 2 --retry-all-errors \
  --retry-max-time 120 --max-time 5 http://127.0.0.1:2455/health/ready
docker exec codex-lb python -c 'import app; print(app.__version__)'

Then sign in with the existing dashboard credentials and verify your accounts, API keys, settings, and history. Make a normal client request. Keep the backup until that verification is complete. Existing client URLs remain the same. Active streams disconnect during the restart and may need a client retry.

The default entrypoint applies the inherited schema updates before serving. CODEX_LB_DATABASE_MIGRATE_ON_STARTUP=false deliberately prevents that step; beta.9's older schema then fails startup. If schema changes are prohibited, keep that setting and the old image until a separate upgrade is approved. Do not bypass the mismatch with stamp, deletion of store.db, or a new empty volume. The documented transition does not require a PostgreSQL upgrade.

Rollback

After the new image has upgraded the schema, do not simply restart the original container against that volume. Restore the backup into a new volume and launch the exact original image recorded above. This retains the failed container and upgraded data for inspection. The example uses the same shell's backup_dir; set it to the printed backup path if you opened a new shell. Changes made after the backup will not be present in the restored instance.

docker stop --time 60 codex-lb
docker rename codex-lb codex-lb-upgrade-failed
rollback_volume="codex-lb-rollback-$(date +%Y%m%d%H%M%S)"
docker volume create "$rollback_volume"
docker create --name codex-lb --restart unless-stopped \
  --network codex-lb-net \
  -p 2455:2455 -p 1455:1455 \
  -v "$rollback_volume:/var/lib/codex-lb" \
  "$(cat "$backup_dir/image-id")"
docker cp -a "$backup_dir/data/." codex-lb:/var/lib/codex-lb/
docker start codex-lb

For external PostgreSQL, keep the existing CODEX_LB_DATABASE_URL, PostgreSQL server/version, and encryption key. The filesystem backup above does not back up PostgreSQL: make a consistent database backup before upgrading and restore that backup for rollback. Do not run the repository's postgres-upgrade profile as part of this image change. The dedicated beta.9 container check uses SQLite; external database deployments require their own backup and rehearsal.

Releases and source

See GitHub Releases for the fix list, verification results, and downloadable packages. Validated releases publish PyPI packages, Docker images, a Helm chart, and a GitHub Release.

The original project and its contributors retain their attribution and MIT license. General configuration documentation is inherited from upstream; use the fork's installation command above to install this distribution.

Release contract: OpenSpec release-management specification.

Metadata

Release files for codexLB-up 1.25.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codexLB-up 1.25.0
File Size Uploaded Provenance Actions
codexlb_up-1.25.0.tar.gz 20.8 MB With provenance Details for codexlb_up-1.25.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codexLB-up 1.25.0
File Interpreter ABI Platform Actions
codexlb_up-1.25.0-py3-none-any.whl Python 3 none any Details for codexlb_up-1.25.0-py3-none-any.whl

Total release size: 24.1 MB

Release files / codexlb_up-1.25.0.tar.gz

Download URL codexlb_up-1.25.0.tar.gz
Size 20.8 MB
Tags Source
SHA-256 checksum
How to use checksums
43989c8467f30a76c08d09174b16fa63841be6ee4c31d331a86a0e5dca00d213
BLAKE2b-256 checksum
How to use checksums
a421a98a05150d4e68a0defa2ee8a19631ddd8b894d356aab089df00e501704e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / codexlb_up-1.25.0-py3-none-any.whl

Download URL codexlb_up-1.25.0-py3-none-any.whl
Size 3.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
96371d1d91d997a7c17d353093615980a6c0da1b9650ad8f5556045a4cf4be4a
BLAKE2b-256 checksum
How to use checksums
082fae48905e1d633477c7de0892ba09acf41068d095d2003fbc6e5d4a5fc316
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for codexLB-up 1.25.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for codexlb_up-1.25.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.25.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page