Skip to main content

Connect Pi with Zeldoc.ai

Pi is a minimal, open source coding agent for the terminal that you extend with your own tools, commands, and providers. There are two ways to connect it to Zeldoc.ai:

Prerequisites​

Option A: install the provider package​

zeldoc-pi-provider is an open source Pi package that registers Zeldoc.ai as a provider and discovers your model catalog. Install it with Pi's package manager:

pi install npm:zeldoc-pi-provider

Then give it your API key. Either export it before starting Pi:

export ZELDOC_API_KEY=your-api-key

or store it in Pi: start pi, run /login, pick Zeldoc.ai, and paste the key.

That's it. Start pi, run /model, and pick a model under Zeldoc.ai. ZDev is available right away; the rest of the models your key can access appear a few seconds after startup and are remembered between sessions. Thinking levels are wired up per model, so /thinking offers the effort levels each model actually supports.

Too many models in the picker?

Zeldoc.ai's router exposes many models. Image, audio, and embedding models are hidden automatically. To narrow the list further, add substrings to match in ~/.pi/agent/settings.json:

{
  "zeldoc.models": ["zdev"]
}

Each entry is a substring: "zdev" matches every ZDev model.

If you'd rather not install an extension, use option B instead.

Option B: declare the provider in models.json​

Create or edit ~/.pi/agent/models.json and add a zeldoc provider:

{
  "providers": {
    "zeldoc": {
      "baseUrl": "https://api.zeldoc.ai/v1",
      "api": "openai-completions",
      "apiKey": "$ZELDOC_API_KEY",
      "models": [
        {
          "id": "zdev",
          "name": "ZDev",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 131072,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

A few notes on the fields:

  • api — openai-completions uses Zeldoc.ai's /chat/completions endpoint, which is the most compatible option. Pi also supports openai-responses and anthropic-messages, and Zeldoc.ai serves both.
  • apiKey — The $ prefix tells Pi to read the key from an environment variable. You can also use !command to fetch the key from a secret manager, for example "!op read 'op://vault/item/credential'".
  • reasoning — Enables Pi's thinking levels for the model. ZDev accepts low, medium, high, and max.
  • cost — Pi uses these numbers for its usage display. Zeldoc.ai doesn't bill per token, so leave them at zero.

Set the environment variable before starting Pi:

export ZELDOC_API_KEY=your-api-key
Persist the environment variable

Add the export line to your shell profile (e.g. ~/.bashrc or ~/.zshrc) so the key is available in every new terminal session.

Pi reloads models.json every time you open the model picker, so there's no restart needed. Start pi, run /model, and pick ZDev under the zeldoc provider.

Make ZDev the default​

Whichever option you chose, you can make ZDev the default for every session by adding these keys to ~/.pi/agent/settings.json:

{
  "defaultProvider": "zeldoc",
  "defaultModel": "zdev",
  "defaultThinkingLevel": "high"
}

Use other Zeldoc.ai models​

With the provider package, every chat model from your Zeldoc.ai model list is registered for you. With models.json, add more entries to the models array — see list your available models. The id must match the model ID exactly as Zeldoc.ai reports it, for example zdev-2.