Codex

The Codex provider always uses the Codex harness. open·kritt supports two access methods:

• Sign in with ChatGPT uses an eligible ChatGPT/Codex plan and is recommended for interactive local use.
• OpenAI Platform API key uses metered OpenAI API billing and works well for automation or separate API spend.

These methods use different accounts and billing systems. A ChatGPT subscription does not add API credits to an OpenAI Platform account.

Recommended: sign in with ChatGPT

The guided flow uses Codex device authentication. It runs in a temporary engine container, so you do not need to install Codex on the host and it does not depend on a browser callback to a container's localhost address.

1. Open the Codex login menu

   Run ./kritt setup, select Codex login, then select Sign in with Docker.

2. Complete the device flow

   Open the URL printed by Codex, sign in to the ChatGPT workspace that has Codex access, and enter the one-time code.

3. Confirm the saved login

   Return to the CLI. Setup should show Codex login present. By default the credential is saved to ./.data/codex/auth.json and mounted into the engine.

4. Start open·kritt

   ./kritt start

If Codex is already signed in on the host and stores a readable file at ~/.codex/auth.json, choose Import local login instead. The CLI copies that file into the project login directory. A login held only in an operating-system keychain cannot be imported this way; use the guided device flow instead.

Weekly usage and manual resets

For ChatGPT sign-ins, Accounts → Codex shows the weekly reset time when Codex reports a weekly usage window. If that window has not started, choose Start quota to make a small Codex request through the selected account and refresh its usage. The refresh can take a short while.

When Codex reports manual reset credits, Accounts shows how many are available. Choose Use reset to consume one for an eligible usage window. open·kritt asks for confirmation because this action cannot be undone. These controls apply to ChatGPT sign-ins, not OpenAI Platform API keys.

Linux ownership and permissions

Run ./kritt as your regular Linux user, not with sudo. The guided device flow and Import local login preserve the host user's ownership of the project credential. The CLI keeps ./.data/codex private and saves auth.json with owner-only permissions so the host CLI and engine can both use it with standard Docker Engine, rootless Docker, or Docker Desktop.

Prefer Import local login over a manual cp. It handles the destination ownership and permissions, including replacement of a credential previously written by a container.

If an older open·kritt release created .data/codex or auth.json as root, repair the existing project credential from the repository root. Replace the first value if ENGINE_CODEX_HOME_HOST uses a custom path:

CODEX_HOME_DIR=.data/codex
sudo chown -R "$(id -u):$(id -g)" "$CODEX_HOME_DIR"
chmod 700 "$CODEX_HOME_DIR"
[ ! -e "$CODEX_HOME_DIR/auth.json" ] || chmod 600 "$CODEX_HOME_DIR/auth.json"
./kritt setup

Setup should then show Codex login present. These commands change ownership and modes only; they do not print or modify the credential contents.

Note

open·kritt marks the shared Codex credential mounts for access on SELinux-enabled Linux. Docker can recursively relabel a configured host path, so keep ENGINE_CODEX_HOME_HOST project-local. Do not point it directly at ~/.codex, your home directory, or a shared/system directory; use Import local login instead. If a custom Compose override removes the label, check the host's SELinux denials and mount labels. Do not disable SELinux or make auth.json world-readable.

Warning

Docker Engine's rootful userns-remap mode is not currently supported. Its remapped container user cannot read the private host credential, and other writable bind mounts in the stack have the same ownership constraint. Use standard Docker Engine, rootless Docker, Docker Desktop, or an API key instead. Do not work around this by making auth.json group- or world-readable or by disabling user-namespace isolation for only one service.

Warning

auth.json contains access tokens. Treat it like a password. Do not copy it between users, commit it, or include it in logs and support requests.

Read the official Codex authentication guide for account, device-login, and credential-storage details.

Alternative: use an OpenAI API key

open·kritt exposes both OPENAI_API_KEY and CODEX_API_KEY, but they accept the same OpenAI Platform API key and enable the same Codex provider. You only need one:

• OpenAI API key uses the conventional OPENAI_API_KEY name. open·kritt supplies it to Codex when CODEX_API_KEY is empty.
• Codex API key sets CODEX_API_KEY directly for Codex non-interactive runs. It takes precedence when both values exist.

1. Create a Platform API key

   Sign in to the OpenAI API key page, select the intended project, and create a secret key. Copy it when it is shown.

2. Check API billing

   Confirm the Platform organization has billing configured in Billing settings. API-key usage is charged at OpenAI API rates.

3. Save one key option

   Run ./kritt setup, choose OpenAI API key or Codex API key, and paste the secret into the hidden input. Do not configure both unless you intentionally want CODEX_API_KEY to override OPENAI_API_KEY.

4. Start or recreate the stack

   Run ./kritt start. If the stack was already running, stop it with Ctrl+C before starting it again.

Verify and troubleshoot

• ./kritt setup should show the chosen login or key as present.
• The create and generation forms should list Codex and load the models available to the authenticated account.
• If the provider appears but its model catalog does not load, inspect docker compose logs engine and confirm the account can use Codex models.
• If device authentication is unavailable for a managed workspace, ask its administrator whether device-code login is allowed, import a file-based local login, or use a Platform API key.
• On Linux, if the OpenAI page reports success but setup does not show the login, follow the ownership recovery steps and retry the guided flow without sudo.

Next: configure Claude Code, OpenRouter, or learn how to choose a model and harness.