Use eb1 with Pi

Pi is an efficiency-first, customizable coding-agent harness. Use Keiro through Pi's custom model configuration when lower context overhead, local control, and a minimal terminal workflow matter.

On this page 1 of 8

Before you configure#

  1. Open API keys.
  2. Create a dedicated key for this Pi installation.
  3. Keep the newly revealed secret available in your password manager until setup is complete.

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

Install and configure#

Install Pi with the @earendil-works/pi-coding-agent package, or run it through npx:

Install with npm Shell
npm install --global --ignore-scripts @earendil-works/pi-coding-agent@latest
# or
npx --yes @earendil-works/pi-coding-agent@latest --help

Install the provider extension below as ~/.pi/agent/extensions/keiro.js. Create an executable ~/.pi/agent/keiro-auth that reads your dedicated key from your OS credential store or secret manager and prints one token. The extension uses that same helper for discovery and inference; it never writes the token into configuration or environment variables.

On macOS, save this as ~/.pi/agent/keiro-auth (it reads the Keychain):

Save as ~/.pi/agent/keiro-auth Shell
#!/bin/sh
# Prints the Keiro key stored in the macOS Keychain. Store it once with
#   security add-generic-password -s keiro-pi -a "$USER" -w
# which asks for the key, so it never appears in your shell history.
exec security find-generic-password -s keiro-pi -a "$USER" -w

On Linux, save this instead (it reads the Secret Service through secret-tool):

Save as ~/.pi/agent/keiro-auth Shell
#!/bin/sh
# Prints the Keiro key stored in the Secret Service. Store it once with
#   secret-tool store --label="Keiro Pi key" service keiro-pi account "$USER"
# which asks for the key, so it never appears in your shell history.
exec secret-tool lookup service keiro-pi account "$USER"

Then let only you run it:

Run in the terminal Shell
chmod 700 ~/.pi/agent/keiro-auth

Remove an older providers.keiro entry from ~/.pi/agent/models.json, since that file's overrides take precedence over extension metadata. Pi waits for the extension's initial authenticated discovery before selecting a model, then uses refreshModels for subsequent catalog refreshes. Discovery failure stops startup or refresh instead of publishing stale limits. Install this extension once; catalog changes need no reinstall. Existing models.json-only setups need this one-time migration.

Save as ~/.pi/agent/extensions/keiro.js JavaScript
import { execFileSync } from "node:child_process";
import { homedir } from "node:os";
import { join } from "node:path";

const baseUrl = "https://api.keirolabs.ai/v1";
const authCommand = join(homedir(), ".pi", "agent", "keiro-auth");
const ids = ["eb1-preview", "eb1-frontier-preview", "eb1-fast-preview", "eb1-efficient-preview"];

export default async function keiro(pi) {
  async function models() {
    let output;
    try {
      // stderr is captured, not inherited, so a failing helper prints once.
      output = execFileSync(authCommand, [], {
        encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "pipe"],
      });
    } catch (error) {
      const helper = "Keiro: the key helper at " + authCommand;
      if (error.code === "ENOENT" || error.code === "EACCES") {
        throw new Error(helper + " is missing or not executable");
      }
      if (error.code === "ETIMEDOUT") throw new Error(helper + " did not finish within 5 seconds");
      if (typeof error.status === "number") {
        const detail = String(error.stderr || "").trim().split("\n")[0];
        throw new Error(helper + " failed (exit " + error.status + ")" + (detail ? ": " + detail : ""));
      }
      throw error;
    }
    const token = output.trim();
    if (!token || /\s/.test(token)) throw new Error("Keiro credential helper must return one token");
    const response = await fetch(baseUrl + "/models", {
      headers: { Authorization: "Bearer " + token },
      redirect: "error",
      signal: AbortSignal.timeout(5000),
    });
    if (response.status === 401) throw new Error("Keiro rejected the key; check the helper prints the current key");
    if (!response.ok) throw new Error("Keiro model discovery failed (HTTP " + response.status + ")");
    const payload = await response.json();
    if (!Array.isArray(payload.data)) throw new Error("Keiro model discovery returned an invalid catalog");
    return ids.map((id) => {
      const matches = payload.data.filter((entry) => entry.id === id);
      if (matches.length !== 1 || !Number.isSafeInteger(matches[0].context_window) || matches[0].context_window <= 0) {
        throw new Error("Keiro model discovery returned an invalid context window");
      }
      return {
        id, name: id, reasoning: false, input: ["text"],
        contextWindow: matches[0].context_window, maxTokens: 32000,
        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
        compat: { supportsStore: false, supportsDeveloperRole: false, supportsReasoningEffort: false },
      };
    });
  }
  let initialModels;
  try {
    initialModels = await models();
  } catch (error) {
    // Stop here with one plain line, before Pi starts without Keiro's models
    // and reports that failure again with a stack trace.
    console.error(error.message);
    process.exit(1);
  }
  pi.registerProvider("keiro", {
    baseUrl, api: "openai-completions",
    apiKey: "!" + "'" + authCommand.replaceAll("'", "'\\''") + "'",
    models: initialModels,
    refreshModels: models,
  });
}

Then start Pi on eb1:

Run in the terminal Shell
pi --provider keiro --model eb1-preview

To check the setup without opening a session, send one prompt. Pi prints the answer and exits:

Run in the terminal Shell
pi --provider keiro --model eb1-preview -p "Say hello in one sentence."

contextWindow comes from /v1/models on startup and model refresh. The generation cap is per turn. The extension leaves cost reporting at zero because discovery does not publish prices; use Keiro Usage and Logs for actual charges. This extension requires a Pi release supporting asynchronous provider factories and refreshModels; see Pi's provider contract.

Long requests#

Pi's httpIdleTimeoutMs setting is how long Pi waits for a response to start, and then for each next piece of it. The default is 300000 (five minutes). Unless retry.provider.timeoutMs is set, Pi's request timeout follows it. Set it as Long requests describes, by adding this key to ~/.pi/agent/settings.json and keeping the settings already there:

JSON payload JSON
{
  "httpIdleTimeoutMs": 3720000
}

Leave retry.provider.timeoutMs unset so it follows this value, and restart Pi after the change. A project's .pi/settings.json overrides this key, so check there too if a project sets it.

Models#

Start with eb1-preview. Switch models when the task has a clear quality, latency, or cost requirement:

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

See Models for what each model is for.

Efficiency positioning#

External benchmark evidence makes Pi a strong efficiency-oriented harness choice, especially when context volume and cost are first-order constraints. That does not make it the universal quality leader: outcome quality still depends on the selected model, task type, repository shape, and tool configuration.

Authentication#

The key is sent as Authorization: Bearer, the same credential form as every other public endpoint. See API auth. A 401 means the configured key is missing, invalid, or revoked.

Requests from Pi appear in Keiro Usage and Logs like other API traffic.

Rotate the Pi key#

  1. Create a replacement dedicated key in the console.
  2. Rotate the key in the credential source used by keiro-auth.
  3. Verify a harmless request.
  4. Delete the old key in the console.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console