Pi Setup
This guide walks you through using Pi with the @upstash/box-pi extension (npm), 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.
This is the inverse of running Pi inside a box as a custom harness. Here, Pi runs locally and only its tools execute remotely.
1. Get your API key
Go to the Upstash Console and create a Box API key. See the quickstart for details.
2. Install Pi and the extension
npm install -g @earendil-works/pi-coding-agentpi install npm:@upstash/box-piTo update the extension later, run pi update. pi install won't refresh an existing install.
3. Set the API key
Export your Box API key (e.g. in your shell profile):
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:
cd my-projectpi --boxThe 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:
pi --box --repo github.com/acme/api --branch devA 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 |
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.
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.comThe 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 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
originremote, then start a new session. Run/sandboxto 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 listandpi uninstallone of them. - Pushes not appearing on GitHub? Branch sync needs
gh auth loginand a github.com remote.