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

# Pi

> Connect Pi to Prem API through the @premai/api-extension-pi provider for confidential inference.

Pi is a coding agent that runs in your terminal. This guide connects it to Prem API. Prem runs the model inside a secure enclave. Your prompts stay private on the way there.

The recommended setup uses the **`@premai/api-extension-pi`** extension. It registers a `prem-api` provider inside Pi. By default, the provider encrypts your prompts end-to-end before they leave your machine, using the same encrypted transport as the Confidential Proxy — but **inside the Pi process**, so you do not run a separate proxy daemon. Set `ENABLE_ZDR=true` to route through the plain OpenAI-compatible ZDR path instead.

> [!NOTE]
>
> Pi does not use the TypeScript SDK directly. The extension calls `@premai/api-sdk`'s `createRvencClient` in-process. The encrypted transport is the same one the Confidential Proxy uses.

## How the connection works

```mermaid theme={"system"}
flowchart TB
    subgraph Local["Your machine: plaintext is available"]
        P["Pi + @premai/api-extension-pi<br/>in-process rvenc client"]
    end

    P -->|"Encrypt before network egress"| G["Prem API Gateway<br/>ciphertext and metadata"]
    G -->|"Route the encrypted payload"| E["Prem API Enclave (TEE)<br/>decrypt, infer, encrypt"]
    E -.->|"Encrypted response returns on the same path"| G
    G -.->|"Decrypt on your machine"| P
```

Pi and the extension stay on your machine. The Prem API Gateway sees only the sealed message. The Prem API Enclave opens it inside a Trusted Execution Environment (TEE).

## Before you start

Get these things ready:

* **Pi**, installed. See the [Pi install guide](https://pi.dev/docs/latest/install).
* **A Prem API key.** This proves who you are. See [API Keys](https://docs.prem.io/api-keys.md).
* **A model** that your Prem account can use. See [Models & Pricing](https://docs.prem.io/models-and-pricing.md).

> [!NOTE]
>
> The extension resolves the API key from the `PREM_API_KEY` environment variable at request time. It does not need a separate client KEK for the default ephemeral path.

## 1. Set your API key

Open a terminal. Set the API key in the terminal that runs Pi:

```bash theme={"system"}
export PREM_API_KEY="your-prem-api-key"
```

The extension reads the key from this environment variable. Keep the terminal open while you work.

## 2. Install the extension

Add `@premai/api-extension-pi` to your Pi `settings.json` `packages` array (npm form):

```json theme={"system"}
{
  "packages": ["npm:@premai/api-extension-pi@^0.1.0"]
}
```

Or point `extensions` at a local checkout:

```json theme={"system"}
{
  "extensions": ["/path/to/@premai/api-extension-pi"]
}
```

The extension registers the `prem-api` provider when Pi starts. No separate load step is needed.

## 3. Set the default provider

Set `defaultProvider` in `settings.json` to use the provider:

```json theme={"system"}
{
  "defaultProvider": "prem-api"
}
```

Pi picks a default model from the fetched catalog. Set `defaultModel` yourself only if you want a specific one.

The provider **dynamically refreshes the model catalog** from the gateway at runtime. In confidential mode it fetches `/rvenc/models`; in ZDR mode it fetches `/openai/models`. Only CHAT models that are visible in the dashboard are registered. Hidden models are excluded automatically. When Prem adds a new model, it appears in Pi on the next refresh — no extension update needed. No model list is hardcoded; the gateway is the source of truth.

## 4. ZDR mode

By default, the extension routes through the encrypted rvenc transport. To use the plain OpenAI-compatible ZDR path instead, set `ENABLE_ZDR=true`:

```json theme={"system"}
{
  "defaultProvider": "prem-api"
}
```

In ZDR mode the provider fetches the standard model catalog from `/openai/models` and routes requests through `/openai/chat/completions` without the in-process encryption. Pi picks a standard model from that catalog; set `defaultModel` only if you want a specific one.

## 5. Start Pi

Start Pi from the folder that has your `settings.json`:

```bash theme={"system"}
pi
```

Send a short prompt, such as "Say hello." The request travels through the encrypted path.

That is it. Pi now talks to Prem through the sealed path.

## Optional environment variables

| Variable | Required | Default | Purpose |
| - | - | - | - |
| `PREM_API_KEY` | yes | — | Gateway API key (resolved at request time) |
| `ENABLE_ZDR` | no | `false` | `true` routes through the plain OpenAI ZDR path |
| `PROXY_URL` | no | `https://gateway.prem.io` | Gateway proxy endpoint |
| `ENCLAVE_URL` | no | `https://conf-engine.prem.io` | Confidential enclave endpoint (confidential mode only) |
| `CLIENT_KEK` | no | ephemeral | Persistent key-encryption key for DEK caching (confidential mode only) |

> [!NOTE]
>
> `PROXY_URL` and `ENCLAVE_URL` show the current default endpoints. Check the [Prem dashboard](https://dashboard.prem.io) if the endpoints change.

## What this setup protects

| Component | Reads your text | Notes |
| - | - | - |
| Pi | Yes | It reads your prompt, your code, and the tool results on your machine. |
| @premai/api-extension-pi | Yes, on your machine | It seals requests and opens replies in-process. |
| Prem API Gateway | No | It handles the sealed message and metadata only. |
| Prem API Enclave | Yes, inside the TEE | It opens the request, runs the model, and seals the reply. |
| External tool or MCP server | Depends on the tool | A tool reads the data that Pi sends to it. |

> [!WARNING]
>
> This setup protects the model path only. It does not put Pi, your code, shell commands, plugins, MCP servers, or local files inside the enclave.

## Good to know

**Tool calls run on your machine.** The model can ask Pi to run a tool. The model traffic uses the sealed path. But Pi runs the tool on your machine, outside the enclave. Keep the `edit` and `bash` permissions set to `ask`. Do not treat a private model as a private tool.

**Concurrent requests per key.** Each API key can run a limited number of requests at the same time, set by your [tier](https://docs.prem.io/tiers.md#concurrent-requests). The encrypted endpoint always streams, and each call holds a slot until its stream closes. Requests above the limit return `429`. Start with one Pi session and no parallel subagents. Need parallel workers? Run them one after another, or give each worker its own API key. See [Agents & Automation](https://docs.prem.io/agents.md).

## Troubleshooting

> [accordion] Pi does not show the prem-api provider
>
> Check that `@premai/api-extension-pi` is in the `packages` array (or `extensions`). Restart Pi after you change `settings.json`.

> [accordion] The provider returns 401
>
> Check that `PREM_API_KEY` is correct. Check that the API key is active.

> [accordion] The API says model not found
>
> Pick a model your account can use. The dynamic refresh registers only the models your key can see.

> [accordion] The API returns 429
>
> Wait for active streams to finish. Reduce parallel work. Follow the `Retry-After` header if the response has one.

## Frequently asked questions

### Does Pi use the Prem TypeScript SDK?

The extension calls `@premai/api-sdk`'s `createRvencClient` in-process. Pi itself does not import the SDK.

### Do I need to run the Confidential Proxy?

No. The extension runs the encrypted transport inside the Pi process. You do not start a separate proxy daemon.

### Is the API key the same as the KEK?

No. The API key handles access, limits, and billing. The KEK protects your encryption keys. The default path uses an ephemeral KEK; set `CLIENT_KEK` for persistent DEK caching.

### Does this protect my whole Pi session?

No. It protects the model path. Pi and its local tools stay on your machine.

### Can Pi use tool calls?

Yes, when the selected model supports tool calls. The model traffic uses the encrypted path. Pi runs each tool outside the enclave.

## Related

> [card] [Confidential Proxy](https://docs.prem.io/confidential-proxy.md)
>
> Learn the proxy modes, routes, keys, and daemon controls.

> [card] [Agents & Automation](https://docs.prem.io/agents.md)
>
> Review concurrency, retries, reasoning, and error controls.

> [card] [OpenAI-compatible clients](https://docs.prem.io/guides/openai-compatible-clients.md)
>
> Understand the compatibility layer that the extension uses.

> [card] [Security Model](https://docs.prem.io/security-model.md)
>
> Learn what the enclave protects and what stays outside the TEE.

> [card] [Production Checklist](https://docs.prem.io/production-checklist.md)
>
> Complete the key, reliability, capacity, and attestation checks.

> [card] [Platform Status](https://docs.prem.io/platform-status.md)
>
> Review current behavior, assurance gaps, and roadmap items.


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