A self-hosted remote runtime for Pi.
Run Pi on an always-available Linux server and connect from the normal Pi terminal on your Mac with pi --cloud. Your repository workspace and native Pi session stay available across client disconnects and runtime restarts.
Pi Cloud starts the installed CLI with pi --mode rpc. Pi owns the conversation, tools, models, compaction, and session data. Pi Cloud provides authenticated remote access, workspace and process lifecycle, isolation, and scoped credentials.
Warning
Pi Cloud is pre-alpha and currently targets single-operator deployments. Hosted Pi RPC execution, reconnect, and native session resume now work end-to-end; production isolation, pooling, and multi-tenant hardening are still under construction.
run the Pi Cloud Compose stack on your Linux server
→ install the Pi Cloud extension on your Mac
→ run `pi --cloud` from a local Git repository
→ prompt, steer, follow up, cancel, and reconnect
→ continue in the same native Pi session and remote workspace
A hosted session remains available while its Pi process is disposable. Pi Cloud can stop an idle process and later resume the native session in its persistent workspace.
Mac: upstream Pi + cloud extension
`pi --cloud`
│
authenticated HTTP + WebSocket
▼
Pi Cloud API and router
│
scoped runtime authority
▼
isolated runtime worker
├── persistent repository workspace
├── opaque native Pi session data
├── operator Pi configuration
├── scoped credentials
└── pi --mode rpc
The API authenticates clients, manages lifecycle metadata, and routes connections. It does not mount repository workspaces. The runtime worker owns the workspace, starts Pi, and relays Pi's native JSONL RPC records.
Workspace files and native Pi session data persist independently from runtime processes and injected credentials. Clients reconnect through Pi's own session state.
Hosted Pi uses the same resources as local Pi:
- extensions;
- skills and prompt templates;
- settings and providers;
- Pi packages;
- project trust.
A small trusted Pi package supplies hosted capabilities that are not part of the RPC protocol. It uses Pi's public extension API and a capability channel scoped to one hosted session.
The current pre-alpha slice includes:
- authenticated, SQLite-backed workspace, hosted-session, agent, run, and lifecycle metadata;
- atomic dispatch, single-use leases, browser attachment tickets, and authenticated public and internal hosted-runtime WebSockets;
- exact-revision checkout, persistent workspaces, native Pi session resume, and scoped credential references;
- bounded hosted RPC envelopes, LF JSONL Pi supervision, reconnect, stop, restart, and redaction of configured secrets;
- a local single-operator Docker baseline and a hosted runtime smoke command.
Not yet included: the usable pi --cloud terminal client, its required upstream Pi startup-delegation seam, mutable cloud branches, complete server distribution, multi-tenant isolation, pooling, horizontal scaling, and production hardening.
See docs/hosted-runtime.md for the operator contract. Follow broader progress through the GitHub milestones.
- Node.js 22.19 or newer
- npm 11 or newer
- Docker only for the runner image and local smoke test; checks, builds, API development, and unit tests do not need a running daemon
Install dependencies:
npm installStart the current control plane:
eval "$(node scripts/create-development-keys.mjs)"
export PI_CLOUD_PUBLIC_BASE_URL="http://host.docker.internal:3000"
export PI_CLOUD_DISPATCHER_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64url"))')"
export PI_CLOUD_USER_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64url"))')"
export PI_CLOUD_API_CREDENTIALS="[{\"token\":\"$PI_CLOUD_USER_TOKEN\",\"subjectId\":\"local-user\",\"type\":\"user\",\"displayName\":\"Local User\"}]"
npm run dev:apiCheck it from another terminal:
curl http://localhost:3000/healthThe development database defaults to ./data/pi-cloud.sqlite.
Run the repository checks:
npm run check
npm run build
npm testRun the hosted runtime smoke flow against a dedicated temporary API and a real HTTPS repository revision:
npm run smoke:hostedIt requires the repository, revision, and optional credential-reference variables from .env.example, built API and runner packages (npm run build), Docker Compose, and a sanitized, non-secret Pi resource directory readable by isolated workspace UIDs. The command builds an isolated runner image and removes its temporary API database, containers, volumes, and runtime roots after success, failure, or termination signals.
On a 16 GiB Apple Silicon development Mac, an on-demand Colima VM with four CPUs, four GiB of memory, and a 60 GiB sparse disk leaves enough host headroom while accommodating the Compose runner's two GiB limit:
colima start --cpu 4 --memory 4 --disk 60
npm run smoke:hosted
colima stopDo not register Colima as a Homebrew service when Docker is needed only for smoke tests. docker system df reports VM storage use; docker builder prune removes reproducible build cache when needed. Avoid pruning volumes casually because the local Compose provider deliberately stores workspaces and native sessions in a Docker volume.
packages/
api/ Authentication, lifecycle, dispatch, and remote transport
cloud/ Mac Pi extension published as @pi-cloud/extension
contracts/ Shared client, API, and runtime wire contracts
runner/ Isolated repository and Pi runtime worker
assets/ Project identity assets
docs/ Product, architecture, and protocol documentation
scripts/ Development helpers
compose.yaml Local single-operator hosted runtime worker example
All workspaces use strict TypeScript and ESM on Node.js 22 or newer.
- Product scope
- Architecture
- Hosted runtime
- Control-plane API
- Task leases
pi --cloudstartup delegation
Repository code, dependencies, hooks, and project Pi resources execute inside the runtime isolation boundary. The host enforces authentication, filesystem and process isolation, credential scope, network policy, resource limits, and cleanup.
The API stays separate from repository execution. Credentials enter only the operation that needs them, and public records are validated, bounded, and redacted.