Skip to main content
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

To 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):
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:
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:
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

​
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:
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:
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 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.