pi-ollama-keyring

Ollama cloud provider for pi-coding-agent with multi-key rotation, live model discovery, and persistent key-pool management.

What makes this different

The official @0xkobold/pi-ollama package supports a single API key and a stale hardcoded model list.

pi-ollama-keyring was built for people running multiple Ollama cloud API keys who need:

• a live model inventory pulled directly from their account
• automatic key rotation when a key hits quota or rate limits
• manual key selection that survives restarts
• full tool-calling and thinking support through Pi

Installation

pi install npm:pi-ollama-keyring

Or add to your global ~/.pi/agent/settings.json:

{
  "packages": ["pi-ollama-keyring"]
}

Configuration

Add your keys and settings to ~/.pi/agent/settings.json:

{
  "pi-ollama": {
    "cloudUrl": "https://ollama.com",
    "apiKeys": [
      "key-1",
      "key-2",
      "key-3"
    ],
    "activeKeyIndex": 0
  }
}

A single key also works:

{
  "pi-ollama": {
    "apiKey": "your-key-here"
  }
}

Environment variables

export OLLAMA_API_KEY="your-key"
export OLLAMA_API_KEYS="key-1,key-2,key-3"
export OLLAMA_HOST_CLOUD="https://ollama.com"
export OLLAMA_ACTIVE_KEY_INDEX="0"

Config precedence (highest to lowest)

1. Environment variables
2. pi.settings runtime API
3. .pi/settings.json (project-local)
4. ~/.pi/agent/settings.json (global)

Features

• ☁️ Ollama Cloud — talks directly to api.ollama.com via the ollama npm client
• 🔑 Multi-key pool — load as many API keys as you have
• 🔁 Auto-rotation — on quota, rate-limit, or auth failure the key pool is walked until a working key is found
• 💾 Persistent rotation — manual key changes write activeKeyIndex back to your settings file so the active key survives restarts
• 🎯 Live model discovery — model list is fetched from your actual Ollama cloud account at startup, not a stale hardcoded list
• 📊 Accurate context lengths — uses /api/show for real context window sizes
• 👁️ Vision detection — detected from capabilities and model name
• 🧠 Thinking/reasoning — native support for models that expose a thinking block
• 🛠️ Tool calling — Pi tools work end-to-end through the native Ollama chat stream
• 🔄 Manual refresh — re-fetch the cloud model list any time with /ollama-refresh

Commands

Command	Description
/ollama-status	Show cloud connection status and active key
/ollama-models	List all discovered cloud models
/ollama-refresh	Re-fetch the live model inventory
/ollama-info MODEL	Show details for a specific model
/ollama-keys	Show masked key-pool status
/ollama-rotate	Rotate to the next key and persist the change
/ollama-use-key N	Activate a specific key by 1-based index and persist

How key rotation works

Keys are stored in an ordered pool. On startup, the active key starts at activeKeyIndex (default 0).

Automatic rotation happens during any cloud request when a response matches a quota or rate-limit pattern:

• HTTP 429, 402, 401, 403, 5xx
• Body containing quota, rate limit, unauthorized, payment required, etc.

The pool is walked from the current key through all remaining keys until a working one is found. If all keys are exhausted the error is surfaced to Pi.

Manual rotation via /ollama-rotate or /ollama-use-key N additionally writes activeKeyIndex back to ~/.pi/agent/settings.json so the choice persists across restarts.

Provider name

Models are registered under provider ollama-cloud:

ollama-cloud/minimax-m2.7
ollama-cloud/kimi-k2.5
ollama-cloud/gpt-oss:20b

Use them in Pi like any other provider:

pi --provider ollama-cloud --model gpt-oss:20b

Or add to enabledModels for Ctrl+P cycling:

{
  "enabledModels": [
    "ollama-cloud/minimax-m2.7",
    "ollama-cloud/kimi-k2.5",
    "ollama-cloud/gpt-oss:20b"
  ]
}

Model display

Each model shows source, vision, and reasoning badges plus context size:

☁️ 👁️ 🧠 kimi-k2.5 · 1.04T · 262K ctx
☁️ 🧠 minimax-m2.7 · 230B · 200K ctx
☁️ gpt-oss:20b · 13.8B · 128K ctx

License

MIT