Pi - boxd

Pi 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. The boxd extension, @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

Install Pi and the extension

npm install -g @earendil-works/pi-coding-agent
pi install npm:@boxd-sh/pi

Create an API key

boxd auth keys create pi --org <your-org>
export BOXD_API_KEY=bxd_...

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

Start Pi with --boxd

In a git checkout:

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:

☁ 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:

pi --boxd --boxd-no-repo --no-session -p "Run uname -a and tell me where you are."

[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 with its memory, so a server the agent started is still running when you come back.

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."

[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:

pi --boxd -c -p "Is the web server from before still running? Check with pgrep and curl, and tell me the machine's hostname."

[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 the machine too, running processes included. The fork gets its own machine and the parent’s machine hibernates:

pi --boxd --fork 01a1d204 -p "Tell me this machine's hostname, and whether a web server is running on port 8000."

[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.
`--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. 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 covers the errors, limits, and examples.

Getting started

Guides

Integrations and automations

Use cases

References

Pi