$ cat ~/map/pi-remote.md

pi-remote

Phone remote control for pi: one Python process wraps pi --mode rpc — self-hosted, relay-free, built for native Windows.

tools✓ Sep 15

pip install -r requirements.txt, run python pi_web_bridge.py from the repository with the static folder next to it, and open the machine's port 8770 in a browser (over Tailscale, use the tailnet name)

## TL;DR

A self-hosted remote control for the pi coding agent: one Python bridge wraps pi --mode rpc and serves a phone-friendly web app over a tailnet, built for native Windows with no relay and no third party in the path.

## Key points

• $Architecture: the browser speaks WebSocket to pi_web_bridge.py, which spawns pi --mode rpc and owns its stdin and stdout over JSONL; agent events stream back as messages while prompt, steer, and abort commands go the other way, and a prompt or steer can carry attached images for a model with vision.
• $Why it exists: the README's comparison table faults pi-web with WSL-only operation, remote-pi with needing a relay, pi-remote-control with a hosted relay, and Telegram bridges with the transcript leaving home; this bridge keeps everything on your own machines, and it also documents leave-it-running setups for Windows (startup folder, Task Scheduler — a real service via NSSM or pywin32 is documented but not recommended), Linux (systemd user service), and macOS (launchd).
• $Recommended topology: an always-on Linux box runs llama.cpp serving a local model over HTTP, the Windows PC holds the code and runs pi plus the bridge, and the phone is a thin client over Tailscale — though everything can run on one machine and the inference endpoint can be any OpenAI-compatible server.
• $Security model: a token is always required (one is generated at startup when PI_WEB_TOKEN is unset, and PI_WEB_TOKEN=off drops the bridge to read-only, refusing prompts, shell, and project opening at the server, not just by disabling buttons); the WebSocket checks Origin, the page ships a strict CSP with nosniff and no-referrer, and the token is compared in constant time — still a single-user tool whose port must stay inside the tailnet.
• $Permissions: pi ships no prompts of its own, so a guardrails extension supplies the dialogs, and over RPC only the four standard dialog kinds (select, confirm, input, editor) reach the browser — an extension drawing with ctx.ui.custom() gets undefined, and the bridge can neither see nor answer it; pi-guardrails is recommended with its pathAccess feature turned off, because that guard's prompt uses ctx.ui.custom() and would otherwise deny file access outside the working directory silently.
• $Projects are working directories holding pi's existing sessions, and the transcript is rebuilt from pi's own get_messages so the history is the session on disk, not an in-memory copy; removing a session moves the jsonl file to a _trash folder beside it because pi has no delete over RPC.
• $The rest: twenty-three slash commands filtered as you type (/bash skips the model and the guardrails; /restart relaunches the bridge via a one-shot scheduled task outside the process tree), a Functions page with show-reasoning, response suggestions, summary-on-stop, local notifications, and smooth generation, PWA install over HTTPS via tailscale serve, and a fake_pi.py harness that exercises the whole surface without a model in headless Chrome.

## FAQ

## References

• README ↗

Last updated: Sep 15, 2026