Use eb1 with Claude Code
Keiro's installer adds a claude-keiro command that starts the stock Claude Code CLI on the public eb1 models. No fork of Claude Code is involved, and your existing claude command keeps its own settings and credentials.
On this page 1 of 12
Before you install#
- Open API keys.
- Create a dedicated key for this Claude Code installation.
- Keep the newly revealed secret available in your password manager until setup is complete.
- Run the installer from an interactive terminal so it can prompt without echoing the secret.
A dedicated key lets you inspect and revoke Claude Code traffic independently from production application traffic.
Install and configure#
Run the installer:
s="$(curl -fsS 'https://api.keirolabs.ai/v1/claude-code/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-claude-code.sh, then run the local copy:
curl -fsS 'https://api.keirolabs.ai/v1/claude-code/install.sh' -o keiro-claude-code.sh
less keiro-claude-code.sh
bash keiro-claude-code.sh
rm keiro-claude-code.sh
If Claude Code is not installed, the script says so and installs it with npm when npm is available. It then prompts for the Keiro API key, verifies the key with one authenticated request to the API, stores it with owner-only permissions, and writes the claude-keiro launcher along with a keiro-claude alias.
Installing from a script with no terminal to prompt from? Store the key in a file only you can read and pass the file's absolute path. The installer never accepts the key itself as a command argument:
s="$(curl -fsS 'https://api.keirolabs.ai/v1/claude-code/install.sh')" && bash -c "$s" keiro-install --key-file /absolute/path/to/key
keiro-install is the name the script uses in its messages. If you downloaded the script to read it first, run bash keiro-claude-code.sh --key-file /absolute/path/to/key before you delete it. The key file must hold only the key, on one line, and be a regular file that you own; symlinks are refused. If other users can read it, setup tells you to run chmod 600 on it.
Setup checks the key with one authenticated request to the API before it stores anything, and it needs curl for that check. If the check does not succeed, setup stops with exit status 1 and leaves the key file unchanged. A 401 means the key is invalid or revoked, and a 403 means the key lacks access. If the API cannot be reached or answers with another error, setup says so; check your connection or wait a few minutes, then run the install command again.
The installer is idempotent. Every artifact it writes is replaced or skipped, and it never edits ~/.claude/settings.json, your shell startup files, or the stock claude command. It closes by listing the files it wrote, and its last lines are the verdict: Verified against the API, then Done. with the command that starts Claude Code, or — if no key is stored by the end of a run — the --key-file rerun command, Setup incomplete: no API key stored., and a nonzero exit.
Launch Claude Code#
claude-keiro
To check the setup without opening a session, send one prompt. Claude Code prints the answer and exits:
claude-keiro -p "Say hello in one sentence."
claude-keiro accepts the same arguments as claude, so claude-keiro --resume resumes a session the same way claude --resume does. Requests appear in Keiro Usage and Logs like other API traffic. keiro-claude is an alias for the same launcher; either spelling starts the same session.
Use /model inside Claude Code to switch tiers. Each tier is pinned to a public eb1 model, in descending capability order:
| Claude Code tier | Keiro model |
|---|---|
| Fable | eb1-frontier-preview |
| Opus, and the session default | eb1-preview |
| Sonnet | eb1-efficient-preview |
| Haiku | eb1-fast-preview |
These four public eb1 model IDs are the only ones the tiers resolve to. Claude model IDs are not part of the public Keiro catalog. Unless your key has access to models outside the eb1 family, a request carrying one is refused with a 403 model_not_available or a 404 model_not_found.
Subagents run on the session model. When the main agent hands a subagent a tier (the Agent tool's model setting, or the model line of an agent file), that tier resolves through the same table, so a session on eb1-frontier-preview can run its searches on eb1-fast-preview.
The model picker#
The /model picker lists eb1-preview, eb1-frontier-preview, eb1-fast-preview, and eb1-efficient-preview using their public IDs and catalog descriptions in both helper and direct modes. The launcher sets the tier rows from the table above; picker labels use these rows while launch requires authenticated model-limit discovery. Client requests and Keiro's Usage and Logs pages use the same bare eb1-* IDs.
The launcher resolves the default model's context window from authenticated /v1/models before every launch, with auto-compaction enabled. Python 3 and the installed request helper are required; discovery failure stops launch. Existing launchers need one setup rerun; future limit changes need no reinstall. Claude Code uses one session-wide window, so switching to a larger model in that session still uses the primary tier's conservative window.
The launcher also sets CLAUDE_CODE_MAX_OUTPUT_TOKENS to 128,000, the most Claude Code allows for these model IDs, in place of its 32,000-token default. A long tool call or file write can finish in one turn instead of stopping at the client's cap. Existing installs pick this up by running the installer again.
The launcher also sets CLAUDE_CODE_GATEWAY_HINT_HEADERS=1, so Claude Code labels each request with the agent that sent it (the main session or a subagent), the prompt it serves, whether it is a compaction, and how long its tools ran since the previous request. Keiro records these labels with each request; tool names are stored only as one-way hashes. Existing installs pick this up by running the installer again.
The installer requires python3 on your PATH. claude-keiro runs ~/.claude/keiro-shim.py on a loopback port for the session. The helper records requests and translates connection failures into actionable messages; your key and prompts go only to Keiro. It records each request in ~/.claude/keiro-shim.log; see Troubleshooting for reading it. Set KEIRO_SHIM_LOG to write the log to a different path. If the listener cannot start after discovery succeeds, the launcher connects directly to Keiro with the same picker rows and refreshed context window.
Files written by setup#
| Path | Purpose | Permission posture |
|---|---|---|
~/.local/bin/claude-keiro | Launcher that starts Claude Code on eb1 | Executable mode 0755 |
~/.local/bin/keiro-claude | Alias; either name starts the same session | Symlink to the launcher |
~/.claude/keiro-shim.py | Local helper that records requests and translates connection failures | Mode 0644, holds no secrets |
~/.claude/keiro-api-key | API-key secret | Owner-only mode 0600 |
~/.claude/keiro-shim.log | Helper request log — written by the launcher at each run, not by the installer; KEIRO_SHIM_LOG moves it | Rotated near 1 MB with a .1 backup, holds no secrets; self uninstall removes it |
The launcher reads the key file at startup and passes the secret to the Claude Code process only. Nothing writes it into the launcher body, a settings file, or your shell history.
Set CLAUDE_CONFIG_DIR before installing to keep the key beside a non-default Claude Code configuration directory, or KEIRO_BIN_DIR to write the launcher somewhere other than ~/.local/bin.
Manage the setup#
The launcher carries a self namespace for local management, so removal never requires re-fetching the installer:
claude-keiro self status # show what the setup manages
claude-keiro self uninstall # remove the launcher and helper
claude-keiro self help # list these commands
self status lists the launcher, helper, and key-file paths and whether each is present, plus the helper log locations and whether claude-keiro resolves on your PATH. The key file's contents are never shown.
self uninstall removes the launcher, its keiro-claude alias, the model picker helper, and the helper logs. The key file is never deleted: the command prints the exact rm line to run yourself if you also want the stored secret gone. Plain claude is never changed.
Set up without the installer#
The launcher only sets documented Claude Code environment variables. Pass the same set yourself, scoped to the one command so nothing lingers in your shell:
KEIRO_BASE_URL=https://api.keirolabs.ai/v1
ANTHROPIC_BASE_URL="${KEIRO_BASE_URL%/v1}" \
ANTHROPIC_AUTH_TOKEN="$(cat ~/.claude/keiro-api-key)" \
ANTHROPIC_MODEL="eb1-preview" \
ANTHROPIC_DEFAULT_OPUS_MODEL="eb1-preview" \
ANTHROPIC_DEFAULT_SONNET_MODEL="eb1-efficient-preview" \
ANTHROPIC_DEFAULT_HAIKU_MODEL="eb1-fast-preview" \
ANTHROPIC_DEFAULT_FABLE_MODEL="eb1-frontier-preview" \
claude
Keep the secret in a file only you can read and pass it in at launch, as above. The path is yours to choose; the installer uses ~/.claude/keiro-api-key with mode 0600. Do not put the secret in a shell startup file.
This path runs without the local helper, so the /model picker does not list eb1 rows; the tier variables above still pin every tier to an eb1 model.
ANTHROPIC_BASE_URL is the API root without the /v1 suffix. Claude Code appends /v1/messages itself, so a value that already ends in /v1 produces a 404.
ANTHROPIC_AUTH_TOKEN is sent as Authorization: Bearer, the same credential form as every other public endpoint. See API auth.
Client limitations#
Requests retain at most 600 images counted across every placement (pasted images and tool-result screenshots together), with 10 MB (10,000,000 bytes) of encoded data per image, 24 MiB of encoded inline media per request (images and PDFs together), and 8 KiB per remote image URL. A request with more than 100 images can be refused before processing with the same measured error. PDF inputs allow 2 files, 8 MiB of encoded data each and 12 MiB total; filenames allow 255 characters. Replay items allow 512 KiB each (raw UTF-8 bytes for redacted thinking, serialized bytes for other replay items) and 4 MiB serialized bytes total. The content scan allows 65,536 nodes and a nesting depth of 64; it does not cap text length. These checks apply before both streaming and non-streaming responses. Media-limit errors use phrases such as “images exceed the API limit”; replay-size and content-node errors use “prompt is too long” with measured bytes or content parts, so clients such as Claude Code can automatically remove media or compact history. Depth-only failures remain count-free; these recovery phrases do not promise that an unchanged retry will succeed.
Claude Code reserves some of its interface for its own endpoint. These limits come from the client, not from Keiro:
- The
/modelpicker shows no pricing and no reasoning-effort control for eb1 models. Pick the variant that fits the task. /costprices the session at Keiro list rates. The launcher passes the four public SKU rate rows to Claude Code with--settings, replacing the unknown-model estimate Claude Code would otherwise show. Billed reasoning tokens count at the output rate there, so Keiro Usage remains the statement of record. Existing installs pick the rows up by running the installer again./usagereads rate limits from Claude's own subscription service and is unavailable for API-key sessions, includingclaude-keiro. Read limits and usage in Keiro Usage./fastand Remote Control are unavailable whileANTHROPIC_BASE_URLpoints at Keiro.- Extended thinking is not shown in the transcript. Answers arrive complete; only the intermediate display is missing.
- A hard
eb1-frontier-previewturn can think for many minutes before its first visible block. Claude Code asks for thinking, so that wait carries an empty thinking block, which its stream watchdog counts; see Silence while the model thinks. Claude Code keeps that block in the session as an empty unsigned thinking block and sends it back on later turns, which Keiro accepts. The launcher setsCLAUDE_STREAM_IDLE_TIMEOUT_MSandAPI_TIMEOUT_MSfrom Long requests. A turn with no event for longer than that is abandoned and resent without streaming. Existing installs pick this up by running the installer again. Plainclaudekeeps its defaults.
Rotate the Claude Code key#
- Create a replacement dedicated key in the console.
- Remove the old local key file.
- Run the installer again and enter the replacement secret at the prompt.
- Launch
claude-keiroand verify a harmless request. - Delete the old key in the console.
Do not pass the secret in a command argument or save it in shell history.
Remove the setup#
Setup owns exactly the files in the table above; the stock claude command and ~/.claude/settings.json are never touched. The launcher removes its own artifacts:
claude-keiro self uninstall
This deletes the launcher, its keiro-claude alias, the request helper, and the helper logs, wherever CLAUDE_CONFIG_DIR or KEIRO_BIN_DIR put them. The key file survives; the command prints the exact rm line to delete it too. If the launcher itself is already gone, remove the remaining files by hand:
rm -f ~/.local/bin/claude-keiro \
~/.local/bin/keiro-claude \
~/.claude/keiro-shim.py \
~/.claude/keiro-shim.log \
~/.claude/keiro-shim.log.1 \
~/.claude/keiro-shim-diag.log \
~/.claude/keiro-api-key
Delete the key in API keys once nothing else uses it.
Troubleshooting#
The installer's last line is its verdict. Done. after a Verified against line means the stored key answered an authenticated request during the run. could not reach <base URL> to check the key means the request did not reach the API, and could not check the key: <base URL> answered HTTP <code> means the API answered with an error. In both cases the key file was not changed: check your connection or wait a few minutes, then run the install command again. Setup incomplete: no API key stored. with a nonzero exit means the run stored nothing; save your key in a file only you can read, then run the printed --key-file command.
claude-keiro: no API key is stored yet means setup did not store a key. The launcher prints the installer command with --key-file: save your key in a file only you can read, then run that command with the file's absolute path. You can also rerun the installer from an interactive terminal and enter an active key.
command not found: claude-keiro means the launcher directory is not on your PATH. The installer names the directory and the launcher's full path; it does not edit shell startup files for you.
At startup Claude Code may print a notice that claude.ai connectors are disabled. The message comes from the Claude Code client, which shows it for any non-default endpoint; it is informational and requests to Keiro are unaffected.
If the /model picker does not show the eb1 IDs, rerun the Keiro installer and start claude-keiro again. Python is needed for the request helper, not the picker. Helper startup errors are recorded in ~/.claude/keiro-shim-diag.log.
If claude is still missing after setup, install it with npm and run the Keiro installer again.
A 401 means the stored key is missing, 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.
To find the request id for a specific response, read ~/.claude/keiro-shim.log: the helper writes one line per request with the timestamp, method, path, model, request id, and HTTP status, rotating the file near 1 MB with the previous portion kept in ~/.claude/keiro-shim.log.1. The helper never writes to the terminal while Claude Code runs; after a session with failed requests, claude-keiro prints how many there were and points at the log. Include the request id when contacting support about a response.
If the connection to Keiro drops after a request was sent, the helper sends it once more with the same idempotency key, so Keiro does not run it twice. When that second copy gets the reply, Claude Code carries on as usual. When Keiro answers that it already has the request, whether it is still running or has ended, its reply cannot reach Claude Code: the helper does not wait, and Claude Code shows at once that Keiro received the request but the connection dropped before its reply. When the helper cannot reconnect at all, the message says Keiro may have run the request. Either way, send your message again; it runs as a new turn. That request's log line also records why the first copy was lost (first_phase, first_reason, first_error), the request id of the first copy (original_request_id), and how many copies followed it (resends). Include original_request_id when contacting support about such a request.