pi-pod / pipod

# pi pod
Run pi coding-agent sessions in
remote sandboxes ("pods"), from a terminal or a phone, on a server you run yourself.
| Path | What it is |
| --- | --- |
| `cli/` | The command-line client (`pipod`). Launches and attaches to pods. |
| `server/` | The control plane: REST API, session gateway, lifecycle workers, Postgres. |
| `sandbox/` | The native sandbox service: one container hosting many isolated pods. |
| `ios/` | The Swift/SwiftUI iOS app. |
| `android/` | The Kotlin/Compose Android app. |
| `selfhost/` | The self-hosted deployment: one Compose project, installed and upgraded with `selfhost/upgrade`. |
| `docs/` | Self-hosting and cross-component notes. |
## How it fits together
The CLI and the apps are clients of the server. The server owns pod lifecycle and launches each
pod into the sandbox service on the same host; inside a pod it runs pi behind a small shim, and
clients drive that session over the server's gateway. Identity is Zitadel
(OIDC); the server stores no passwords.
## Run your own
On a Linux host with 8 GB of RAM, Docker with the Compose plugin, `git`, `openssl` and Node
22.19 or later:
 [code] 
Upgrading later is `git pull && selfhost/upgrade`. docs/self-host.md
is the full guide: signing in from a server without a browser, HTTPS for other machines and
the phone apps, sizing, backups, and what to do when something fails.
## Install the CLI
On any other machine, install the CLI from npm, where it is published as
`@pipod/cli`. It needs Node 22.19 or later:
 [code] 
A CLI newer than its server is refused with a message saying so; upgrade the server first. See
cli/README.md for what it does.
## Development
Each component builds on its own; see its README. From the repository root:
 [code] 
The pi version is one pin shared by the CLI and the server. Change it with
`make bump-pi VERSION=x.y.z`, never by hand.
`server/src/core/` is a tracked copy of part of the CLI, classified file by file in
`server/scripts/core-manifest.txt`. Change a `[shared]` file in `cli/` and run
`server/scripts/sync-core.sh ../cli`.
## The hosted service
A hosted pi pod service at pipod.dev is coming soon; it is not available
yet. It will run this code with an extension that adds per-user hosts, metering and billing.
Those parts are not in this repository; they plug into the interface in
`server/src/server/edition.ts`, which this server runs without.
## License
AGPL-3.0-only. Copyright © 2026 Billzo, LLC.
See CONTRIBUTING.md before opening a pull request and
SECURITY.md to report a vulnerability.