> Keiro Labs API documentation - Codex Setup
> Page: https://docs.keirolabs.ai/codex.html
> Markdown: https://docs.keirolabs.ai/codex.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

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

## Before you configure Codex

1. Install stock Codex from the
   [official Codex quickstart](https://developers.openai.com/codex/quickstart).
2. Open [API keys](https://console.keirolabs.ai/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.

## Download, inspect, and run the installer

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

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
~/.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:

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

## Files written by setup

| Path | Purpose | Permission posture |
|---|---|---|
| `~/.codex/config.toml` | Keiro Responses provider block only | Atomically replaced only when content changes; unrelated settings are preserved |
| `~/.codex/keiro.config.toml` | The `--profile keiro` overlay: eb1 default model and catalog | Non-secret configuration, mode `0600`; reruns merge and keep settings Codex persisted here |
| `~/.codex/keiro.json` | Four-model public eb1 catalog | Non-secret configuration, mode `0600` |
| `~/.codex/keiro-auth` | Reads the selected OS store or operator-supplied external helper for setup checks and Codex requests | Contains no key bytes, mode `0700` |
| `~/.local/bin/keiro` | Supported 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 guidance | Contains no key bytes, mode `0755` |
| `~/.codex/config.toml.keiro-install-backup` | Configuration immediately before the latest real change | Mode `0600`; unchanged on no-op reruns |
| `~/.codex/config.toml.keiro-original` | Configuration before Keiro's first change, written once and never refreshed | Mode `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 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](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml)
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_catalog_json = "/absolute/path/to/.codex/keiro.json"
model_reasoning_effort = "none"
service_tier = "default"
```

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

```toml
[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](streaming.md#stream-lifetime-and-time-entitlements).

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

   ```bash
   # macOS
   security delete-generic-password -s ai.keirolabs.codex -a codex
   # Linux
   secret-tool clear service ai.keirolabs.codex account codex
   ```

   Rerunning setup while an entry exists keeps the stored key and says so.
3. Launch Codex and verify a harmless request.
4. Delete the old key in the console.

## Check or remove the setup

```bash
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:

```bash
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](agent-setup.md)
- [API keys](api-keys.md)
- [Models](models.md)
- [Tool calling](tool-calling.md)
- [Usage and billing](usage-billing.md)