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

# Pi

> Run Pi's tools in a boxd machine while the agent runs on your computer. One machine per Pi session, hibernated when you quit, forked when you fork the session.

![The Pi logo mark and wordmark inside the boxd card.](https://mintcdn.com/azin/hzxvJlAVnEvK1ZI1/images/boxd-x-pi.png?fit=max\&auto=format\&n=hzxvJlAVnEvK1ZI1\&q=85\&s=87a080f8d53f73b28218aa50db51261e)

[Pi](https://pi.dev) is a terminal coding agent with a small core and an extension API. Extensions ship as npm packages and are listed in the [Pi package gallery](https://pi.dev/packages).

The [boxd extension](https://pi.dev/packages/@boxd-sh/pi), `@boxd-sh/pi`, runs Pi's `bash`, `read`, `write`, `edit`, `ls`, `find`, and `grep` tools in a boxd machine. The agent, its model calls, and your model key stay on your computer. Each Pi session gets its own machine, which keeps its files and running processes with the session.

## Set up

**1. Install Pi and the extension**

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

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create pi --org <your-org>
export BOXD_API_KEY=bxd_...
```

Machines are created and billed in the key's organization.

**3. Start Pi with --boxd**

In a git checkout:

```bash theme={"theme":"github-dark"}
cd my-project
pi --boxd
```

The extension creates a machine, clones the checkout's `origin` at your current branch into `/home/boxd/<repo>`, and points every tool there. The footer shows the machine:

```text theme={"theme":"github-dark"}
☁ boxd · pi-01a1d205-8a62-756a-a87b-6f6e8109f836 · /home/boxd/Hello-World
```

Only what is pushed to `origin` reaches the machine. Without `--boxd`, the extension does nothing and Pi's own tools run as usual.

## Try it with one prompt

This runs one prompt in a fresh machine and deletes the machine when Pi exits:

```bash theme={"theme":"github-dark"}
pi --boxd --boxd-no-repo --no-session -p "Run uname -a and tell me where you are."
```

```text theme={"theme":"github-dark"}
[boxd-pi] Machine ready · pi-01a1d203-ec07-755c-8114-3b54a9c086c0 · 1.0s
I'm running inside a boxd machine called `pi-01a1d203-ec07-755c-8114-3b54a9c086c0`. It's an x86_64 Linux system on kernel 6.18.0 running Ubuntu 24.04. My working directory is `/home/boxd/workspace`, which is a git repository, and I'm logged in as `boxd` with passwordless sudo.
```

## Quit, resume, and fork

A saved Pi session keeps its machine. When you quit, the machine [hibernates](https://docs.boxd.sh/guides/suspend-resume.md) with its memory, so a server the agent started is still running when you come back.

```bash theme={"theme":"github-dark"}
git clone https://github.com/octocat/Hello-World && cd Hello-World
pi --boxd -p "Start a web server on port 8000 in the background that serves this folder, then give me its preview URL."
```

```text theme={"theme":"github-dark"}
[boxd-pi] Machine ready · pi-01a1d204-957f-7395-bc3d-8e7a1c5d7f8b · 1.8s
The web server is running in the background on port 8000 and serving `/home/boxd/Hello-World`.

**Preview URL:** https://p8000.pi-01a1d204-957f-7395-bc3d-8e7a1c5d7f8b.boxd.sh
```

Pi has exited and the machine is hibernated. Opening the preview URL wakes it, and the page loads. Resume the session and the agent finds the same server:

```bash theme={"theme":"github-dark"}
pi --boxd -c -p "Is the web server from before still running? Check with pgrep and curl, and tell me the machine's hostname."
```

```text theme={"theme":"github-dark"}
[boxd-pi] Reattached machine · pi-01a1d204-957f-7395-bc3d-8e7a1c5d7f8b · 0.6s
Yes, the web server is still running.

- **pgrep:** found `python3 -m http.server 8000` with PID 1022.
- **curl:** `localhost:8000` answered with `HTTP/1.0 200 OK`.
```

Forking the session, with `/fork` in Pi or `pi --fork <session>`, [forks](https://docs.boxd.sh/guides/fork.md) the machine too, running processes included. The fork gets its own machine and the parent's machine hibernates:

```bash theme={"theme":"github-dark"}
pi --boxd --fork 01a1d204 -p "Tell me this machine's hostname, and whether a web server is running on port 8000."
```

```text theme={"theme":"github-dark"}
[boxd-pi] Forked machine · pi-01a1d205-3eaf-75ac-802e-3a6b7a7dd04a · 1.6s
The hostname is `pi-01a1d205-3eaf-75ac-802e-3a6b7a7dd04a`. A web server is running on port 8000.
```

So you can set a project up once, fork the session twice, and let two agents try two approaches, each in its own copy of the machine.

## Commands

| Command | What it does |
| - | - |
| `/boxd` or `/boxd status` | Shows the machine, its state, and its URL. |
| `/boxd url <port>` | A public HTTPS URL for a port in the machine. |
| `/boxd hibernate` | Hibernates the machine now. The next tool call wakes it. |
| `/boxd push [branch]` | Pushes the machine's `HEAD` to a branch of the repo the session cloned, `pi/<session>` by default. |
| `/boxd delete [--yes]` | Deletes the machine. It asks first. |

The agent also gets a `preview_url` tool, so it can hand you a link to a server it started. Anyone with the link can open it, and the first link on a machine can take up to a minute before HTTPS answers.

## Flags and environment

| Flag | What it does |
| - | - |
| `--boxd` | Runs Pi's tools in a boxd machine. |
| `--boxd-repo <url>` | The repo to clone. Default: the `origin` of the checkout you are in. |
| `--boxd-branch <name>` | The branch to clone. Default: your current branch. |
| `--boxd-no-repo` | Starts in an empty git repo at `~/workspace`. |
| `--boxd-snapshot <name>` | Creates the machine from a boxd [snapshot](https://docs.boxd.sh/guides/snapshots.md). |
| `--boxd-size <size>` | `1x4`, `2x8`, `4x16`, or `8x32` (vCPU x GiB). Default: your organization's default. |
| `--boxd-region <region>` | The region for new machines, such as `fra` or `nyc`. |
| `--boxd-org <org>` | The organization for new machines. |

`BOXD_ORG` and `BOXD_REGION` set the defaults for `--boxd-org` and `--boxd-region`. `BOXD_PI_NAME_PREFIX` changes the machine name prefix, `pi-` by default.

## What each machine gets

* **Isolation:** every machine is [isolated](https://docs.boxd.sh/guides/machine-specs.md). Your boxd API key never enters it, and of your shell environment only Pi's `PI_*` variables go with a command.
* **A full computer:** Ubuntu 24.04 with Docker, Node.js, Python, Go, and passwordless sudo. A command that leaves a process in the background, like `npm run dev &`, returns, and the process keeps running.
* **No fallback to your computer:** when the machine can't be used, the tool call fails and says so. It is never run on your computer instead.
* **A name and labels:** `pi-<session id>`, labelled `created-by=boxd-pi` and `pi-session=<id>`.
* **A clean end:** quitting a saved session hibernates the machine. Quitting an in-memory session (`--no-session`) deletes it. A machine whose session you delete stays hibernated, so run `/boxd delete` first.
* **Your GitHub token, for one command:** for a private GitHub repo, the extension uses the token from your `gh` login for the clone and for `/boxd push`. It is not written to the machine's disk or git config.

The [extension's README](https://github.com/boxd-sh/boxd-pi) covers the errors, limits, and examples.


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