Pi

Pi, the coding agent from earendil-works/pi, connects to TokenFlux as a custom OpenAI-compatible provider. Requests are charged to your TokenFlux balance.

This guide was tested with Pi 1.0.4 and gpt-6-luna for streaming replies.

Before you startCopy Anchor Link

1. Start with Pi installed. Configuration details are in the official Pi model guide and models.json reference.
2. Create and copy a key on the web app’s API keys page. The full key is shown only once.
3. Check that your balance is above zero on Billing.
4. Copy a model ID from Models and pricing and check its supported protocols.

Add TokenFlux to models.jsonCopy Anchor Link

Set the key in Bash or Zsh:

export TOKENFLUX_API_KEY="YOUR_TOKENFLUX_KEY"

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

{
  "providers": {
    "tokenflux": {
      "baseUrl": "https://tokenflux.ai/v1",
      "api": "openai-completions",
      "apiKey": "${TOKENFLUX_API_KEY}",
      "models": [{ "id": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID" }]
    }
  }
}

Replace YOUR_TOKENFLUX_KEY with the key you copied. Keep the key out of Git.

Pi expands ${TOKENFLUX_API_KEY} from the environment. Keep that reference in the JSON file instead of the key itself. The API identifier openai-completions uses /v1/chat/completions. Merge the provider into an existing providers object if the file already exists.

Choose a modelCopy Anchor Link

Replace both YOUR_MODEL_ID values in models.json with a catalog model that supports Chat Completions and tool calls. Start pi --provider tokenflux --model YOUR_MODEL_ID, or open /model to reload the file and select the model.

Verify the connectionCopy Anchor Link

Run these commands in a scratch directory. If the client asks for file access, check the path before you approve it.

printf 'TOKENFLUX_GUIDE_OK\n' > marker.txt
pi --provider tokenflux --model YOUR_MODEL_ID --tools read \
  -p "Read marker.txt and return its contents"

The reply should contain TOKENFLUX_GUIDE_OK. Check the model, key, token count and cost on Usage. Delete marker.txt after the test.

TroubleshootingCopy Anchor Link

The model does not appear. Check the JSON syntax, the providers.tokenflux.models list, and the key variable. If PI_CODING_AGENT_DIR is set, put models.json in that directory instead.

Authentication fails despite a new environment key. A saved auth.json credential takes precedence over models.json. Remove the old TokenFlux credential with /logout, then retry.

Tools fail. Choose a model that supports tool calls. Keep api set to openai-completions for this setup.

401, 429 or a model error. Check that the key is enabled, the full model ID is correct, and your account has balance and available rate limits. Do not switch models automatically.

API referenceCopy Anchor Link

See Chat Completions, Models and API overview.