# Running Pi

This guide covers running the [Pi coding agent](https://github.com/earendil-works/pi) in a Moat container.

Pi is a model-agnostic, bring-your-own-key coding agent. Unlike the other agents, **Pi has no credential of its own** — it runs against whichever model backend you grant. Moat supports two Pi backends today: `anthropic` and `openai`. Any other backend fails hard.

## Prerequisites

- Moat installed
- An Anthropic API key from [console.anthropic.com](https://console.anthropic.com/) **or** an OpenAI API key from [platform.openai.com](https://platform.openai.com/api-keys)

## Granting a backend

Pi uses your existing `anthropic` or `openai` grant — the same credential the other agents use. Grant one:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
moat grant anthropic

# ...or
export OPENAI_API_KEY="sk-..."
moat grant openai
```

The credential is stored encrypted and never enters the container. Moat's proxy injects the real token at the network layer. See [Credential management](/moat/concepts/credentials) for details.

## Choosing a backend

Pi decides which backend to use as follows:

1. **`--provider` flag** or **`pi.provider`** in `moat.yaml`, if set. Must be `anthropic` or `openai`, and the matching grant must be configured.
2. Otherwise, the backend is **inferred** from the single configured grant.
3. If **both** grants are configured and no provider is set, the run fails hard and asks you to choose.
4. If **no** supported grant is configured, the run fails before a container is created.

```bash
# One grant configured — inferred automatically
moat pi

# Both grants configured — choose explicitly
moat pi --provider openai

# Pin a model
moat pi --provider anthropic --model claude-opus-4-8
```

These checks run before any container is created, so misconfiguration fails fast with an actionable message.

## Running Pi

Interactive:

```bash
moat pi
moat pi ./my-project
```

Non-interactive (headless):

```bash
moat pi -p "explain this codebase"
moat pi -p "fix the bug in main.py"
```

## Configuration

```yaml
# moat.yaml
agent: pi
grants:
  - anthropic
pi:
  provider: anthropic      # optional; inferred from the grant when unset
  model: claude-opus-4-8   # optional; Pi's per-provider default when unset
```

See the [moat.yaml reference](../reference/02-moat-yaml.md#pi) for the full field list.

## Packages

Declare Pi packages (extensions, skills, prompt templates, themes) in `pi.packages`. Moat runs `pi install` for each at image build time, so they are baked into a reproducible, cached layer — no runtime install, no network needed at run time.

```yaml
pi:
  provider: anthropic
  packages:
    - "npm:@acme/pi-reviewer@1.2.0"
    - "git:github.com/acme/pi-skills@v3"
```

Only remote sources are accepted (`npm:` / `git:` / `https://` / `ssh://`); local paths are rejected. Pin exact versions/refs — Pi has no lockfile. If a package needs a runtime tool, add it to `dependencies:`.

## Safety defaults

Every `moat pi` image bakes a safe `~/.pi/agent/settings.json`:

- **`defaultProjectTrust: never`** — a checked-out repo's own `.pi/` config and extensions (which are arbitrary code) do not auto-load. Your project's `AGENTS.md`/`CLAUDE.md` still load (that is inherent to Pi).
- Telemetry and analytics off; quiet startup.

Pi config can redirect model traffic to any host (via `baseUrl`, custom providers, or extensions), so only the **network policy** actually constrains egress. `moat pi` warns when it runs under a permissive policy — prefer `network.policy: strict` for untrusted work.

## Runtime context

Moat injects a description of the sandbox (workspace, grants, network policy, Docker access) into Pi's system prompt via Pi's `--append-system-prompt`, so it augments rather than replaces your own `AGENTS.md` / `CLAUDE.md`.

## Not yet supported

- **Other backends** — only `anthropic` and `openai` are wired up. Gemini, Bedrock, and the rest are planned.
- **`pi.mcp`** — Pi core has no MCP configuration format to target.
- **`pi.sync_logs`** — session-log syncing is a planned follow-up.
- **Subscription (OAuth) login** — v1 uses API-key grants only.

---
[← Moat documentation index](https://majorcontext.com/moat/llms.txt)