From c17c029a302465275ef6c516b6360f5101c66d66 Mon Sep 17 00:00:00 2001 From: alitariksahin Date: Fri, 31 Jul 2026 16:58:19 +0300 Subject: [PATCH 1/5] feat: add pi setup guide --- box/guides/pi-setup.mdx | 120 ++++++++++++++++++++++++++++++++++++++++ docs.json | 2 +- 2 files changed, 121 insertions(+), 1 deletion(-) create mode 100644 box/guides/pi-setup.mdx diff --git a/box/guides/pi-setup.mdx b/box/guides/pi-setup.mdx new file mode 100644 index 00000000..4653e777 --- /dev/null +++ b/box/guides/pi-setup.mdx @@ -0,0 +1,120 @@ +--- +title: "Pi Setup" +--- + +This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://www.npmjs.com/package/@upstash/box-pi) extension, 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](/box/overall/custom-harness/pi). Here, Pi runs locally and only its tools execute remotely. + + +--- + +## 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 +npm install -g @earendil-works/pi-coding-agent +pi install npm:@upstash/box-pi +``` + + + 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): + +```bash +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 +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 +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 ` | Git repo to clone into the box (defaults to the repo you're in) | +| `--branch ` | Branch to clone (defaults to your current branch) | +| `--runtime ` | Box runtime image: `node`, `python`, `golang`, `ruby`, `rust` (append `-alpine` for the musl variant) | +| `--size ` | 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/` 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://-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. diff --git a/docs.json b/docs.json index b7b7560e..720a7837 100644 --- a/docs.json +++ b/docs.json @@ -1690,7 +1690,7 @@ }, { "group": "Guides", - "pages": ["box/guides/remote-development", "box/guides/nextjs-setup", "box/guides/code-review-agent", "box/guides/langchain-deep-agents", "box/guides/web-scraping-playwright", "box/guides/ai-sdk-code-interpreter", "box/guides/tanstack-ai-file-editor", "box/guides/openclaw-setup", "box/guides/hermes-setup", "box/guides/crabbox-setup"] + "pages": ["box/guides/remote-development", "box/guides/nextjs-setup", "box/guides/code-review-agent", "box/guides/langchain-deep-agents", "box/guides/web-scraping-playwright", "box/guides/ai-sdk-code-interpreter", "box/guides/tanstack-ai-file-editor", "box/guides/pi-setup", "box/guides/openclaw-setup", "box/guides/hermes-setup", "box/guides/crabbox-setup"] } ] }, From 69b23f6d9e6d12b1775b618f86e3084d61ac5404 Mon Sep 17 00:00:00 2001 From: alitariksahin Date: Fri, 31 Jul 2026 16:59:19 +0300 Subject: [PATCH 2/5] fix: custom harness link --- box/guides/pi-setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/box/guides/pi-setup.mdx b/box/guides/pi-setup.mdx index 4653e777..9e1b50b5 100644 --- a/box/guides/pi-setup.mdx +++ b/box/guides/pi-setup.mdx @@ -5,7 +5,7 @@ title: "Pi Setup" This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://www.npmjs.com/package/@upstash/box-pi) extension, 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](/box/overall/custom-harness/pi). Here, Pi runs locally and only its tools execute remotely. + 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. --- From 991ceba344c193c03ad03f79459cc347cff1dbd7 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 13:59:53 +0000 Subject: [PATCH 3/5] chore(llms): regenerate llms.txt and llms-full.txt --- llms-full.txt | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++ llms.txt | 1 + 2 files changed, 121 insertions(+) diff --git a/llms-full.txt b/llms-full.txt index d8fb2ab9..69c7d363 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1480,6 +1480,126 @@ ssh -F /dev/null -o ControlMaster=no -o ServerAliveInterval=15 -o ServerAliveCou The most likely causes are a local `~/.ssh/config` entry (e.g. a stale `ControlMaster` socket or conflicting options) being applied to the connection, or a NAT/firewall on your network dropping idle TCP connections. The flags above bypass your local SSH config and keep the connection active with periodic keepalives. +# Pi Setup +Source: https://upstash.com/docs/box/guides/pi-setup + +This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://www.npmjs.com/package/@upstash/box-pi) extension, 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](https://github.com/upstash/box/blob/main/packages/sdk/examples/custom-pi-agent.ts). Here, Pi runs locally and only its tools execute remotely. + + +*** + +## 1. Get your API key + +Go to the [Upstash Console](https://console.upstash.com) and create a Box API key. See the [quickstart](/docs/box/overall/quickstart#1-get-your-api-key) for details. + +*** + +## 2. Install Pi and the extension + +```bash +npm install -g @earendil-works/pi-coding-agent +pi install npm:@upstash/box-pi +``` + + + 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): + +```bash +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 +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 +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 ` | Git repo to clone into the box (defaults to the repo you're in) | +| `--branch ` | Branch to clone (defaults to your current branch) | +| `--runtime ` | Box runtime image: `node`, `python`, `golang`, `ruby`, `rust` (append `-alpine` for the musl variant) | +| `--size ` | 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/` 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://-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](/docs/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. + # Remote Development Source: https://upstash.com/docs/box/guides/remote-development diff --git a/llms.txt b/llms.txt index 9b683375..07a6e4a9 100644 --- a/llms.txt +++ b/llms.txt @@ -39,6 +39,7 @@ - [LangChain Deep Agents](https://upstash.com/docs/box/guides/langchain-deep-agents.md) - [Next.js Setup](https://upstash.com/docs/box/guides/nextjs-setup.md) - [OpenClaw Setup](https://upstash.com/docs/box/guides/openclaw-setup.md) +- [Pi Setup](https://upstash.com/docs/box/guides/pi-setup.md) - [Remote Development](https://upstash.com/docs/box/guides/remote-development.md) - [AI File Editor with TanStack AI](https://upstash.com/docs/box/guides/tanstack-ai-file-editor.md) - [Scrape Dynamic Websites with Playwright](https://upstash.com/docs/box/guides/web-scraping-playwright.md) From 1135502e0d3ca03fff45cf948cde3a91c20f5f12 Mon Sep 17 00:00:00 2001 From: alitariksahin Date: Fri, 31 Jul 2026 17:05:12 +0300 Subject: [PATCH 4/5] fix: link to pi packages --- box/guides/pi-setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/box/guides/pi-setup.mdx b/box/guides/pi-setup.mdx index 9e1b50b5..26067c91 100644 --- a/box/guides/pi-setup.mdx +++ b/box/guides/pi-setup.mdx @@ -2,7 +2,7 @@ title: "Pi Setup" --- -This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://www.npmjs.com/package/@upstash/box-pi) extension, 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 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. 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. From 91ee63187caf95cc22dbbf061c3b168a661e9729 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 14:07:06 +0000 Subject: [PATCH 5/5] chore(llms): regenerate llms.txt and llms-full.txt --- llms-full.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/llms-full.txt b/llms-full.txt index 69c7d363..99eaaef1 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1483,7 +1483,7 @@ The most likely causes are a local `~/.ssh/config` entry (e.g. a stale `ControlM # Pi Setup Source: https://upstash.com/docs/box/guides/pi-setup -This guide walks you through using [Pi](https://pi.dev) with the [`@upstash/box-pi`](https://www.npmjs.com/package/@upstash/box-pi) extension, 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 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. 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.