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.

Copy Page https://docs.keirolabs.ai/claude-code.md

Before you install#

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

1. Open API keys.
2. Create a dedicated key for this Claude Code installation.
3. Keep the newly revealed secret available in your password manager until setup is complete.
4. Run the installer from an interactive terminal so it can prompt without echoing the secret.

Install and configure#

Run the installer:

1

bash -c "$(curl -fsS 'https://api.keirolabs.ai/v1/claude-code/install.sh')"

The command substitution downloads the whole script before bash starts, and the script runs its main function only on its final line, so a truncated download 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:

1
2
3
4

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 it by path — the installer never accepts the secret itself as a command argument:

1

bash keiro-claude-code.sh --key-file <path-to-key-file>

The key check fails the install — without storing anything — when the API answers 401 (the key is invalid or revoked) or 403 (the key lacks access). If the API cannot be reached, or curl is missing, the installer notes that the key is unverified and continues.

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 line is the verdict: Verified against the API followed by Done. when the stored key answered the check, Done (key stored, not verified) when the check could not run, or — if no key is stored by the end of a run — the manual store command, Setup incomplete: no API key stored., and a nonzero exit.

Launch Claude Code#

1

claude-keiro

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:

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, and a request carrying one is rejected.

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; gateway model discovery is not required. Client requests and Keiro's Usage and Logs pages use the same bare eb1-* IDs.

The launcher declares the default model's 400,000-token context window to Claude Code with CLAUDE_CODE_MAX_CONTEXT_TOKENS; it applies to the whole session, including eb1-frontier-preview. Auto-compaction remains enabled unless you have disabled it in your own settings or environment. Claude Code reserves space for output and compaction before reaching that 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.

When python3 is 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. Without Python or the helper, the launcher connects directly to Keiro with the same picker rows and context window.

Files written by setup#

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:

1
2
3

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:

1
2
3
4
5
6
7
8
9
10

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. The model a request routes to can accept fewer (100 images on 200k-context Claude models); the request is then refused before dispatch 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 /model picker shows no pricing and no reasoning-effort control for eb1 models. Pick the variant that fits the task.
• /cost prices 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.
• /usage reads rate limits from Claude's own subscription service and is unavailable for API-key sessions, including claude-keiro. Read limits and usage in Keiro Usage.
• /fast and Remote Control are unavailable while ANTHROPIC_BASE_URL points at Keiro.
• Extended thinking is not shown in the transcript. Answers arrive complete; only the intermediate display is missing.
• A hard eb1-frontier-preview turn can think for many minutes before its first visible block, with nothing on screen. Claude Code would normally abandon a stream after five silent minutes and retry without streaming, so claude-keiro sets its stream and request timeouts (CLAUDE_STREAM_IDLE_TIMEOUT_MS, API_TIMEOUT_MS) to 62 minutes: two minutes past the longest turn Keiro allows, so Keiro's own limit always ends a turn first. Existing installs pick this up by running the installer again. Plain claude keeps its defaults; only sessions started with claude-keiro get these.

Rotate the Claude Code key#

Do not pass the secret in a command argument or save it in shell history.

1. Create a replacement dedicated key in the console.
2. Remove the old local key file.
3. Run the installer again and enter the replacement secret at the prompt.
4. Launch claude-keiro and verify a harmless request.
5. Delete the old key in the console.

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:

1

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:

1

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. Done (key stored, not verified) means the files are in place but the check could not run — the API was unreachable or curl is missing — so the first launch is where an invalid key would surface. Setup incomplete: no API key stored. with a nonzero exit means the run stored nothing; use the printed store command or --key-file, then rerun the installer.

claude-keiro: missing key file means setup did not store a key. Run the installer from an interactive terminal and enter an active key, or rerun it with --key-file.

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.

Related pages#

• Agent-driven setup
• API keys
• API auth
• Models
• Messages API
• Usage and billing
• Claude Code gateway documentation