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.

Copy Page https://docs.keirolabs.ai/codex.md

Before you configure Codex#

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

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.

Download, inspect, and run the installer#

Download the installer instead of piping a mutable response directly to a shell:

1
2
3

curl --proto '=https' --tlsv1.2 -fsS \
  https://api.keirolabs.ai/v1/codex/install.sh \
  -o keiro-codex-install.sh

Inspect the local copy, then run it:

1
2
3

less keiro-codex-install.sh
bash keiro-codex-install.sh
rm keiro-codex-install.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.

For a headless machine with an existing workload-identity or secret-manager helper, point setup at the helper's absolute executable path:

1
2

KEIRO_AUTH_COMMAND=/usr/local/bin/fetch-keiro-token \
  bash keiro-codex-install.sh

The helper must take no input, return a non-empty bearer token on stdout, 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.134.0 or newer, the first supported release with both standalone profile files and the command-backed provider-auth contract used by this setup. Older installations fail closed with an upgrade message and no configuration changes.

Before activation, setup asks the installed Codex binary to parse both staged configuration views and the staged catalog. It uses strict configuration validation when the debug command accepts it. Stock Codex 0.144.5 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#

1

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. If another keiro command is already on your PATH, setup stops and tells you rather than replacing it. If ~/.local/bin is not on your PATH, either add it or use the launcher by full path:

1

~/.local/bin/keiro

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 0.144.5 currently 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:

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 moves that old default into the opt-in profile when the old settings are recognizably Keiro's own, keeps the model you had selected, and restores plain codex to stock behavior. Settings the earlier setup did not write are reported and left in place, never deleted.

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

Files written by setup#

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 a lock so concurrent reruns cannot interleave.

The provider disables automatic request and stream retries so authentication and protocol errors fail visibly instead of producing retry storms. A bounded two-minute idle timeout allows normal long-running eb1 turns without turning a stalled stream into an hour-long hang.

Manual configuration#

The console exposes a local download for the installer and previews the non-secret model catalog and settings block 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):

1
2
3
4
5

model = "eb1-preview"
model_provider = "keiro"
model_catalog_json = "/absolute/path/to/.codex/keiro.json"
model_reasoning_effort = "none"
service_tier = "default"

And the provider block merged into ~/.codex/config.toml:

1
2
3
4
5
6
7
8
9
10
11
12

[model_providers.keiro]
name = "Keiro"
base_url = "https://api.keirolabs.ai/v1"
wire_api = "responses"
stream_idle_timeout_ms = 120000
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 catalog uses an absolute path to keep the value unambiguous. The auth command must also 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. eb1 selects its own reasoning depth. On the raw API you may still send reasoning.effort, which also selects the run's time entitlement — 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

   1
   2
   3
   4

    # 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.

Check or remove the setup#

1
2

keiro self status      # what Keiro setup manages, and how to launch
keiro self uninstall   # remove it all; plain codex is never changed

Status names the credential source selected at install time: macOS Login Keychain, Linux Secret Service, or an external helper. 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.

Roll back#

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

1

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 0.144.5'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 the stored Keiro key was rejected error during setup means the gateway refused the stored credential; replace it (see the rotation steps) and rerun. A Codex ... predates profile files error means the installed Codex is older than 0.134.0; upgrade Codex, then rerun setup.

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.

Related pages#

• Agent-driven setup
• API keys
• Models
• Tool calling
• Usage and billing