Connect pi

pi is an AI agent that runs in your terminal. The setup script below registers the Arena API as a custom provider in pi so you can use Arena routing models — auto, fast, max, and the full catalog of direct models — from inside pi.

1. Get a gateway key

Open the Keys page and create a new API key. You'll pass it to the setup script in the next step.

2. Run the setup script

This script fetches the current model list from the gateway, writes an arena-gateway provider entry into ~/.pi/agent/models.json, and — on macOS — detects any corporate TLS-inspection CAs that would otherwise break Node.js connections.

export GATEWAY_API_KEY=<your-key>
curl -fsSL https://portal.api.preview.arena.ai/api/scripts/setup-pi | bash

Or pass the key inline without setting the env var:

curl -fsSL https://portal.api.preview.arena.ai/api/scripts/setup-pi | bash -s -- --key <your-key>

3. Add env vars to your shell

Add the following to ~/.zshrc or ~/.bashrc, then open a new shell.

export GATEWAY_API_KEY=<your-key>
# If the setup script detected a corporate TLS-inspection CA:
export NODE_EXTRA_CA_CERTS="$HOME/.pi/corp-ca-bundle.pem"

The NODE_EXTRA_CA_CERTS line is only needed if the setup script detected a corporate TLS-inspection CA (Cloudflare WARP, Zscaler, etc.). If it said "No known TLS-inspection root CAs detected", skip it.

4. Use Arena models in pi

Use the arena-gateway/ prefix to route through the Arena API. Many model IDs overlap with pi's built-in providers, so the prefix prevents ambiguity.

# Use the arena-gateway/ prefix to force routing through the Arena API.
# Many model IDs (gpt-5, o3, gemini-2.5-pro) also exist on pi's built-in
# providers — the prefix avoids ambiguity.
pi --model arena-gateway/claude-sonnet-4-6 -p "hello"
pi --model arena-gateway/auto -p "hello"
pi --model arena-gateway/fast -p "hello"

You can also select models interactively inside pi by running /models and choosing from the arena-gateway provider group.

5. Verify the connection

Before debugging pi itself, confirm your key works directly against the gateway.

curl https://api.preview.arena.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Say hello in exactly five words"}],
    "max_tokens": 64
  }'

Troubleshooting

Symptom	Fix
`Connection error.` in pi, but `curl` works fine	Corporate VPN is intercepting TLS. Re-run the setup script — it will detect and export the CA. Set `NODE_EXTRA_CA_CERTS` as shown in step 3.
Still failing after setting `NODE_EXTRA_CA_CERTS`	Run `NODE_DEBUG=undici pi ...` to see the underlying TLS error.
`401 Unauthorized`	Check that `GATEWAY_API_KEY` is exported in your current shell.
Model not found	Use the `arena-gateway/<id>` prefix. Re-run the setup script to refresh the model list.