pi-tower

Control tower for remote pi runners. Register a headless pi on any machine, then let an interactive pi session anywhere dispatch tasks to it by name — like calling a remote coding agent as a tool.

┌────────────────────── interactive pi (anywhere) ─────────────────────────────────┐
│  process: pi (interactive TUI)                                                   │
│  ┌────────────────────────────────────────────────────────────┐                  │
│  │  extension.ts                                              │                  │
│  │  ├─ registerFlag("--tower", "--tower-token")               │                  │
│  │  └─ registerTool("runner_list", "runner_task")             │                  │
│  │       execute() ──── wss ────────────────────────────────────────┐            │
│  └────────────────────────────────────────────────────────────┘     │            │
└─────────────────────────────────────────────────────────────────────┼────────────┘
                                                                      │
                                              wss (RPC JSONL frames, token auth)
                                                                      │
┌────────────────── tower (any reachable host) ───────────────────────┼────────────┐
│  process: pi-tower (tower.mjs)                                      ▼            │
│  ┌────────────────────────────────────────────────────────────┐                  │
│  │  registry: { "win-test-1" → control ws + session pipes }   │                  │
│  │  pure relay per session pipe, client ⇄ runner untouched    │                  │
│  │  one client per session; sessions run in parallel          │                  │
│  └──────────────────────────────▲─────────────────────────────┘                  │
└─────────────────────────────────┼────────────────────────────────────────────────┘
                                  │
              wss outbound (runner dials out, NAT/firewall friendly)
                                  │
┌───────────────────── runner (any machine with pi) ─┼─────────────────────────────┐
│  process: pi-runner (runner.mjs)                   │                             │
│  ┌─────────────────────────────────────────────────┴──────────┐                  │
│  │  pi-runner --hq wss://hq.example.com --id win-test-1       │                  │
│  │  control ws + one data ws per session (LF JSONL)           │                  │
│  └───────────────┬────────────────────────────────────────────┘                  │
│                  ▼                                                               │
│  child processes: pi --mode rpc × N   (one per session, tools run locally)       │
└──────────────────────────────────────────────────────────────────────────────────┘

Setup

Three roles, each runnable on any machine (even all three on one box); the runner and interactive sides also need pi installed.

Tower (any host the runner and interactive sides can both reach)

npx pi-tower --port 9000 --token <shared-token>   # or PI_TOWER_TOKEN env

Or with Docker plus a Cloudflare Tunnel (no exposed port, TLS terminates at the edge):

cp .env.example .env   # set PI_TOWER_TOKEN and TUNNEL_TOKEN
docker compose up -d

In the Zero Trust dashboard, point the tunnel's public hostname at http://tower:9000; the tower URL everywhere else is then wss://<that-hostname>.

Runner (the machine that executes tasks: a CI box, a lab PC, a server)

npx pi-runner --hq wss://hq.example.com --id win-test-1 --token <shared-token> -- --no-session

Args after -- go to the spawned pi --mode rpc and are all optional. --no-session keeps task transcripts off the runner's disk; drop it for an on-machine audit trail of what remote tasks did. The runner dials out and reconnects every 3s, so it works behind NAT. --id defaults to the hostname.

Interactive side (wherever you drive pi from)

pi-tower is a pi package bundling the extension (runner_task / runner_list tools) and the remote-runner skill. Install it from npm or GitHub, or try a local checkout without installing:

pi install npm:pi-tower
pi install git:github.com/iamken1204/pi-tower  # or from GitHub
pi -e /local/path                              # or try a local checkout (this run only)

Then start pi with the tower flags and prompt "use runner_task on win-test-1 to ...":

pi --tower wss://hq.example.com --tower-token <shared-token>

Providers with a direct API key see the extension tools natively. Providers that run their agent loop server-side (and never expose extension tools) get the remote-runner skill instead, which teaches the model the pi-task CLI below.

pi-task CLI

Some providers run their agent loop server-side and never expose extension-registered tools to the model. pi-task is the provider-agnostic fallback: any agent (or human) dispatches with one shell command instead of the extension tools.

export PI_TOWER_URL=wss://hq.example.com PI_TOWER_TOKEN=<shared-token>
pi-task --list                    # who's online
pi-task win-test-1 "run the failing job and report the error"

stdout carries only the final answer, so $(pi-task ...) captures cleanly; progress streams to stderr only in an interactive terminal, keeping piped output clean for agent callers. --session <name> picks the session (see below); --fresh resets the session's conversation first; Ctrl-C forwards an abort to the runner.

Sessions

Each runner runs one pi --mode rpc process per session, so different sessions run in parallel with full process isolation. Tasks that reuse a session name continue its conversation — context survives between tasks and across detach/reattach. The default session is main; names match [A-Za-z0-9._-]{1,64}. Idle session processes stay alive until the runner stops.

pi users get discovery via the bundled remote-runner skill automatically. For non-pi agents, add a line to the project's AGENTS.md instead:

Remote runner tasks: `pi-task <runner-id> "<prompt>"`; list runners: `pi-task --list` (env: PI_TOWER_URL, PI_TOWER_TOKEN).

Wire contract

Session pipes are pure relays: each WebSocket text frame is one pi RPC JSONL record (see pi's docs/rpc.md), untouched in both directions. The runner's control channel carries only {"type":"open","session":"<name>"} frames from the tower; the runner answers by dialing a session pipe.

Every HTTP request and WebSocket upgrade authenticates with an Authorization: Bearer <token> header. The tower pings every connection every 30s and terminates peers that miss two pings.

| Endpoint | Purpose | |----------|---------| | GET / | health, returns pi-tower | | GET /runners | JSON [{id, connectedAt, sessions}] | | WS /runner?id=<id> | runner control channel; same id reconnect replaces the socket, live sessions survive | | WS /runner-session?id=<id>&session=<name> | runner-dialed data pipe, one per session | | WS /attach?runner=<id>&session=<name> | client attachment, one per session (session defaults to main) |

| Close code | Meaning | |-----------|---------| | 4001 | bad token | | 4004 | unknown runner (reason lists online ids) | | 4005 | session busy (another client attached or attaching) | | 4006 | session disconnected while attached | | 4007 | runner failed to open the session (15s timeout or runner offline) |

Detaching a client leaves its session pipe idle on the tower, so a later attach with the same name resumes the conversation without a new open.

Security

Single shared token, sent as an Authorization header on every upgrade and HTTP request, so it stays out of URLs and access logs. Run the tower behind a TLS reverse proxy (caddy/nginx) so the public URL is wss://; the token and all traffic are plaintext otherwise. Anyone with the token can drive any runner — runners execute arbitrary commands, so treat the token like an SSH key.

Verify

npm run verify

Four assert-based scripts: tower relay semantics (fake runner), full chain through a real pi --mode rpc (no LLM call), the extension's tools plus the pi-task CLI driven against a fake runner, and pi-package loading via pi -e . (extension flag registered, skill listed).