pi-remote

WebSocket-first server runtime for Pi Coding Agent. Start it once, talk to Pi from anywhere.

npm install -g @k3_2o/pi-remote
pi-remote start
curl -X POST http://localhost:8080/v1/chat -H "Content-Type: application/json" -d '{"message":"say hello"}'

pi-remote is a thin server that turns Pi's RPC mode into a network service. It handles process management, session multiplexing, and transport. Pi does the thinking. The pipe is dumb.

Features

• WebSocket — the real protocol. Connection = session. All Pi commands available. Extension UI flows bidirectionally.
• HTTP — sugar layer for curl, cron, webhooks. /v1/chat streams SSE.
• Session management — one Pi process per session. Auto-cleanup. Pool with eviction. Idle reset policies.
• Auth — optional API key middleware on both transports.
• Daemon mode — --detach for quick dev, systemd for production.
• CLI — start, stop, status, health, sessions, logs, relay.
• SDKs — JavaScript and Python clients. Import from npm or copy-paste.
• Zero config — sensible defaults for everything. Config file optional.

Quick Start

npm install -g @k3_2o/pi-remote       # you also need Pi: npm install -g @earendil-works/pi-coding-agent
pi-remote start                # server on :8080
pi-remote health               # check it's alive
pi-remote sessions             # list sessions

Documentation

Documentation Index

| Document | Type | What's in it | |---|---|---| | Getting Started | Quick Start | Five-minute install + curl test — verify it works | | Your First Chat | Tutorial | Step-by-step from zero — install, connect, send your first message, learn the SDK | | Deploy to a VPS | Tutorial | Bare Ubuntu server to production pi-remote behind nginx with TLS, auto-start, and API key auth | | Build a Discord Bot | How-to | Connect pi-remote to a Discord bot — real example | | Triggers | How-to | Discord bots, cron jobs, webhooks — patterns for connecting anything | | Daemon Mode | How-to | Background, systemd, logs | | Docker | How-to | Run in a container | | Production Setup | How-to | TLS, rate limiting, log rotation | | SDK Reference | Reference | Every method and event — abstracted vs raw, examples | | CLI Reference | Reference | Every command with options | | Configuration | Reference | Every config option with defaults | | Protocol | Reference | WebSocket handshake, commands, events, extension UI | | Deployment Paths | Reference | VPS providers, tunnel alternatives, bare metal — comparison and trade-offs | | How It Works | Explanation | The pipe model — what we built vs what emerged from Pi | | Architecture | Explanation | Why WebSocket, process model, design decisions |

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT