How to Use Kimi K3 in pi (One JSON Block)

pi is the minimalist terminal coding agent from earendil-works (you may know it by its old name, pi-mono): MIT-licensed, four built-in tools, no subscription, no seat wall. It is also the quiet heavyweight of the coding-agent world — north of 100k GitHub stars, and one of the largest Kimi K3 consumers on OpenRouter. Unlike tools that sync a provider catalog, pi puts the integration point in your hands: any OpenAI-compatible endpoint becomes a first-class provider through one JSON block in ~/.pi/agent/models.json.

The short version — create ~/.pi/agent/models.json with this block, then export WALLABY_API_KEY=sk-your-wallaby-key and run pi:

{
  "providers": {
    "wallaby": {
      "baseUrl": "https://api.wallabytoken.com/v1",
      "apiKey": "$WALLABY_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "kimi-k3",
          "name": "Kimi K3 (Wallaby)",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 131072
        }
      ]
    }
  }
}

That's the whole setup — no plugin, no fork, no waiting for a registry to list anyone. The rest of this guide is that block field by field, the install gotchas we actually hit, and the billing-side verification. Disclosure: Wallaby Token sells API access to kimi-k3, and the endpoint configured below is ours.

Update (2026-11-05): Kimi K3.1 Pro is live on Wallaby. Use kimi-k3.1-pro wherever this guide asks for the model ID; the endpoint and steps are unchanged. K3.1 Pro is $1.80 / $9.00 per 1M input/output ($0.18 cached), 10% off list. K3 remains available at $2.55 / $12.75 ($0.255 cached). In the JSON block, set "model": "kimi-k3.1-pro" (or add a second model entry). Full K3.1 Pro setup and pricing →

What you need

• A Wallaby Token account (create one at wallabytoken.com; new accounts receive $0.50 in free credit) and an API key from the console
• Node.js 22.19 or later (node --version to check — on an older Node, npm silently installs the legacy pi line; see Step 1)
• Five minutes

Setting this up for a team? One account is enough — see the For teams section at the end.

Step 1: Install pi

npm install -g @earendil-works/pi-coding-agent
pi --version

Three real gotchas from our install runs:

1. Check the version you actually got. Current pi (0.86.x) requires Node ≥ 22.19. On an older Node — ours was 22.17 — npm silently resolves the legacy-node20 line instead (0.74.x), with no error. If pi --version prints something old, upgrade Node first (nodejs.org LTS), then reinstall. You can also pin explicitly: npm install -g @earendil-works/pi-coding-agent@latest.
2. The package moved. It used to live at @mariozechner/pi-coding-agent, deprecated and frozen at 0.73.1. Older blog posts still reference it — make sure you install the @earendil-works/ scope. (The project moved from badlogic/pi-mono to earendil-works/pi.)
3. First launch downloads two helpers, and the UI may look frozen. On first run pi fetches fd and ripgrep into ~/.pi/agent/bin/ from GitHub releases. In our run the "Downloading..." line never cleared even though the files had already landed — on a slow network this looks like a hang. If it sits there: Ctrl+C, run pi again; the binaries are detected and startup proceeds. (ls ~/.pi/agent/bin/ confirms both are in place.)

Step 2: Add the provider block

Create or edit ~/.pi/agent/models.json:

{
  "providers": {
    "wallaby": {
      "name": "Wallaby (Kimi K3)",
      "baseUrl": "https://api.wallabytoken.com/v1",
      "apiKey": "$WALLABY_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "kimi-k3",
          "name": "Kimi K3 (Wallaby)",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 131072,
          "cost": { "input": 2.55, "output": 12.75, "cacheRead": 0.255, "cacheWrite": 2.55 }
        }
      ]
    }
  }
}

What each field is actually doing:

• apiKey: "$WALLABY_API_KEY" — the $ prefix means "read this environment variable," so the key itself never sits in the file. pi's models documentation calls this environment interpolation — "$ENV_VAR" or "${ENV_VAR}" "uses the value of the named variable" — and literals or !command shell-outs work too.
• api: "openai-completions" — tells pi to use its built-in OpenAI-compatible streaming. No custom code anywhere in this setup.
• contextWindow: 1048576 — the full 1M-token context, not the 256k cut-down variant.
• input: ["text", "image"] — image input is live on this endpoint. Inside pi, paste a screenshot with Ctrl+V (not Cmd+V — pi hooks Ctrl+V itself; the pi README keybindings table lists "Ctrl+V to paste an image or text (Alt+V on Windows), or drag images onto terminal") and the model answers about the actual pixels.
• No compat flags — snippets for other providers sometimes set supportsDeveloperRole or supportsReasoningEffort. Verified on pi 0.86.1: this endpoint needs neither. Add flags only if you hit a real error.
• cost — only feeds pi's local spend display. It changes nothing on the billing side; your console's itemized usage log is the source of truth.

Step 3: Set your key and run

export WALLABY_API_KEY=sk-your-wallaby-key
cd your-project
pi

Add the export line to your shell's startup file so it survives new terminals — ~/.zshrc for zsh, ~/.bash_profile for bash (check with echo $0; on this machine it was bash, and a PATH line written to the zsh file did exactly nothing).

Inside pi, type /model (or Ctrl+L). With only one provider configured the list has a single entry — kimi-k3 [wallaby], captioned "Kimi K3 (Wallaby)". Enter selects it for the session; Ctrl+S pins it as the default. The models file is re-read every time you open the picker, so config edits apply without a restart.

Verified on pi 1.0.4 (October 2026): the same block works unchanged on the current pi — /model lists kimi-k3 [wallaby], and Ctrl+S still pins it as the default. New in 1.0: the picker only lists providers whose key resolves, so export WALLABY_API_KEY before you launch pi. If kimi-k3 is missing from the list, that is usually why.

Three commands worth knowing:

Verify on the billing side

A working reply is legs one and two of the test. Leg three: open your console's Usage Logs. Seconds after the request, there is a line with the model, token counts, and cost, itemized immediately.

Our verification run for this guide (pi 0.86.1, one "write a palindrome function" task): pi's status bar reported $0.014 with a 93.8% cache-hit rate, and the console logged three itemized consume lines — one per agent loop iteration — summing to $0.0138. The client-side display and the server-side bill agree to the rounding digit; the log is the source of truth.

A follow-up screenshot question ("what is in this picture?", ~7.7k input tokens with the image) brought total session spend to $0.037. The whole test suite costs about four cents — the $0.50 trial credit covers it ten times over. The status bar only meters active turns, though; the pause tax covers what still leaks from a pi session between prompts. pi is also one of several terminal setups we maintain — the Kimi K3 CLI hub has the rest in one table.

Troubleshooting

"pi --version" shows 0.74.x right after install — why?

Your Node is older than 22.19, so npm silently resolved the legacy-node20 line (0.74.x) — no error, no warning. Upgrade Node (nodejs.org LTS), then reinstall, or pin explicitly with npm install -g @earendil-works/pi-coding-agent@latest. Details in Step 1, gotcha 1.

First run hangs on "fd not found. Downloading..." — why?

pi downloads its fd and ripgrep helpers from GitHub releases on first launch, and the status line may never refresh even after the files land. Ctrl+C and relaunch; ls ~/.pi/agent/bin/ confirms both binaries are in place.

"command not found: pi" after install — why?

Your npm global bin directory isn't on your shell's PATH. Check that the output of npm bin -g appears in your PATH — and that you edited the startup file your shell actually reads (echo $0; on our machine it was bash, not zsh).

kimi-k3 doesn't appear in /model — why?

Almost always a JSON syntax error in models.json. Validate with python3 -m json.tool < ~/.pi/agent/models.json, fix what it flags, and reopen the picker — pi re-reads the file every time you open /model. On pi 1.0.4 there is a second cause: the picker only shows providers whose apiKey resolves, so if WALLABY_API_KEY was not exported in the shell that launched pi, the entry stays hidden. Export it in that shell and relaunch.

Config edits don't seem to take effect — why?

Not a bug: pi re-reads models.json when you open the /model picker, so just reopen it. No restart needed.

Older tutorials say @mariozechner/pi-coding-agent — is that still right?

No. That package scope is deprecated and frozen at 0.73.1. Install @earendil-works/pi-coding-agent — the project moved from badlogic/pi-mono to earendil-works/pi.

Rolling out to a team

pi's user-level config makes per-developer setup trivial, and the account side carries the team mechanics: one prepaid balance as a hard ceiling on the whole team's spend, one named key per developer with its own dollar cap and optional expiry, and usage logs itemized per key so per-person cost attribution is the default view, not a spreadsheet project. There are no seat fees: adding a teammate costs exactly their token usage. The full walkthrough is in One endpoint, one bill.

Pricing

Per 1M tokens, as of September 2026 (current rates always on the pricing page):

The $0.50 trial credit covers this entire guide many times over.

If you prefer a zero-config path over editing one JSON file, the OpenCode route pulls the same model from a synced catalog with a single environment variable — see Kimi K3 in OpenCode.

Get started

Create an account at wallabytoken.com, mint a key, paste one JSON block, export one variable. pi's whole philosophy is that your tools belong to you — this is the one provider setup that actually respects that. Prefer no config files at all? The same setup now installs as an npm package in a single command, on Windows and Mac alike: Run pi with Kimi K3 on Windows or Mac.