Use eb1 with OpenCode
Install the opt-in opencode-keiro launcher. Plain opencode, your global packages, and your opencode.json / opencode.jsonc stay unchanged.
On this page 1 of 5
Install and configure#
Create a dedicated key on the console's API keys page. Keep the newly revealed secret available in your password manager until setup is complete. You need macOS or Linux, with bash, curl and Node 22.15 or later installed. Run this command in a project directory where you use OpenCode. Setup checks the OpenCode settings it finds there; each later launch checks the settings of the directory it starts in:
s="$(curl -fsS 'https://api.keirolabs.ai/v1/opencode/install.sh')" && bash -c "$s"
The console supplies this command using its configured API base. 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. The X-Content-SHA256 response header checks the downloaded bytes; it is not an independent signature. To read the script before you run it, download it first. -D saves the response headers in keiro-opencode.headers, so you can compare X-Content-SHA256 with shasum -a 256 keiro-opencode.sh:
curl -fsS 'https://api.keirolabs.ai/v1/opencode/install.sh' -D keiro-opencode.headers -o keiro-opencode.sh
less keiro-opencode.sh
bash keiro-opencode.sh
Setup reuses a compatible OpenCode installation from any channel. The pinned runtime is opencode-ai@1.18.11; other releases require a compatibility update. If OpenCode is absent, npm is required to install that exact release into a private directory. Setup never installs Node or npm, upgrades an external installation, runs a global npm install, or creates a plain opencode command. An incompatible external executable must be upgraded through its original installation channel. Only incompatible Keiro-managed runtimes are replaced, side by side, with the previous generation retained for rollback.
Enter the key at the hidden local prompt. Without a terminal, pass a key file instead:
s="$(curl -fsS 'https://api.keirolabs.ai/v1/opencode/install.sh')" && bash -c "$s" keiro-install --key-file /absolute/path/to/key
With a downloaded copy, run bash keiro-opencode.sh --key-file /absolute/path/to/key. The key file must be a regular file that you own, with mode 0600, holding one nonempty token (at most 4096 bytes; one final newline is allowed). Symlinks and multiline credentials are refused. --key is refused because it exposes the key in shell history and the process list.
Setup checks the key with one authenticated request to the /models endpoint. Redirects, authorization errors, throttling, malformed responses and network failures stop activation. No inference request is made. “Verified” covers authentication and configuration in the inspected directory, not future projects, plugin behavior, remote policies or completed inference.
Start with the command printed by setup:
opencode-keiro
To check the setup without opening a session, send one prompt. OpenCode prints the answer and exits:
opencode-keiro run "Say hello in one sentence."
Each launch makes an authenticated model-discovery request and applies the current context windows in a fresh configuration layer. The generation's stored opencode.json is a review snapshot; its limits do not govern launches. Discovery failure stops launch rather than using stale limits. Existing launchers need one setup rerun to receive this behavior; later catalog changes need no reinstall.
Fresh sessions select keiro/eb1-preview. An explicit --model wins; --continue and --session keep the resumed session's model. Change directory before launching; project and directory override arguments are rejected when their configuration scope cannot be inspected. Use plain opencode for administrative commands, including debug, upgrade, and remote attachment. Never run opencode debug config with a real key: it can print resolved secrets.
Files and credentials#
Setup creates the following under ${XDG_DATA_HOME:-$HOME/.local/share}/keiro/opencode:
generations/<generation>/opencode.json: the additional Keiro settings layer.generations/<generation>/manifest.jsonandrun.cjs: ownership, integrity, runtime selection and launch preflight.credentials/<opaque-id>: an owner-only 0600 credential file in a 0700 directory.runtimes/1.18.11/: a private npm prefix, only if needed.
The launcher is ${KEIRO_BIN_DIR:-$HOME/.local/bin}/opencode-keiro. The separate settings document references the key with {file:/absolute/path}. The key never appears in configuration, launcher, manifest, command arguments, or environment variables. Setup does not use KEIRO_API_KEY or auth.json as a fallback. This per-user file store is not an OS keychain: same-user processes and OpenCode plugins can read what OpenCode can read.
Running setup again with nothing new checks the key again and changes no installed file, file permission, timestamp, runtime package, or stored key. If a file's permissions have become unsafe, setup reports it and does not fix it for you. Setup uses an exclusive lock; a stale lock is not removed automatically. Confirm no setup is running before following the reported manual recovery action.
Configuration boundaries and migration#
OPENCODE_CONFIG is an additional configuration layer, not an isolated profile. In OpenCode's own precedence, project opencode.json[c] and OPENCODE_CONFIG_CONTENT override it, so setup and every launch inspect applicable local sources before resolving the managed credential. Setup and launch stop with an error, and change nothing, when they find any of these: settings that override Keiro's settings, duplicate keys, malformed JSONC, a policy that disables the Keiro provider, an unsupported custom configuration directory, or a managed or remote configuration source they cannot read. Existing opencode.json or opencode.jsonc files that use {file: or {env: substitution are refused because setup cannot inspect them without resolving the values, as is every inherited OPENCODE_* variable except OPENCODE_DISABLE_AUTOUPDATE and OPENCODE_DISABLE_MODELS_FETCH; keep plain opencode for those setups. This is not a sandbox against malicious plugins or concurrent modifications by another same-user process.
A legacy manual provider.keiro entry is a conflict, even when it looks identical. Keep your custom setup and use plain OpenCode, or deliberately remove or rename that entry yourself before rerunning setup. Setup never renames, normalizes or rewrites user files, and never adopts a legacy credential.
Rotate, roll back or remove#
- Create a new dedicated key and save it in an owner-only 0600 file.
- Rerun setup with
--key-file /absolute/path/to/replacement, using either key-file command shown above. - Setup verifies the replacement before switching the launcher. Failure leaves the previous setup active.
- Revoke the old key on the console API keys page when rollback is no longer needed.
Only active and immediately previous generations retain credentials. Rollback verifies the retained key again; a revoked key cannot be reactivated offline.
opencode-keiro self status
opencode-keiro self rollback
opencode-keiro self uninstall
The self commands run before the launcher reads your API key. Uninstall removes the launcher and reports the retained directory for deliberate removal and key revocation. Plain OpenCode remains unchanged.
Advanced: generated settings preview#
This is a read-only preview of the separate managed document, not a block to paste into user configuration. Context windows come from the public model catalog; limit.output is each model's output cap. OpenCode 1.18.11 requests at most 32,000 output tokens per turn unless OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX is set. Pi uses the same context windows. The idle settings follow Long requests, with no total timeout.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"keiro": {
"npm": "@ai-sdk/openai-compatible",
"name": "Keiro",
"options": {
"baseURL": "https://api.keirolabs.ai/v1",
"apiKey": "{file:/absolute/path/to/keiro/opencode/credentials/<opaque-id>}",
"headerTimeout": 3720000,
"chunkTimeout": 3720000
},
"models": {
"eb1-preview": {
"name": "eb1-preview",
"limit": { "context": 400000, "output": 128000 }
},
"eb1-frontier-preview": {
"name": "eb1-frontier-preview",
"limit": { "context": 869811, "output": 128000 }
},
"eb1-fast-preview": {
"name": "eb1-fast-preview",
"limit": { "context": 400000, "output": 128000 }
},
"eb1-efficient-preview": {
"name": "eb1-efficient-preview",
"limit": { "context": 400000, "output": 128000 }
}
}
}
}
}
See Models, API auth, and Usage and billing.