Pi - TrueFoundry Docs

This guide shows how to connect Pi, the open-source terminal coding agent, to the TrueFoundry AI Gateway. Pi reads custom providers from ~/.pi/agent/models.json, so you add the gateway once and every model behind it shows up in Pi’s model picker.

What is Pi?

Pi is a minimal, extensible coding agent that runs in your terminal. It reads and edits files, runs shell commands, and can be extended with TypeScript extensions, skills, and prompt templates. Pi talks to models through three wire protocols (OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages), and the TrueFoundry AI Gateway serves all three, so you can route any model in your gateway through Pi.

Prerequisites

A TrueFoundry account with at least one model provider configured. See the Gateway quick start.
A TrueFoundry API key. See Authentication.

Node.js 22.19 or later, and Pi installed:

npm install -g @earendil-works/pi-coding-agent

Add TrueFoundry as a provider

Get your gateway base URL and model IDs

Open the AI Gateway playground and copy the base URL and model IDs from the unified code snippet. Model IDs use the provider-account/model format, for example openai-main/gpt-4o. See how to find the gateway base URL.

TrueFoundry playground showing the unified code snippet with the base URL and model name

Export your API key

Pi resolves the key from an environment variable at request time, so the key never sits in the config file. Add this to your shell profile:

export TRUEFOUNDRY_API_KEY="<your-truefoundry-api-key>"

Create models.json

Create ~/.pi/agent/models.json with a truefoundry provider. Replace {GATEWAY_BASE_URL} with your gateway base URL and the model IDs with your own:

~/.pi/agent/models.json

{
  "$schema": "https://pi.dev/schemas/models.schema.json",
  "providers": {
    "truefoundry": {
      "name": "TrueFoundry AI Gateway",
      "baseUrl": "{GATEWAY_BASE_URL}",
      "apiKey": "$TRUEFOUNDRY_API_KEY",
      "api": "openai-completions",
      "headers": {
        "X-TFY-METADATA": "{\"application\":\"pi\"}"
      },
      "models": [
        {
          "id": "openai-main/gpt-4o",
          "name": "GPT-4o (TrueFoundry)",
          "contextWindow": 128000,
          "maxTokens": 16384,
          "input": ["text", "image"]
        },
        {
          "id": "anthropic-main/claude-sonnet-4-5",
          "name": "Claude Sonnet 4.5 (TrueFoundry)",
          "api": "anthropic-messages",
          "contextWindow": 200000,
          "maxTokens": 64000,
          "reasoning": true,
          "input": ["text", "image"]
        },
        {
          "id": "openai-main/gpt-5",
          "name": "GPT-5 (TrueFoundry)",
          "api": "openai-responses",
          "contextWindow": 400000,
          "maxTokens": 128000,
          "reasoning": true
        }
      ]
    }
  }
}

The provider-level api is the default for every model, and a model can override it. Pi appends the right path to baseUrl for each protocol (/chat/completions, /responses, or /messages), so set baseUrl to the gateway root, not to a full endpoint.

Check that Pi sees the models

pi --list-models truefoundry

Expected output:

provider     model                             context  max-out  thinking  images
truefoundry  anthropic-main/claude-sonnet-4-5  200K     64K      yes       yes
truefoundry  openai-main/gpt-4o                128K     16.4K    no        yes
truefoundry  openai-main/gpt-5                 400K     128K     yes       no

If the list is empty, TRUEFOUNDRY_API_KEY isn’t set in the current shell. Pi hides models whose API key it can’t resolve.

Provider fields

Field	Description
`baseUrl`	Gateway base URL, without an endpoint path.
`apiKey`	`$VAR` reads an environment variable, `!command` runs a shell command and uses its output (for example a password manager CLI), and any other value is used as a literal key.
`api`	`openai-completions`, `openai-responses`, or `anthropic-messages`. Set it on the provider as a default, or on a model to override.
`headers`	Headers sent with every request. Use `X-TFY-METADATA` to tag requests for metadata logging.
`models[].contextWindow`, `models[].maxTokens`	Context and output limits Pi uses for compaction and request sizing. Match them to the underlying model.
`models[].reasoning`	Set to `true` for reasoning models so Pi’s `--thinking` levels apply.
`models[].input`	`["text"]` or `["text", "image"]`.

Use Pi with the gateway

Start an interactive session on a TrueFoundry model:

pi --provider truefoundry --model openai-main/gpt-4o

Pass --provider explicitly. Pi accepts provider/id in --model, and gateway model IDs already contain a slash, so without --provider Pi can read openai-main as the provider name. Inside a session, run /model to switch between models. Opening /model reloads models.json, so edits apply without a restart. Run a single prompt non-interactively:

pi --provider truefoundry --model anthropic-main/claude-sonnet-4-5 --thinking high \
  -p "Read package.json and list the scripts it defines"

Every request appears in the AI Gateway request logs with the application: pi metadata from the X-TFY-METADATA header.

Connect MCP Gateway servers

Pi supports remote MCP servers over Streamable HTTP. Point it at a server registered on the MCP Gateway and its tool calls get the gateway’s access control, guardrails, and audit logs. Copy the server URL from the How To Use tab on the server’s page in TrueFoundry. It has the form {GATEWAY_BASE_URL}/<tenant>/mcp/<server>/server.

Sign in with TrueFoundry
API key

Add the server without credentials, then sign in through the browser:

pi mcp add github --url "{GATEWAY_BASE_URL}/<tenant>/mcp/github/server"
pi mcp login github

Pi stores the tokens in ~/.pi/agent/mcp-auth.json and refreshes them when they expire. Run pi mcp logout github to delete them.

Send your TrueFoundry API key as a bearer token from an environment variable:

pi mcp add github \
  --url "{GATEWAY_BASE_URL}/<tenant>/mcp/github/server" \
  --bearer-token-env-var TRUEFOUNDRY_API_KEY

This writes the following to ~/.pi/agent/mcp.json:

~/.pi/agent/mcp.json

{
  "mcpServers": {
    "github": {
      "url": "{GATEWAY_BASE_URL}/<tenant>/mcp/github/server",
      "headers": {
        "Authorization": "Bearer ${TRUEFOUNDRY_API_KEY}"
      }
    }
  }
}

Check the connection:

pi mcp list

A working server shows connected and the number of tools it exposes. A server that needs OAuth shows needs sign-in until you run pi mcp login. Add -l to pi mcp add to write the server to .pi/mcp.json in the current project instead of the global file. Inside a session, run /mcp to see server status.

​What is Pi?

​Prerequisites

​Add TrueFoundry as a provider

​Provider fields

​Use Pi with the gateway

​Connect MCP Gateway servers