Codex and ChatGPT

This page is for administrators who want to translate with OpenAI’s Codex models. Libris offers two ways:

Both use the same translation pipeline as any other provider: memory, prompts, structured answers, glossary, checks, history and resumable jobs.

Use a ChatGPT account

Start the bridge

The bridge is an optional container, codex, that is not part of the published image: it is built from the source tree on your machine. A .env generated by scripts/setup.py already contains its private token, CODEX_BRIDGE_TOKEN. On an older .env without it, add one first:

python3 scripts/enable_codex.py

The script only adds that dedicated token. It never reads or copies a Codex sign-in that may already exist on the machine.

Then build and start the bridge with the rest of Libris:

./scripts/install-docker.sh --profile codex

or, by hand:

docker compose --profile codex build codex
docker compose --profile codex up -d --no-build --wait

The installer writes COMPOSE_PROFILES=codex into .env, so a plain docker compose pull or up includes the bridge; an update adds it to an older .env. If you manage .env yourself, keep that line or pass --profile codex to every docker compose command, or the bridge stays on its old image or does not start.

Libris checks that the bridge runs its own version. When they differ, Settings › LLM providers and the Codex connection show a warning with the command that updates the bridge, /health answers "codex_bridge": "mismatch", and librisctl doctor fails that check. A bridge that does not answer is reported as unknown and blocks nothing.

Connect the account

In Settings › LLM providers:

1. Click New provider and choose Codex · ChatGPT account as the connection.
2. Give it a name and click Save. The model can be chosen after sign-in.
3. Click Sign in with ChatGPT.
4. Open the official OpenAI link shown, and enter the temporary code there.
5. If OpenAI refuses the code, enable device-code sign-in in your ChatGPT (or workspace) security settings.
6. When the state becomes Connected, click Check / detect Codex models.
7. Choose a model from the list, then click Save.
8. Select this provider in the configuration of the books you want to translate with it.

Like any provider, it is shared by every book that selects it. For several ChatGPT accounts, create several providers: each has its own Codex home directory and its own Codex process.

Disconnect this account signs out through Codex’s official API. Signing in or out is refused while a book is using the provider: pause those books first. If the session expires and cannot be renewed, the provider’s books are blocked until someone signs in again.

Sign-ins are stored in the codex-state volume. It holds credentials: protect it like .env, and include it in your backups if you want to avoid signing in again after a restore.

Limits of this connection

• Codex runs at OpenAI: this is not local inference. Your subscription’s quotas and terms apply; when a quota is reached, the book waits (at least an hour) and resumes on its own.
• Temperature and top-p are not sent.
• The output limit you set only reserves budget inside Libris: Codex has no equivalent of max_output_tokens.
• Books can use separate Codex conversations in parallel, within the provider’s Concurrent books and the worker’s limits. Pausing a book interrupts only that book’s call.
• Each call starts a fresh, temporary conversation. Continuity between passages comes from Libris’ memory, not from a Codex history.
• The request inspector shows the messages Libris sent. Codex adds its own framing around them, which Libris cannot see; such requests are marked upstream_prompt_managed_by_codex=true.

Use an OpenAI API key

Create a provider of type Codex / OpenAI · API key (Responses) with:

Base URL: https://api.openai.com/v1
API key:  your OpenAI Platform key
Model:    a Responses/Codex model your account may use

This type does not need the bridge container. The API is billed separately from any ChatGPT subscription. Enter the prices per million tokens if you want Libris to show costs.

Libris sends no tools (tools=[], tool_choice=none), asks OpenAI not to store the response (store=false) and uses structured output (text.format). Only the final output_text of the answer becomes a translation; reasoning and refusals are recognised as such, and an incomplete answer is rejected.

How the bridge is isolated

• The bridge publishes no port. Only containers on the Libris Compose network can reach it, and every call must carry CODEX_BRIDGE_TOKEN; without a token of at least 32 characters the bridge refuses to start.
• The container has no access to the books volume, the application files or the Docker socket. It runs as an unprivileged user on a read-only file system; only codex-state and a temporary area are writable.
• The Codex process receives a filtered environment, without the bridge token or any database secret.
• Shell, web search, image tools, plugins, apps and sub-agents are disabled in its configuration. Any request from Codex to run a tool or obtain an approval is refused. Reasoning and commentary never become translations.

Troubleshooting

References

• Codex app-server
• Codex authentication and device-code sign-in
• app-server protocol, version 0.160.0