Use eb1 with Codex

Keiro's setup adds an opt-in keiro profile to the stock Codex CLI and installs a keiro launcher command. Typing keiro opens Codex on the public eb1 catalog with eb1-preview as the default; plain codex keeps your existing OpenAI models, picker, and settings untouched. No Codex fork or local proxy is required.

On this page 1 of 13

Before you configure Codex#

  1. Install stock Codex from the official Codex quickstart.
  2. Open API keys and create a dedicated key for this Codex installation.
  3. Keep the newly created key in your password manager until setup is complete.

A dedicated key lets you inspect and revoke Codex traffic independently from production application traffic.

Install and configure#

Run the installer:

Run a curl request Shell
s="$(curl -fsS 'https://api.keirolabs.ai/v1/codex/install.sh')" && bash -c "$s"

The command downloads the whole script before bash starts. If the download fails, the command exits with an error and runs nothing. The script runs its main function only on its final line, so a partial download also runs nothing.

To read it first, download it, compare the X-Content-SHA256 response header (add -D - to print the headers) against shasum -a 256 keiro-codex.sh, then run the local copy:

Run a curl request Shell
curl -fsS 'https://api.keirolabs.ai/v1/codex/install.sh' -o keiro-codex.sh
less keiro-codex.sh
bash keiro-codex.sh
rm keiro-codex.sh

The installer requires an existing codex executable. It does not install global npm or Homebrew packages.

On macOS, setup stores the key in Login Keychain. On Linux, setup uses the Secret Service through secret-tool. The generated helper reads that canonical store whenever Codex needs a bearer token. The supported Codex floor accepts command-backed provider authentication, so setup does not copy the key into a dotenv file or process environment. The key never appears in a command argument, repository file, browser storage, console URL, or Codex config file.

With no terminal to prompt from, for example in CI or a script, give setup a key helper instead: an executable that prints the key, such as a script that reads it from your password manager. Pass its absolute path:

Run a curl request Shell
s="$(curl -fsS 'https://api.keirolabs.ai/v1/codex/install.sh')" && KEIRO_AUTH_COMMAND=/absolute/path/to/key-helper bash -c "$s"

The helper must take no input, return exactly one non-empty, whitespace-free bearer token on stdout (with an optional final newline), and exit nonzero when the credential is unavailable. Setup preflights it the way Codex invokes it (no terminal, no stdin) and makes one authenticated request before changing Codex configuration, so a rejected key fails the install instead of your first prompt.

Setup requires Codex 0.166.0 or newer. It is the first release whose plain codex resume refuses a Keiro session instead of continuing it on another provider, and it carries the live provider model-catalog contract used by this setup. Older installations fail closed with an update message and no configuration changes.

Before activation, setup asks the installed Codex binary to parse both staged configuration views using the bundled catalog for offline parsing. It uses strict configuration validation when the debug command accepts it. The pinned stock release reports that --strict-config is unsupported specifically for codex debug; setup recognizes only that exact diagnostic and repeats the same parse without that unsupported flag. Every other debug failure remains fatal. The request-time provider and command-backed credential path is separately exercised under strict configuration in the release tests. If you ran the brief env-key installer generation, rerunning setup stops before making changes. First use that installation's keiro self uninstall, or remove both KEIRO_API_KEY from ~/.codex/.env and its [model_providers.keiro] block from ~/.codex/config.toml; then run setup again. Current setup never reads or edits a shared dotenv file.

Launch Codex#

Run in the terminal Shell
keiro

keiro is a small launcher installed to ~/.local/bin (override with KEIRO_BIN_DIR); it runs codex --profile keiro, so keiro exec ... and keiro resume work like their codex counterparts. Codex management commands that take no profile, such as codex login or codex update, run as plain codex; keiro update refreshes the Keiro setup instead. If ~/.local/bin is not on your PATH, either add it or use the launcher by full path:

Run in the terminal Shell
~/.local/bin/keiro

To check the setup without opening a session, run one prompt. Codex prints the answer and exits. --skip-git-repo-check lets the check run outside a Git repository:

Run in the terminal Shell
keiro exec --skip-git-repo-check "Say hello in one sentence."

Two different tools install a command named keiro: this launcher, and the command-line tool from the Keiro Python package (SDKs and CLI). Run keiro --version to see which one answers. The Python tool prints a line that starts with keiro; this launcher prints the Codex version. If a keiro file that Keiro setup did not write is already at the launcher path, setup stops and changes nothing; set KEIRO_BIN_DIR to another directory and rerun setup. If a different keiro comes earlier on your PATH, setup says so and prints the launcher's full path.

Image input is not supported by the Keiro Codex profile yet. The supported keiro launcher rejects -i, attached -iFILE, --image, and --image=FILE before starting Codex, reading a credential, or sending a request. A -- ends option scanning, so those strings remain valid as literal prompt text after it.

Do not use codex --profile keiro -i ... as a workaround. Stock Codex accepts that command but, because the Keiro catalog truthfully declares text-only input, removes the image from prompt history and sends a text-only request. Direct profile launches and images pasted into the TUI do not pass through the keiro launcher's guard. This upstream limitation remains open until Keiro can advertise and preserve image input end to end.

Use /model inside the session to switch among:

  • eb1-preview
  • eb1-frontier-preview
  • eb1-fast-preview
  • eb1-efficient-preview

Plain codex (without the profile flag) is unchanged and keeps your stock OpenAI models. To use OpenAI models, exit and run plain codex; one session uses one profile.

Requests appear in Keiro Usage and Logs like other API traffic.

Earlier versions of this setup made eb1 the process-wide Codex default by writing top-level model and model_provider keys. Rerunning the installer reports those settings and leaves them in place, never deleted. To restore plain codex to stock behavior, remove the top-level model, model_provider, and model_catalog_json keys from ~/.codex/config.toml; keiro self uninstall also removes them when they point at the Keiro-managed catalog. If the profile's last-selected model is no longer a current public selection, setup resets it to eb1-preview and prints a note.

How model limits stay current#

Codex requests the authenticated gateway catalog at startup and on its normal refresh cycle. The gateway reads every context window from the central model catalog for each discovery request. Codex derives its automatic compaction threshold from that live window; setup never writes limits into keiro.json. Codex owns a five-minute catalog cache, so changes follow its refresh cycle, not necessarily the next turn in an already-running session.

Installations made before this change need setup once more: run keiro update, or rerun the setup command if your launcher predates keiro update. Update Codex to 0.166.0 or newer first if needed (codex update). Setup removes model_catalog_json from the managed Keiro profile and updates the provider catalog URL. The new launcher heals a restored old managed profile on its next launch. An old keiro.json may remain for rollback; it is ignored and uninstall removes it. After migration, future limit changes need no setup rerun.

Files written by setup#

PathPurposePermission posture
~/.codex/config.tomlKeiro Responses provider block onlyAtomically replaced only when content changes; unrelated settings are preserved
~/.codex/keiro.config.tomlThe --profile keiro overlay: eb1 default model and reasoningNon-secret configuration, mode 0600; reruns merge and keep settings Codex persisted here
~/.codex/keiro-authReads the selected OS store or operator-supplied external helper for setup checks and Codex requestsContains no key bytes, mode 0700
~/.local/bin/keiroSupported launcher: rejects unsupported image flags, then starts codex --profile keiro; also provides keiro self management verbs and records the selected credential backend for truthful status/removal guidanceContains no key bytes, mode 0755
~/.codex/config.toml.keiro-install-backupConfiguration immediately before the latest real changeMode 0600; unchanged on no-op reruns
~/.codex/config.toml.keiro-originalConfiguration before Keiro's first change, written once and never refreshedMode 0600; only minted when the config was still pre-Keiro

Setup refuses to overwrite a keiro.config.toml or launcher file it did not write (an existing keiro command from another tool fails the install with instructions instead of being replaced), refuses a customized [model_providers.keiro] block instead of silently reverting your edits, and takes the same lock as keiro self uninstall so setup and removal cannot interleave. A blocked operation leaves the active operation's lock and files untouched; the operation holding the lock releases it when it exits.

The provider disables automatic request and stream retries so authentication and protocol errors fail visibly instead of producing retry storms. Its idle timeout follows Long requests.

Manual configuration#

The console exposes a local download for the installer and previews the non-secret profile and settings blocks for review. Merge settings into an existing ~/.codex/config.toml; do not overwrite unrelated profiles, sandbox policy, plugins, or MCP configuration.

The official Codex configuration reference documents custom model providers, model catalogs, profile files, and command-backed provider authentication. The relevant contract is two files. ~/.codex/keiro.config.toml (the profile Codex loads for --profile keiro):

TOML
model = "eb1-preview"
model_provider = "keiro"
model_reasoning_effort = "none"
service_tier = "default"
features.apps = false
features.daemon_auto_start = false

The provider settings below follow Long requests and are merged into ~/.codex/config.toml:

TOML
[model_providers.keiro]
name = "Keiro"
base_url = "https://api.keirolabs.ai/v1"
model_catalog_url = "https://api.keirolabs.ai/v1/models"
wire_api = "responses"
stream_idle_timeout_ms = 3720000
stream_max_retries = 0
request_max_retries = 0

[model_providers.keiro.auth]
command = "/absolute/path/to/keiro-auth"
timeout_ms = 5000
refresh_interval_ms = 0

Replace the /absolute/path/to prefix with the resolved absolute path to your home directory. The auth command must be an absolute executable path. Codex invokes it without stdin and uses its single-line stdout as the bearer token; do not add env_key alongside the auth table. The installer creates the helper automatically and leaves the bearer in your operating system's credential store. After rotating the key, re-run the installer so its online preflight verifies the replacement.

service_tier = "default" is stock Codex's explicit-clear sentinel: eb1 sessions send no service tier and print no tier warning, while any tier you use with OpenAI models stays configured for plain codex. The two features lines apply only through keiro: ChatGPT apps stay off, so a ChatGPT login is never used inside a Keiro session, and Codex skips the shared background server that profile launches cannot use anyway, so no notice appears about it. eb1 selects its own reasoning depth. On the raw API you may send reasoning.effort to cap that depth (see Models). No wall-clock limit ends a working run — see Streaming.

Tool boundaries#

Shell commands, file reads, and file edits are local stock-Codex tools. Keiro's provider configuration does not broaden their filesystem or approval scope.

Browser and Chrome control are separate Codex app integrations. Installing the Keiro model provider does not install a browser extension or make those tools available in Codex CLI. Hosted web search is also a separate provider tool and is not advertised by the current Keiro Codex model catalog.

Rotate or revoke the key#

  1. Create a replacement dedicated key in the console.
  2. Remove the stored entry, then rerun setup so it prompts once for the new key: Rerunning setup while an entry exists keeps the stored key and says so.
    Run in the terminal Shell
     # macOS
     security delete-generic-password -s ai.keirolabs.codex -a codex
     # Linux
     secret-tool clear service ai.keirolabs.codex account codex
  3. Launch Codex and verify a harmless request.
  4. Delete the old key in the console.

Update, check, or remove the setup#

Run in the terminal Shell
keiro update           # refresh this setup from the Keiro gateway
keiro self status      # what Keiro setup manages, and how to launch
keiro self uninstall   # remove it all; plain codex is never changed

keiro update downloads the current setup over HTTPS from the gateway named in your [model_providers.keiro] block, checks it against the X-Content-SHA256 header the gateway sends with it, and runs it. A mismatch stops before anything runs. Setup reuses your stored key, or the key program you named with KEIRO_AUTH_COMMAND, so a rerun prompts only when neither exists. keiro update never updates Codex itself; use codex update for that.

Status is a local-first diagnostic. It reads no credential and sends no request. It reports:

  • The launcher path that answered, and whether keiro on your PATH resolves to it, is missing, or is shadowed by a different keiro executable.
  • The Codex runtime the launcher will exec (command -v codex) and its version.
  • The session the profile applies through keiro: model, provider, reasoning effort, and service tier. These keys never affect plain codex.
  • The live gateway catalog source; an old keiro.json is no longer authoritative.
  • The credential source selected at install time: macOS Login Keychain, Linux Secret Service, or an external helper.

A shadowed launcher is the usual cause of "I updated Codex but keiro did not change": a standalone keiro binary earlier on PATH is running instead.

Uninstall removes the profile, catalog, key helper, [model_providers.keiro] block, and the keiro command itself. For an OS store it prints only that store's removal command. For an external helper it says that Keiro stored no credential to remove. Backups are kept. To change credential backends, first run the existing keiro self uninstall and its printed credential-cleanup command, then rerun setup with the new backend. Setup refuses an in-place backend change before reading a credential or changing files so an old OS-store entry cannot become invisible to status or uninstall.

Replace a standalone Keiro binary#

Earlier Keiro previews shipped keiro as a standalone compiled executable. It does not update when Codex updates, and it reads your global Codex model, effort, and service-tier settings against the Keiro provider. Setup detects a compiled executable at the launcher path and refuses to overwrite it. To replace it with the launcher, opt in explicitly:

Run in the terminal Shell
KEIRO_MIGRATE_LEGACY_BINARY=1 bash keiro-codex.sh

Setup renames the executable to a timestamped backup beside it (keiro.keiro-legacy-<UTC timestamp>), installs the launcher, and prints the backup path. If activation fails, the executable is moved back before setup exits. Nothing is deleted. keiro self uninstall names any kept backup and the mv command that restores it. To keep the executable and install the launcher elsewhere, set KEIRO_BIN_DIR instead.

Roll back#

If setup changed an existing configuration, restore the immediate backup:

Run in the terminal Shell
cp ~/.codex/config.toml.keiro-install-backup ~/.codex/config.toml

~/.codex/config.toml.keiro-original holds the configuration from before Keiro's first change, if the config predated Keiro.

The installer writes staged files in ~/.codex and renames them into place, so an interrupted write does not leave a partial TOML document. It rejects symlinks and non-regular files at managed paths instead of replacing an unexpected target. If activation fails after it begins, setup attempts to restore every managed file from same-filesystem snapshots before exiting. Each file replacement is atomic, but the multi-file activation is not a filesystem transaction and cannot guarantee rollback after power loss, SIGKILL, or a restore failure. If a restore command fails, setup logs the retained same-filesystem snapshot path so an operator can recover the previous bytes manually.

Troubleshooting#

keiro-auth failures mean the OS secret entry or configured external helper is missing. Setup fails before activation when credential preflight fails.

A staged configuration failed stock Codex validation error means the merged configuration is not valid for the installed Codex. Its preceding parse error should identify the conflict; normalize duplicate provider declarations as explicit [model_providers.<id>] tables, validate the TOML, and rerun setup. The sole compatibility exception is stock Codex's exact --strict-config-unsupported diagnostic for codex debug; similar or additional text does not trigger a retry.

An existing config contains multiline TOML strings error is a conservative rewrite guard. Merge the reviewed Keiro block manually instead of asking the shell installer to edit a document whose string contents can resemble TOML keys or table headers.

A Keiro rejected the key error during setup names where the key came from (Keychain, Secret Service, or your KEIRO_AUTH_COMMAND helper) and means Keiro refused that key. Codex configuration is not changed. A key you typed during that run is not kept, so rerun setup and enter an active key. A key that was already stored stays; replace it there (see the rotation steps) and rerun setup. A Codex ... is older than error means the installed Codex is older than 0.166.0; update it with codex update, then rerun setup.

If the /model picker stays open after you choose a model, rerun setup once to migrate the old static catalog to live discovery.

A 401 at request time means the stored key is invalid or revoked. A model error means the selected model is not enabled for that key. Check the console's API Keys and Models pages before retrying.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console