@pragmaticcoder/pi-remote-control

Pi extension for securely pairing the π Remote Android companion app with an active Pi TUI session.

Packages

Package details

extension

Install @pragmaticcoder/pi-remote-control from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@pragmaticcoder/pi-remote-control

Package: @pragmaticcoder/pi-remote-control
Version: 0.1.1
Published: Jun 23, 2026
Downloads: 318/mo · 13/wk
Author: nucleoid
License: MIT
Types: extension
Size: 35.6 KB
Dependencies: 2 dependencies · 1 peer

Pi manifest JSON

{
  "extensions": [
    "./index.ts"
  ],
  "image": "https://raw.githubusercontent.com/nucleoid/pi-remote/main/docs/screenshots/main.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@pragmaticcoder/pi-remote-control

Pi extension for pairing the π Remote Android app with an active Pi TUI session.

This npm package is a Pi package (pi-package) and should be discoverable through pi.dev/packages after the repository is public.

Install

pi install npm:@pragmaticcoder/pi-remote-control

From this repository:

pi install ./pi-extension/remote-control
pi install git:github.com/nucleoid/pi-remote

Commands

/remote-control — safe status only; token-bearing URLs are redacted.
/remote-control-qr — explicit pairing command that shows a warning plus QR/deep link.
/remote-control-android — explicit pairing command that opens a token-bearing deep link through adb.
/remote-control-rotate-token — rotates the bearer token and disconnects existing clients.
/remote-control-disable — disables and stops the server.
/remote-control-enable — re-enables the server for TUI sessions.

Security

Do not expose the WebSocket port to the public internet. Use LAN, Tailscale/WireGuard, localhost, or SSH tunnels. ws:// is cleartext by design for LAN/VPN use, so protect the network path. Treat tokens, QR codes, and pi-remote:// links as secrets and rotate the token after any leak.

See the repository security model for details.

Configuration is stored at ~/.pi/agent/remote-control.json with best-effort restrictive permissions. allowNoAuthFromLoopback defaults to false; if enabled it is warned in status and applies only to loopback addresses.

Config

{
  "enabled": true,
  "host": "127.0.0.1",
  "port": 37891,
  "token": "generated-secret",
  "allowNoAuthFromLoopback": false,
  "maxClients": 3,
  "failedAuthLimit": 8,
  "failedAuthWindowMs": 60000
}