> ## 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.
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
in-process rvenc client"]
end
P -->|"Encrypt before network egress"| G["Prem API Gateway
ciphertext and metadata"]
G -->|"Route the encrypted payload"| E["Prem API Enclave (TEE)
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](/api-keys).
* **A model** that your Prem account can use. See [Models & Pricing](/models-and-pricing).
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) |
`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. |
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.
**One stream at a time.** The encrypted endpoint allows one active stream for each API key. A second stream on the same key can 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](/agents).
## Troubleshooting
Check that `@premai/api-extension-pi` is in the `packages` array (or `extensions`). Restart Pi after you change `settings.json`.
Check that `PREM_API_KEY` is correct. Check that the API key is active.
Pick a model your account can use. The dynamic refresh registers only the models your key can see.
Wait for the active stream 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
Learn the proxy modes, routes, keys, and daemon controls.
Review concurrency, retries, reasoning, and error controls.
Understand the compatibility layer that the extension uses.
Learn what the enclave protects and what stays outside the TEE.
Complete the key, reliability, capacity, and attestation checks.
Review current behavior, assurance gaps, and roadmap items.