@noahsaso/pi-remote

Remote terminal access for pi via WebSocket with Tailscale integration. Connect to your pi session from mobile browsers over LAN or your tailnet.

Features

• PTY-based remote access - Wraps pi in a pseudo-terminal for optimal performance
• WebSocket bridge - Real-time bidirectional terminal I/O with auto-reconnect and output replay buffer
• Mobile-first - Touch scroll with momentum, virtual keybar (arrows, Ctrl+C, etc.)
• Token authentication - All connections require token auth (HTTP, WebSocket, API)
• Auth modal - Browser prompts for token if missing/invalid, with error feedback on retry
• QR code - Scan to connect instantly from mobile
• /remote command - Restart pi in remote mode from within a running session
• Tailscale integration - Automatically serves over HTTPS on your tailnet with a unique session subpath
• Discovery service - Lists all active remote sessions at /pi/ with a card UI; auto-starts on first session, auto-shuts down on last
• TUI widget - Shows Tailscale URL, LAN URL, token, and all-sessions link in a bordered card above the editor
• Session ended overlay - Browser shows a modal when the remote session exits
• Scroll-to-bottom button - Appears in the header when scrolled up
• Styled error pages - Dark themed 403/404 pages matching the app style

Screenshots

Browser — Remote access modal

TUI — Widget with Tailscale, LAN, and Token

Usage as a pi Extension

This package is primarily used as a pi coding agent extension. The extension registers a /remote command that lets you switch your current pi session into remote access mode without losing context.

Global (all projects)

Add to ~/.pi/agent/settings.json:

{
  "extensions": [
    "~/path/to/pi-remote/packages/remote"
  ]
}

Or install from npm:

pi install npm:@noahsaso/pi-remote

Project-local

Add to .pi/settings.json in your project root:

{
  "extensions": [
    "~/path/to/pi-remote/packages/remote"
  ]
}

Temporary (one-off)

pi -e ~/path/to/pi-remote/packages/remote/extension/index.ts

Using /remote inside pi

Once the extension is loaded, run /remote in pi:

/remote

This will:

1. Save your current session
2. Shut down the current pi process
3. Restart pi wrapped in a PTY with a WebSocket server
4. Display a QR code and URL — scan from mobile or open in a browser

When running inside a remote session, a persistent widget above the editor shows the remote URL.

---

Usage as a CLI Tool

You can also launch remote mode directly from the terminal without a running pi session:

npm install -g @noahsaso/pi-remote
pi-remote

Options

# Specify a custom pi binary path
pi-remote --pi-path /path/to/pi

# Pass extra arguments to pi
pi-remote -- --continue

# Custom port (default: 7009)
PORT=8080 pi-remote

---

Architecture

                        ┌──────────────────┐
                        │  Discovery Svc   │  port 7008
                        │  /pi/ (session   │  Tailscale: /pi/
                        │   list + links)  │
                        └──────────────────┘
                               ▲
              register/deregister via localhost API
                               │
┌─────────────┐         ┌─────────────┐
│   Browser   │  WS     │ HTTP Server │  port 7009+
│  (xterm.js) │────────▶│   + WS      │  Tailscale: /pi/{id}/
└─────────────┘         └──────┬──────┘
                               │
                        ┌──────┴──────┐
                        │     PTY     │
                        │   (pi CLI)  │
                        └─────────────┘

Source Layout

Path	Description
extension/index.ts	Pi extension entry — registers /remote command and bordered TUI widget (Tailscale, LAN, Token, All sessions)
src/cli.ts	pi-remote binary entry point
src/discovery.ts	Discovery service — session registry, card-based web UI, auto-shutdown
src/discovery-main.ts	Entry point for the detached discovery process
src/tailscale.ts	Shared Tailscale helpers (find binary, hostname, serve, serve off)
src/pty.ts	PTY management (node-pty), stdin/stdout attachment
src/ws.ts	WebSocket bridge, mobile-priority resize logic
src/server.ts	HTTP server with token auth, /api/local-url endpoint, styled error pages
web/	Browser frontend (xterm.js, touch scroll, virtual keybar, auth modal, session ended overlay)

---

API

startRemote(options)

import { startRemote } from "@noahsaso/pi-remote";

const cleanup = await startRemote({
  piPath: "/usr/local/bin/pi",  // optional, auto-detected
  args: ["--continue"],          // optional, passed to pi
  cwd: process.cwd(),            // optional
  env: process.env,              // optional
});

// Stop the server and kill the PTY process
cleanup();

Environment Variables

Variable	Description
PORT	HTTP server port (default: 7009)
PI_REMOTE_URL	Set automatically when running inside pi-remote; the extension uses this to show the URL widget
PI_REMOTE_TAILSCALE_URL	Set automatically when Tailscale serve is active; shown in the TUI widget
PI_REMOTE_DISCOVERY_URL	Set automatically when the discovery service is running; links to the all-sessions page

---

Tailscale Integration

When Tailscale is installed and running, pi-remote automatically:

1. Detects the Tailscale binary (checks PATH, then known locations for macOS/Linux)
2. Gets the machine's Tailscale hostname via tailscale status --json
3. Runs tailscale serve --bg --https 443 --set-path /pi/{session-id}/ http://localhost:{port}
4. Displays the full URL with auth token: https://your-host.tailnet.ts.net/pi/abc123/?token=...
5. Shows the Tailscale URL in the QR code modal (with LAN URL as fallback)
6. Cleans up the specific serve route on exit (without affecting other tailscale serve routes)

Graceful fallback: If Tailscale is not installed, not running, or the serve command fails, pi-remote continues normally with just the LAN URL. No errors are shown.

Multiple sessions: Each session gets a unique /pi/{8-hex-chars}/ subpath, so multiple remote sessions can coexist on the same machine.

Discovery Service

When multiple remote sessions run on the same machine, the discovery service provides a central landing page listing all active sessions.

• Auto-start: The first pi-remote session spawns the discovery service as a detached background process on port 7008
• Shared token: The discovery service generates the auth token; all sessions use the same token
• Session registry: Sessions register on startup and deregister on exit via localhost API
• Web UI: Card layout at /pi/ showing each session's working directory and start time, with clickable links
• Tailscale route: Served at https://your-host.tailnet.ts.net/pi/?token=...
• Auto-shutdown: When the last session deregisters, the discovery service cleans up its Tailscale route and exits

URL structure on tailnet:

• https://host.ts.net/pi/?token=... → discovery service (all sessions)
• https://host.ts.net/pi/abc12345/?token=... → individual session

Security

• Shared token — Single random 16-byte token generated by the discovery service, shared across all sessions. Required for all connections (HTTP API, WebSocket, pages). Static assets and the SPA shell are exempt so the auth modal can load.
• No localhost exemption — Even connections from 127.0.0.1 (including Tailscale proxy) require a valid token
• Auth modal — If the browser doesn't have a valid token, a login modal prompts for one
• Styled error pages — Invalid tokens show a dark-themed "Access denied" page; bad paths show "No session found"
• Tailscale — When using Tailscale, traffic is encrypted end-to-end within your tailnet using auto-provisioned TLS certificates

---

Development

# Install dependencies (from monorepo root)
npm install

# Build TypeScript
npm run build:ts

# Build web UI
npm run build:web

# Full build
npm run build

# Watch mode (TypeScript only)
npm run dev

# Link globally for testing
npm link

---

License

MIT