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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.