@inaiii/pi-remote-extension

Connect local Pi sessions directly to Pi Remote Server. Helper is optional and only needed to start/manage Pi processes from the browser.

Requirements

• macOS or Linux with Unix user IDs, private user-owned files, and system file locking. Setup and maintenance use lockf on macOS or flock on Linux, plus /bin/sh and /bin/cat.
• Pi stable >=1.0.0 <2.0.0, with the APIs required by each feature; currently tested with 1.0.0, 1.1.0, and 1.2.0. Node 22.19.0+ is required for Pi and the maintenance CLI.
• A reachable Pi Remote Server and an enrollment token for first setup.

Native Windows Node is not supported by either the Extension or its maintenance CLI. On Windows, run Node, Pi and the Extension inside WSL2 Linux, and keep installation state in the Linux user home directory on a filesystem with Unix ownership and permissions. Git Bash, or invoking Windows-installed Node/Pi from WSL, does not meet these requirements. WSL2 uses the Linux path; a complete WSL2 setup/connect/recovery run has not been verified.

Setup rejects unsupported platforms before asking for connection details or creating installation state; the maintenance CLI rejects them before accessing that state. Setup failures identify the step and distinguish local files, locks, configuration, network/TLS and Server rejection without exposing credentials or raw errors.

If Device credentials were saved but Runtime authorization failed, setup retains them: leave the token empty when retrying to reuse them, subject to Server authorization. A lost enrollment response leaves the result unconfirmed and the token may already have been consumed. Setup does not automatically re-enroll or reset the installation.

This package contains the Extension and an on-demand Node maintenance CLI. It does not install Helper, Server or Web. Pi's coding-agent, AI and TUI APIs are host-provided peer dependencies; the bundle includes its other runtime dependencies. Load it through Pi's extension loader.

Install and connect

pi install npm:@inaiii/pi-remote-extension

For prereleases, select npm:@inaiii/pi-remote-extension@next. In Pi:

/remote-control setup
/remote-control on
/remote-control status

Setup configures the shared device identity and Server connection. Manual sessions require explicit consent; /remote-control off disables it for the current session. Managed sessions use the scoped launch connection prepared by the optional Helper. Credentials do not enter native Session entries.

/remote-control status shows the loaded/installed Extension versions, detected Pi version, supported host range, supported features and missing API requirements, alongside Runtime execution capabilities and connection state. Active Runtime diagnostics use the checks captured at activation; /reload refreshes them. Checking a disabled session does not enable Remote.

Optional Helper

On macOS, install the separate Helper to launch Pi from the browser:

npx @inaiii/pi-remote-helper@latest install

It reuses the shared enrollment. Helper and Extension versions are independent; neither package updates or installs the other. Managed Pi uses normal extension discovery with --offline, so required packages must already be installed.

Update and remove

pi update npm:@inaiii/pi-remote-extension
npx @inaiii/pi-remote-extension@latest disconnect
pi remove npm:@inaiii/pi-remote-extension

Use /reload or restart an existing Pi to load updated code. Updating files does not replace running code. Disconnect existing Remote instances before removing the package; their native Pi tasks keep running. Removing the package does not uninstall Helper or delete native sessions.

Installation maintenance

npx @inaiii/pi-remote-extension@latest status
npx @inaiii/pi-remote-extension@latest disconnect
npx @inaiii/pi-remote-extension@latest reset

The maintenance CLI's status includes each active instance's host compatibility snapshot under compatibility; older loaded instances need /reload to provide this field.

disconnect preserves credentials and data, stops existing Remote connections, reporting, recovery and queued delivery, and keeps them disabled across reconnect/session changes. /remote-control on explicitly enables only the selected session. Helper's Launcher remains available for a subsequent new managed launch.

reset stops the associated Helper and its managed Wrapper/Pi processes, stops Remote in manually started Pi, and removes the local shared identity/credentials and Remote state. Manual Pi tasks, native sessions, work, package files and Helper installation configuration remain. Helper's registered service stays stopped. A subsequent setup creates a new Device identity; use Helper start to adopt it. Server history and remote Device revocation remain Server management actions.

These operations show the scope and ask once (Continue? [y/N]). Pass --yes / -y for noninteractive execution. Use --installation-dir or PI_REMOTE_INSTALLATION_DIR for a custom shared installation. Active older writers leave recovery cleanup pending; status reports it and a later reset can finish. Historical loaded Extensions that do not acknowledge maintenance require /reload; the command reports incomplete disconnection instead of terminating native Pi.

License

MIT