> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-dx-2885.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi Setup

This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://pi.dev/packages/@upstash/box-pi) extension ([npm](https://www.npmjs.com/package/@upstash/box-pi)), which runs every tool call (`bash`, file I/O, and search) inside an Upstash Box. The agent and your model API keys stay on your machine; only tool execution happens in the box.

<Note>
  This is the inverse of running Pi *inside* a box as a [custom harness](https://github.com/upstash/box/blob/main/packages/sdk/examples/custom-pi-agent.ts). Here, Pi runs locally and only its tools execute remotely.
</Note>

***

## 1. Get your API key

Go to the [Upstash Console](https://console.upstash.com) and create a Box API key. See the [quickstart](/box/overall/quickstart#1-get-your-api-key) for details.

***

## 2. Install Pi and the extension

```bash theme={"system"}
npm install -g @earendil-works/pi-coding-agent
pi install npm:@upstash/box-pi
```

<Note>
  To update the extension later, run `pi update`. `pi install` won't refresh an existing install.
</Note>

***

## 3. Set the API key

Export your Box API key (e.g. in your shell profile):

```bash theme={"system"}
export UPSTASH_BOX_API_KEY="box_xxxxxxxxxxxxxxxxxxxxxxxx"
```

If no key is set, Pi prompts you for one once per session.

***

## 4. Run Pi with `--box`

Run Pi from inside a git repository whose `origin` is on GitHub:

```bash theme={"system"}
cd my-project
pi --box
```

The repo is cloned **from GitHub** into a fresh box. The box never sees your local files, so the repo must exist on github.com (private is fine) and anything you want in the box must be committed and pushed. The session's work syncs to its own GitHub branch (see step 5). You can also point at another repo, or run outside a git repo for a blank workspace:

```bash theme={"system"}
pi --box --repo github.com/acme/api --branch dev
```

A footer badge in Pi shows that tool calls are running remotely. Everything else works exactly like a local Pi session: the agent reads, writes, and executes in the box transparently.

### Flags

| Flag               | Description                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------- |
| `--box`            | Run tools inside an Upstash Box sandbox                                                               |
| `--repo <url>`     | Git repo to clone into the box (defaults to the repo you're in)                                       |
| `--branch <name>`  | Branch to clone (defaults to your current branch)                                                     |
| `--runtime <name>` | Box runtime image: `node`, `python`, `golang`, `ruby`, `rust` (append `-alpine` for the musl variant) |
| `--size <name>`    | Box size: `small` (default), `medium`, or `large`                                                     |

***

## 5. Sync work to GitHub

If you launched Pi in a **github.com** repo and you're logged in with the GitHub CLI (`gh auth login`), each session gets its own branch: the extension creates `pi/<short-session-id>` off your current branch, the agent commits its work, and the extension pushes those commits after each turn.

Manage the branch with slash commands inside Pi:

| Command    | What it does                                     |
| ---------- | ------------------------------------------------ |
| `/sandbox` | Show the active box's status and its branch link |
| `/github`  | Open this session's branch on GitHub             |
| `/compare` | Open the branch compare view on GitHub           |
| `/merge`   | Merge this session's branch into its base        |
| `/pr`      | Create a pull request for this session's branch  |

<Note>
  Outside a github.com repo (or without `gh` authenticated), push is disabled. The box still has a local git repo, so the agent can commit, but nothing leaves the box.
</Note>

***

## 6. Preview a running server

When the agent starts a server in the box, ask it for a preview link. The `preview_url` tool returns a live, basic-auth-protected URL for any port:

```
https://<box-name>-8080.preview.box.upstash.com
```

The login is printed alongside the URL, and your browser prompts for it. Preview URLs are created fresh on every call, so ask again after a box resumes from idle. See [Preview URLs](/box/overall/preview) for how these work.

***

## 7. Session lifecycle

Each Pi session gets one box, and the box follows the session:

* **Resume a session**, and its box is reattached, with your files and environment exactly where you left them.
* **Idle sessions** pause the box automatically with the filesystem preserved; the next tool call transparently restarts it. Nothing to configure.
* **Delete a session** from Pi's resume menu, and its box is deleted too. A box lives as long as its session.

***

## Troubleshooting

* **The box is empty.** The box clones from GitHub; it never uploads local files. Make sure the repo exists on github.com and your checkout has an `origin` remote, then start a new session. Run `/sandbox` to see what was cloned.
* **Local changes missing in the box?** Commit and push first. The box clones the branch from GitHub, not your working tree.
* **Duplicate flag or tool errors** mean two copies of the extension are loaded. Run `pi list` and `pi uninstall` one of them.
* **Pushes not appearing on GitHub?** Branch sync needs `gh auth login` and a github.com remote.