Cài đặt Pi

This guide shows how to run Pi (@earendil-works/pi-coding-agent) with Aiberm as a custom OpenAI-compatible provider. Pi is an extensible terminal AI agent: give it a goal and a working folder, and it can inspect files, run commands, edit code, and work through multi-step tasks.

Aiberm exposes an OpenAI-compatible /v1 API. For Pi that is a supported protocol, so you do not need a provider extension. Add the endpoint in models.json. After setup, one Aiberm API key can reach Claude, GPT, Gemini, DeepSeek, Kimi, MiniMax, GLM, Grok, and the rest of the models on Aiberm.

What is Pi?

Pi is an open-source agent harness from Earendil Works. It ships powerful defaults but skips features such as sub-agents and plan mode. You can extend it with extensions, skills, prompt templates, and themes, or bundle those as Pi packages.

Typical entry points:

• Interactive TUI: run pi in a project directory
• One-shot jobs: pi --print "summarize the README"
• JSON / RPC / TypeScript SDK: for scripts and embeddings

Official project:

• Homepage: pi.dev
• Docs: documentation index
• Source: github.com/earendil-works/pi
• npm: @earendil-works/pi-coding-agent

Prerequisites

• An Aiberm account (Sign up)
• An Aiberm API key (Get your key)
• Node.js 22.19 or newer (the official installer can install it if needed)
• A terminal on macOS, Linux, or Windows

Install

macOS / Linux

The official installer pins dependencies and updates Pi with pi update:

curl -fsSL https://pi.dev/install.sh | sh

Or install from npm (this does not pin transitive dependencies):

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Nix users can install the latest stable release from the flake:

nix profile add github:earendil-works/pi/stable

pi update cannot update a Nix install of Pi itself. Use nix profile upgrade pi.

Windows

powershell -c "irm https://pi.dev/install.ps1 | iex"

Or npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

On native Windows, install Git for Windows so Pi’s bash tool can run. You can also install Pi inside WSL using the Linux instructions. See Windows Setup.

Verify the install

pi --version

Why models.json instead of /login?

Pi already includes Anthropic, OpenAI, Gemini, OpenRouter, and other providers. /login openai or /login anthropic talks to those official endpoints, not Aiberm.

Aiberm is an OpenAI-compatible gateway. The supported integration is to add a compatible endpoint in models.json. Write a custom provider extension only when the service needs an unsupported protocol or login flow. Aiberm does not.

Configure the Aiberm provider

User-level config lives in ~/.pi/agent by default (override with PI_CODING_AGENT_DIR). Custom models go in:

If you prefer a GUI editor over Vim:

• macOS: Open Finder, press Shift + Command + G, enter ~/.pi/agent, and press Return. Create models.json if it is missing.
• Windows: In File Explorer, type %USERPROFILE%\.pi\agent in the address bar and press Enter.

Save the file (Command + S / Ctrl + S). Opening /model in interactive mode reloads models.json. After editing settings.json or other resources, run /reload inside Pi.

Recommended configuration

Create or edit models.json:

{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "aiberm": {
      "name": "Aiberm",
      "baseUrl": "https://aiberm.com/v1",
      "api": "openai-completions",
      "apiKey": "$AIBERM_API_KEY",
      "models": [
        { "id": "claude-sonnet-5-5", "name": "Claude Sonnet 5.5", "reasoning": true, "input": ["text", "image"] },
        { "id": "claude-opus-5-5", "name": "Claude Opus 5.5", "reasoning": true, "input": ["text", "image"] },
        { "id": "anthropic/claude-haiku-5.5", "name": "Claude Haiku 5.5", "reasoning": true, "input": ["text", "image"] },
        { "id": "openai/gpt-5.5", "name": "GPT-5.5", "reasoning": true, "input": ["text", "image"] },
        { "id": "gemini-3.8-flash", "name": "Gemini 3.8 Flash", "reasoning": true, "input": ["text", "image"] },
        { "id": "google/gemini-3.1-pro", "name": "Gemini 3.1 Pro", "reasoning": true, "input": ["text", "image"] },
        { "id": "deepseek-v4.1-flash", "name": "DeepSeek V4.1 Flash" },
        { "id": "grok-4.7", "name": "Grok 4.7", "reasoning": true },
        { "id": "kimi-k3", "name": "Kimi K3" },
        { "id": "qwen3.8-max", "name": "Qwen 3.8 Max" }
      ]
    }
  }
}

Put the Aiberm API key in the environment that launches Pi (do not commit the real key):

macOS / Linux:

export AIBERM_API_KEY="sk-your-aiberm-api-key"

To persist it, add the same line to ~/.zshrc or ~/.bashrc, then open a new terminal.

Windows PowerShell (current user, persistent):

[System.Environment]::SetEnvironmentVariable('AIBERM_API_KEY', 'sk-your-aiberm-api-key', 'User')

Open a new terminal and confirm with echo $env:AIBERM_API_KEY.

Field reference

apiKey and header values accept:

• $AIBERM_API_KEY or ${AIBERM_API_KEY}: environment variable
• sk-...: plaintext (protect the file; do not commit it)
• !security find-generic-password -ws 'aiberm': command output
• $$ for a literal $, $! for a literal leading !

Store the key in models.json (optional)

Useful for a local trial. The key is stored in plaintext:

{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "aiberm": {
      "name": "Aiberm",
      "baseUrl": "https://aiberm.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-your-aiberm-api-key",
      "models": [
        { "id": "claude-sonnet-5-5", "name": "Claude Sonnet 5.5" }
      ]
    }
  }
}

Do not commit this file or share it.

Set a default model

In ~/.pi/agent/settings.json:

{
  "$schema": "https://pi.dev/schemas/settings.schema.json",
  "defaultProvider": "aiberm",
  "defaultModel": "claude-sonnet-5-5"
}

Or open /model, select a model, and press Ctrl+S to save it as the default for new sessions. A session that already sent a request keeps the model recorded in its own log.

List every Aiberm model

The sample list above is a curated subset. The catalog changes; confirm IDs from the console or:

curl -H "Authorization: Bearer sk-your-aiberm-api-key" \
     https://aiberm.com/v1/models | jq -r '.data[].id'

Add the IDs you need to the models array. Opening /model reloads the file. See the Models List and Aiberm Pricing.

Use Pi with Aiberm

Start Pi in the folder it should work in:

cd /path/to/project
pi

In the TUI:

/model

Choose Aiberm, then a model. From the shell:

pi --provider aiberm --model claude-sonnet-5-5
pi --list-models aiberm

Send a real task (for example, explain the current repository). The footer should show provider aiberm and the selected model.

Thinking level:

/thinking

This only matters when the model has "reasoning": true in models.json and the upstream model actually supports thinking.

One-shot:

pi --provider aiberm --model claude-sonnet-5-5 --print "Summarize this repository"

Resume the latest session for the same folder:

pi --continue

Credential order

When several sources exist for a provider, Pi uses:

1. Runtime --api-key (not persisted; requires --model or --models)
2. A stored credential in ~/.pi/agent/auth.json
3. apiKey from models.json
4. Built-in provider environment variables or ambient cloud credentials

A custom aiberm provider does not automatically read OPENAI_API_KEY or ANTHROPIC_API_KEY. Use models.json apiKey (prefer $AIBERM_API_KEY), or:

pi --provider aiberm --model claude-sonnet-5-5 --api-key "sk-your-aiberm-api-key"

Vision and thinking models

A model you type by hand is treated as text-only until you say otherwise. For Claude / GPT / Gemini vision models, set "input": ["text", "image"] on that entry (see the recommended config).

For thinking models, set "reasoning": true, then use /thinking (off, minimal, low, medium, high, xhigh, max). Pi clamps unsupported levels to what the model can do.

Do not turn on compat flags just because an endpoint advertises OpenAI compatibility. Enable them only after you confirm a real request or response difference.

Troubleshooting

Aiberm does not appear in /model

• models.json must include a non-empty providers.aiberm.models list.
• Credentials must resolve. Custom models can load from the file but stay hidden until Pi can resolve a key.
• Opening /model reloads the file. If it is still missing, quit and start pi again.
• Validate the JSON (for example with jsonlint).

401 Unauthorized

• Check the key at Aiberm Console.
• baseUrl must be https://aiberm.com/v1 (include /v1).
• If you use $AIBERM_API_KEY, run echo $AIBERM_API_KEY in the same shell that starts Pi (Windows: echo $env:AIBERM_API_KEY). Environment variables apply only to that process and its children.
• Do not paste an Aiberm key into the built-in openai / anthropic /login flows.

Model not found

Aiberm model IDs change. Re-query /v1/models and update the id fields. The ID must match the API exactly, including prefixes such as google/ or deepseek/.

Requests still go to OpenAI or Anthropic

You authenticated a built-in provider. /logout those official accounts, use the aiberm entry in models.json, and pick a model under Aiberm in /model.

Image refused before sending

The model has no image modality. Add "input": ["text", "image"], then start a new session. An attached image stays in the old session log.

Config edits do not apply

/model reloads models.json. Changes to settings.json, instructions, or extensions need /reload. Existing sessions keep the model already written in their log. A new default only affects new sessions.

Where the files live

Notes

• Run Pi in a dedicated project folder. The working directory controls file discovery, AGENTS.md, and session grouping.
• Pi does not ask before every tool call. Use version control or backups for important work.
• For more CLI flags, see pi --help or the official Command Line page.

Links

• Pi homepage
• Pi on GitHub
• Official: configure a compatible endpoint
• Aiberm Console
• Aiberm Models List
• Aiberm Pricing