> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi

> Route the Pi terminal coding agent through TrueFoundry AI Gateway with a custom provider in models.json, and connect MCP Gateway servers with pi mcp add.

This guide shows how to connect [Pi](https://pi.dev), 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

1. A TrueFoundry account with at least one model provider configured. See the [Gateway quick start](https://www.truefoundry.com/docs/ai-gateway/quick-start.md).
2. A TrueFoundry API key. See [Authentication](https://www.truefoundry.com/docs/ai-gateway/authentication.md).
3. Node.js 22.19 or later, and Pi installed:

   ```bash theme={"dark"}
   npm install -g @earendil-works/pi-coding-agent
   ```

## Add TrueFoundry as a provider

**1. 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](https://www.truefoundry.com/docs/ai-gateway/quick-start.md#gateway-base-url).

![TrueFoundry playground showing the unified code snippet with the base URL and model name](https://mintcdn.com/truefoundry/n3EuZuJ0K8wBFp1G/images/new-code-snippet.png?fit=max\&auto=format\&n=n3EuZuJ0K8wBFp1G\&q=85\&s=3634c2dc8c3565fd77ab896d3fd07ed9)

**2. 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:

```bash theme={"dark"}
export TRUEFOUNDRY_API_KEY="<your-truefoundry-api-key>"
```

**3. 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:

```json ~/.pi/agent/models.json theme={"dark"}
{
  "$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.

**4. Check that Pi sees the models**

```bash theme={"dark"}
pi --list-models truefoundry
```

Expected output:

```text theme={"dark"}
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](https://www.truefoundry.com/docs/ai-gateway/log-custom-metadata.md). |
| `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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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](https://www.truefoundry.com/docs/ai-gateway/mcp/mcp-overview.md) 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**

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

```bash theme={"dark"}
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.

**API key**

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

```bash theme={"dark"}
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`:

```json ~/.pi/agent/mcp.json theme={"dark"}
{
  "mcpServers": {
    "github": {
      "url": "{GATEWAY_BASE_URL}/<tenant>/mcp/github/server",
      "headers": {
        "Authorization": "Bearer ${TRUEFOUNDRY_API_KEY}"
      }
    }
  }
}
```

Check the connection:

```bash theme={"dark"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.