π Remote

π Remote is an Android companion app plus daemon-backed Pi extension for monitoring and controlling Pi TUI or RPC sessions from your phone.

It is a developer tool, not a hardened public service. Do not expose the WebSocket port to the public internet.

First public release

π Remote is now available as an early public release for developers who want to monitor and steer an existing Pi TUI session from Android. The Pi extension is published as @pragmaticcoder/pi-remote-control, and the Android app is distributed as a signed APK on GitHub Releases.

This release is intended for trusted personal networks, VPNs, and local tunnels. Please read the security model before pairing a phone with a Pi session.

Quick start

1. Install the Pi extension:

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

2. Start Pi in TUI or RPC mode on your computer. The extension asynchronously ensures one shared profile daemon.

3. Run /remote-control-qr in Pi and scan the QR code from Android.

4. Install the signed APK from the latest GitHub Release.

See docs/INSTALL.md for detailed install and verification steps.

Install

Pi extension

Primary npm / Pi package catalog path:

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

Git/local install paths:

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

Android app

Install the signed release APK from the latest GitHub Release. Verify app-release.apk against the release SHA-256 or SHA256SUMS.txt asset when available:

sha256sum app-release.apk

Google Play Protect may warn that it has not seen this developer before. That is expected for a new GitHub-distributed APK that is not distributed through Google Play. Only install APKs from the official GitHub Releases page.

If no release APK is available for your platform yet, build from source:

./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

Play Store and F-Droid distribution are not available yet.

Security model

Read SECURITY.md and docs/SECURITY-MODEL.md before using π Remote.

• Use LAN, Tailscale, WireGuard, localhost, or an SSH tunnel.
• Do not router-port-forward or publicly expose the WebSocket port.
• The protocol uses cleartext ws:// intentionally for LAN/VPN/tunnel use; protect the transport with your network.
• Treat tokens, QR codes, and pi-remote:// deep links as secrets.
• Run /remote-control-rotate-token if pairing material leaks.
• Android stores connection settings in encrypted preferences and disables Android backups.

Pairing and commands

In Pi TUI mode:

/remote-control

This safe status output redacts token-bearing URLs by default. Use explicit pairing commands only when you are ready to show secret material:

/remote-control-qr
/remote-control-android

Management commands:

/remote-control-rotate-token
/remote-control-disable
/remote-control-enable

Configuration

Daemon configuration and private state live under ~/.pi/agent/pi-remote/. Fresh installs bind 127.0.0.1:37891. Existing explicit legacy host, port, token, and loopback choices are imported narrowly; internal bridge credentials are separate from Android v2 pairing tokens.

Durable local daemon

@nucleoid/pi-remote-daemon provides the profile-scoped durable control plane. The extension ensures it asynchronously on the first enabled TUI/RPC session, registers each Pi process independently over authenticated loopback v3, and retains Android's protocol-v2 root socket.

npx pi-remote-daemon ensure
npx pi-remote-daemon status
npx pi-remote-daemon stop

Ordinary Pi session shutdown disconnects only that bridge; it does not stop the shared daemon. Reload migration briefly reconnects Android. Default-port pairings normally continue to work, while a legacy fallback-port or previously selected secondary session may require re-pairing.

Pi package catalog

The Pi extension is published to npm as @pragmaticcoder/pi-remote-control with the pi-package keyword and Pi package manifest metadata. After the repository is public, it should be discoverable through pi.dev/packages.

More docs

• Install guide
• Security model
• Networking recipes
• Development guide
• Support
• Changelog

Compatibility

Component	Requirement
Pi	Current Pi coding agent with extension support
Android	min SDK 26 / Android 8.0+
Node/npm	Node 22 recommended for extension development

Known limitations

• GitHub Releases are the Android distribution path for now; Play Store and F-Droid distribution are not available yet.
• The protocol intentionally uses cleartext ws:// for trusted LAN/VPN/tunnel use rather than internet-facing TLS.
• π Remote controls an existing visible Pi TUI session; it is not a hosted/headless Pi service.

Troubleshooting

• Cannot connect: confirm Pi is in TUI mode, the extension is enabled, and host/port match.
• LAN vs Tailscale confusion: use the laptop's LAN IP on LAN, or its Tailscale IP/name over Tailscale.
• Token mismatch: re-pair or rotate with /remote-control-rotate-token.
• Firewall: allow the configured port on trusted LAN/VPN only.
• Multiple legacy sessions: each Pi TUI may use a different port if the default is busy. The durable daemon intentionally uses one profile port and never falls back to another port.

Uninstall

pi uninstall @pragmaticcoder/pi-remote-control
adb uninstall com.pragmaticcoder.piremote

Screenshot gallery

All screenshots use demo-safe data only.

Composer with image	Header menu	Settings

Session scan	Session picker	Waiting state

Development

./gradlew test assembleDebug
cd pi-extension/remote-control && npm test && npm run typecheck && npm pack --dry-run

Release APKs are signed with keystore/passwords supplied outside git through local.properties or protected GitHub Actions secrets.