--- title: "Pi on Fly.io Sprites: a remote workspace that Pi's own tools work in" description: "The pi-sprites package points Pi's read, edit and bash tools at a Sprite, a Firecracker microVM with its own kernel, and adds checkpoints, services and policy. Or run Pi inside the Sprite, where it comes preinstalled." --- # Pi on Sprites: run Pi's file and shell tools in a microVM Sprites for Pi: send Pi's tools to a microVM, or run Pi inside one. Install the plugin Run Pi on a Sprite Pi is Earendil's minimal agent harness, and [Pi 1.0](https://earendil.com/posts/pi-1-0/) shipped on October 1. Pi shows you every read, search, command and edit it makes, but it does not stop to ask before each one. On your laptop, each of those commands runs as you, in the same home directory as your SSH keys and cloud credentials. A Sprite is a Firecracker microVM with its own kernel and a disk that stays put. The pi-sprites package keeps Pi on your machine and sends its file and shell tools to a Sprite instead. Or skip the package: Pi is already installed on new Sprites, so you can open a shell on one and start it there. Two ways in ## Pick where Pi runs - The plugin **Pi stays local. Its tools work on the Sprite.** Select a Sprite and Pi's own `read`, `write`, `edit`, `bash`, `grep`, `find` and `ls` tools, plus your `!` shell commands, operate in a workspace on it. There is no second set of remote tools for the model to learn, and no MCP server in between: the package talks to Sprites through the Sprites JavaScript SDK. On top of that it adds automatic checkpoints, services, network policy, a bootstrap from your repo, retained CI runs, a worker pool and a long-running Pi host. `/sprite-local` puts the tools back on your machine. Install the plugin - Inside the Sprite **Pi runs in the Sprite itself.** Pi is one of the coding agents preinstalled on new Sprites. Open a shell, run `pi`, sign in to a model provider, and the whole session runs in the microVM: Pi's process, its tools, its credentials and every command it runs. This is the one for long unattended sessions. Your model provider key lives on the Sprite too, in Pi's `auth.json`, so for a repository you don't trust, use the plugin, which keeps provider credentials on your machine. Run Pi on the Sprite Quickstart: the plugin ## Install the plugin You need Node.js 24 or later, which the Sprites SDK requires, and a Sprites token. 1. 1 **Install the package from GitHub.** `pi install git:github.com/superfly/pi-sprites` ``` pi install git:github.com/superfly/pi-sprites ``` pi-sprites is not on npm yet, so install it from [superfly/pi-sprites](https://github.com/superfly/pi-sprites). One install brings in eight extensions, five skills and a set of prompt templates. Like any Pi package, it runs with your full permissions, so read the source first if that is your habit. 2. 2 **Give Pi a Sprites token.** `export SPRITES_TOKEN='...'` ``` export SPRITES_TOKEN='...' ``` Set it in the shell that starts Pi. This package authenticates with a token, not a browser OAuth flow, and it can reach every Sprite that token can. The token stays in the local Pi process: it is not copied into remote commands or onto the Sprite. 3. 3 **Check it works, then pick a Sprite.** `/sprite list` ``` /sprite list ``` If it prints your Sprites, or an empty list, the token works. Then `/sprite new pi-my-project` creates a Sprite and selects it. Asking Pi in plain words ("list my sprites") works once a Sprite is selected: until then the package keeps its `sprite_*` model tools switched off, and the slash commands are the way in. ### Now give it something real. Tell Pi: Clone github.com/you/your-app into this workspace, install the dependencies, run the test suite, and tell me what fails. That prompt assumes a public repository. Pi's `bash` on the Sprite has none of your local git credentials, so a private repo needs its own access set up on the Sprite first. **Important:** your local checkout is not the Sprite's filesystem. Selecting a Sprite does not copy your files across, and `/sprite-bootstrap` clones from your repository's remote rather than uploading your working tree, so push the branch you want Pi to work on first. Quickstart: Pi in the Sprite ## Run Pi on the Sprite 1. 1 **Install the Sprites CLI and sign in.** `curl https://sprites.dev/install.sh | bash` ``` curl https://sprites.dev/install.sh | bash ``` `sprite login` ``` sprite login ``` 2. 2 **Create a Sprite and open a shell on it.** `sprite create my-app` ``` sprite create my-app ``` `sprite console -s my-app` ``` sprite console -s my-app ``` 3. 3 **Start Pi and choose a model.** `pi` ``` pi ``` Run `/login` inside Pi, pick a provider, and use a subscription or store an API key. Clone your repo and work the way you would locally. Detach with Ctrl+\ to leave the session running, and `sprite attach` reconnects you. Why a Sprite ## What Pi gets, and what it can't reach 1. **A bad install hits the Sprite, not your home directory.** Pi runs whatever the repo and its dependencies ask for, and anyone who can write to the repo, or to a package it installs, decides what that is. On your laptop, a postinstall script that reads `~/.ssh` or `~/.aws` finds them. Once Pi's `bash` is pointed at a Sprite, that script runs in a separate microVM with its own kernel, where those files don't exist, and pi-sprites does not copy your local environment or provider credentials into it. 2. **Every risky turn starts from a checkpoint.** In its default mode, pi-sprites takes one checkpoint per turn before the first write, edit, recognized destructive shell command, or service or policy change. If that checkpoint fails, the change is blocked rather than run without a way back. `/sprite-undo` restores the last one after you confirm, and the model itself cannot restore anything. A checkpoint covers the filesystem, installed packages and on-disk databases, not running processes. 3. **Code on the Sprite can't change where it connects.** A Sprite starts with open egress. `/sprite-policy allow ` builds an allowlist, and once one is in place, a lookup for a name off the list is refused and packets to other addresses are dropped, including code that dials an IP directly. The policy is read-only from inside the Sprite, so a script Pi runs there cannot edit it. Pi's own `sprite_policy` tool runs on your machine and can add rules but never clear the list; setting `toolActivation` to `off` takes all eight of the package's model tools away from Pi and leaves policy to your slash commands. An allowed domain is still a way out as well as in, so keep the list to what the job needs. 4. **The environment comes back the same way every time.** Put the repo, setup commands, services and policy in `.pi/sprites.json` and `/sprite-bootstrap` builds the Sprite from it: clones the repo, runs the setup in a trusted project only, starts the services and leaves a checkpoint. The disk is persistent ext4, so the next session finds the dependencies installed, and an idle Sprite sleeps with its disk intact. 5. **It can run more than one job at once.** `/sprite-workers shell "npm test" "npm run lint"` spreads the tasks across a pool of worker Sprites, up to 16, and runs them at the same time; each worker has its own filesystem. `/sprite-ci` bootstraps a Sprite for the current branch, runs the test command, and keeps the Sprite with a checkpoint when it fails, so you can select it and look. ## Frequently asked questions Do I need the Sprites CLI to use pi-sprites? + No. The pi-sprites package talks to Fly.io Sprites through the Sprites JavaScript SDK with a token from your environment, so it needs Node.js 24 or later and a SPRITES_TOKEN, not the CLI. You need the Sprites CLI only to open a shell on a Sprite yourself, which is how you run Pi inside one. Does pi-sprites run Pi inside the Sprite? + No. With the package, Pi keeps running on your machine and its read, write, edit, bash, grep, find and ls tools operate in a workspace on a Fly.io Sprite. To put the whole Pi process inside the microVM, start pi on the Sprite instead. Is Pi already installed on a Sprite? + Yes. Pi is one of the coding agents preinstalled on new Sprites on Fly.io. Open a shell with sprite console, run pi, and sign in to a model provider with /login. Which Sprites can Pi reach through pi-sprites? + Every Sprite the token you export can reach. pi-sprites authenticates to Fly.io Sprites with a token rather than a browser OAuth grant, so there is no per-session name prefix to limit it; use a token for the organization you want Pi working in. The token stays in the local Pi process and is never copied onto a Sprite. Is pi-sprites on npm? + No, not yet. Install it from GitHub with pi install git:github.com/superfly/pi-sprites. The package connects Pi to Fly.io Sprites and needs Node.js 24 or later, which the Sprites SDK requires. What happens if Pi breaks the Sprite? + Restore a checkpoint. pi-sprites checkpoints a Fly.io Sprite automatically before the first risky change in each turn, and /sprite-undo puts the last one back after you confirm, or /sprite-restore takes a specific checkpoint ID. Restore stays a command for you: Pi's own tools cannot run it. Why doesn't asking Pi to list my sprites work right after install? + Because the package's model tools wait for a Sprite to be selected. With the default setting, Pi gets its sprite_* tools only once a Fly.io Sprite is selected, so start with the /sprite list and /sprite new commands, or set toolActivation to always in .pi/sprites.json to give Pi those tools from the start. Can I preview the app Pi builds on a Sprite? + Yes. Create a service with an HTTP port and it answers on the Sprite's own HTTPS URL on Fly.io, which requires Sprites authentication unless you make it public, and pi-sprites never makes it public. For local-only access, /sprite-proxy forwards a port in the Sprite to your machine. Does pi-sprites copy my uncommitted changes to the Sprite? + No. Selecting a Fly.io Sprite does not copy files, and bootstrap, CI and workers clone from your repository's remote. Push the branch you want Pi to work on before you bootstrap.