Bifrost AI Gateway provider for pi

A pi provider for the Bifrost AI Gateway. It discovers models from Bifrost and sends requests through Bifrost's OpenAI Chat Completions integration.

Installation

Install the published package with pi:

pi install npm:pi-bifrost-provider

Use pi install -l npm:pi-bifrost-provider instead to install it only for the current project. You can also try the package for one session without installing it:

pi -e npm:pi-bifrost-provider

The package runs with your user's permissions. Review its source before installing it, as you would any pi extension.

Usage

A running Bifrost instance with at least one model provider configured is required.

Interactive setup (recommended)

Start pi after installing the package, then use pi's standard login flow:

pi
/login bifrost

Pi prompts for:

1. Bifrost URL — required, for example http://localhost:8080
2. API key — optional
3. Virtual key — optional

The connection is stored in Pi's credential store. Model discovery runs during login, and the resulting model catalog is persisted for future sessions. Run /login bifrost again to change the connection.

Then select a bifrost/* model with /model, or start directly with one:

pi --provider bifrost --model 'anthropic/claude-*'

Manual setup

Configure the provider with environment variables or CLI options:

Using environment variables:

export BIFROST_URL=http://localhost:8080
export BIFROST_API_KEY=your-api-key          # optional
export BIFROST_VIRTUAL_KEY=sk-bf-...         # optional

pi

Or passing options directly:

pi \
  --bifrost-url http://localhost:8080 \
  --bifrost-api-key your-api-key \
  --bifrost-virtual-key sk-bf-...

CLI options override environment variables. Stored /login credentials take precedence over ambient configuration. Environment variables are recommended for secrets because command-line values may be visible in shell history and process listings.

When a virtual key is supplied, model discovery only returns models allowed by that key.

URL behavior

For an instance URL such as http://localhost:8080, the extension uses:

• http://localhost:8080/openai/v1/models for model discovery
• http://localhost:8080/openai/v1/chat/completions for inference

If BIFROST_URL already ends in /v1 (for example, http://localhost:8080/v1), it is used as-is. This permits Bifrost's unified OpenAI-compatible endpoint and reverse-proxy mounts.

Authentication combinations

• Neither key: keyless Bifrost instance.
• API key only: Bearer authentication.
• Virtual key only: governance/routing via x-bf-vk without a bogus Authorization header.
• Both: Bearer authentication plus x-bf-vk, as required when Bifrost inference authentication and governance are both enabled.

You can temporarily override BIFROST_API_KEY with Pi's --api-key option. The virtual key still comes from BIFROST_VIRTUAL_KEY.

Model metadata

The provider maps Bifrost's model-list response into Pi model definitions, including context/output limits, text/image input support, reasoning efforts, and token pricing when Bifrost reports those fields. Models that advertise only non-chat methods (for example, embeddings) are omitted.

Bifrost often returns only id, object, owned_by, and created — for OpenAI-compatible providers it drops upstream metadata such as context_length and max_output_tokens (maximhq/bifrost#4301 tracks preserving it). Without those fields a model would be registered with Pi's conservative 128k/8k defaults, so the provider fills the gaps from the models.dev catalog:

• Bifrost values always win when present; the catalog only replaces the fallback defaults.
• Lookups strip the gateway prefix, so CommandCode/claude-opus-5-5 matches claude-opus-5-5, and ignore :free tags and -YYYYMMDD suffixes.
• The catalog is fetched at most once a day and cached under ~/.cache/pi-bifrost-provider/models-dev.json. An unreachable catalog falls back to a stale cache and then to the defaults, and never fails discovery.
• Models that end up on the defaults anyway are reported once per session through Pi's notification UI, with a pointer to modelOverrides.

To pin exact limits for one model, override them in ~/.pi/agent/models.json; the provider is not involved in that path:

{
  "providers": {
    "bifrost": {
      "modelOverrides": {
        "CommandCode/claude-opus-5-5": { "contextWindow": 1000000, "maxTokens": 128000 }
      }
    }
  }
}

Developing

Install dependencies and run the static checks:

npm install
npm run check

Running the extension locally

From the repository root, load the TypeScript source directly instead of installing the published package:

pi -e ./index.ts

Use /login bifrost in that session to configure a connection, or provide the environment variables and CLI options documented above. Restart the command after editing index.ts to load your changes.

Testing

Both test modes run the same complete *.test.ts suite. Tests that exercise a backend select it from BIFROST_TEST_MODE; pure unit tests run unchanged in both modes.

Mock mode

npm test

The runner sets BIFROST_TEST_MODE=mock. Backend-aware discovery, login, and streaming scenarios use in-process fetch mocks, so no external processes or provider credentials are needed.

Integration mode

npm run test:integration

The runner performs the complete fixture lifecycle:

1. Starts aimock with test/fixtures/aimock.json.
2. Writes a temporary, file-only Bifrost configuration that routes OpenAI requests to aimock.
3. Starts Bifrost with npx -y @maximhq/bifrost.
4. Runs the same full test suite with BIFROST_TEST_MODE=integration and BIFROST_TEST_URL set to the fixture.
5. Stops both process trees and removes the temporary app directory, even when tests fail.

Backend-aware scenarios in test/provider.test.ts therefore run through the real Pi provider → Bifrost → aimock path instead of a separate smoke test.

The fixture uses available ephemeral ports by default. Its bind addresses, client-visible hosts, ports, packages, and startup behavior are configurable:

For example:

BIFROST_TEST_BIND_HOST=0.0.0.0 \
BIFROST_TEST_HOST=127.0.0.1 \
BIFROST_TEST_PORT=18080 \
AIMOCK_TEST_PORT=14010 \
BIFROST_TEST_PACKAGE=@maximhq/bifrost@1.6.3 \
AIMOCK_TEST_PACKAGE=@copilotkit/aimock@1.38.0 \
npm run test:integration

To keep the managed fixture running for manual /login bifrost testing, use:

npm run fixture

The command prints its dynamically selected BIFROST_TEST_URL and keeps the fixture alive until Ctrl+C. A standalone zero-config Bifrost instance is available with:

npm run bifrost

The first fixture run requires network access for npx; subsequent runs can reuse npm's cache.

Contributing

AI policy and usage disclosure

This repository welcomes both AI-assisted and agent-generated contributions. All code changes will receive final review from at least one human.

For any commit, pull request, or issue involving AI, disclose:

• Whether the work was AI-assisted or agent-generated.
• The model used.
• The agent harness or other AI tooling used, if applicable.

You are encouraged to also including the initial prompt or full conversation history, but this is optional.

LICENSE

MIT. See LICENSE.