@agimon-ai/po-remote
Remote access gateway for a Po host: the tunnel, pairing, device trust, passkey step-up, the dev proxy and host federation.
Package details
Install @agimon-ai/po-remote from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@agimon-ai/po-remote- Package
@agimon-ai/po-remote- Version
0.0.0-alpha.183- Published
- Nov 22, 2026
- Downloads
- 2,174/mo · 2,174/wk
- Author
- agiflow-ai
- License
- BUSL-1.1
- Types
- extension
- Size
- 2.1 MB
- Dependencies
- 12 dependencies · 1 peer
Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@agimon-ai/po-remote
Remote access gateway for a Po host: the tunnel, pairing, device trust, passkey step-up, the dev proxy and host federation.
Requirements and composition
Requires Node.js 24 or newer. Po ships this package as a fixed foundation on Node: the CLI composes it, so it is never selected in .po/presets.yaml. Cloud does not load it.
Entries
@agimon-ai/po-remote:createRemoteRuntime, which the CLI starts once per host and binds as po-core'spo/remote-gateway;createRemoteApi, the/api/remotepackage API;relayDevProxySocketfor the web server's dev proxy; andcreateDefaultHubFederation.@agimon-ai/po-remote/extensions/web: the Remote control settings page and its summary line, the rail status spot each template marks (rail-status), and the remote access and pairing approval dialogs. The phone's Remote control screen stays in po-native: device trust is app-owned, and a plugin's native transport refuses/api/remote.
po-core never imports this package. The contracts it implements live in @agimon-ai/po-core/remoteContract (route names, settings and device types, own-device route classification), @agimon-ai/po-core/remoteOrigin and @agimon-ai/po-core/sessionMcpContract (which Session MCP routes are public, host-only or phone-reachable). Federation grant storage lives in @agimon-ai/po-federation, which Cloud also loads.
Independent connections
The approved ConnectionsOff and ConnectionsOn exports in RemoteAccessDialog.stories.tsx exercise RemoteConnectionsDialog. The dialog reads the tunnel and relay states separately. The relay card links the host through Po Cloud and only mints pairing codes after relay admission. The tunnel card never starts, stops, or pairs the relay. Its use is optional.
Local connection controls are /api/remote/{relay,tunnel}/{state,enable,disable,codes} plus transport-specific pairing approval and session revocation. They require the local presentation origin and CSRF header. The existing local /api/remote/disable stops both listeners. Legacy environment-configured relay and LAN modes retain their one-listener behavior.
Each listener owns its pairing codes, sessions, channels, timers, and failures. Native can explicitly scan the other connection's QR for a host whose signer it already trusts. The host verifies a fresh origin-bound proof with the existing trusted device key, and issues a new session on the chosen connection. No cookies move across. A refused switch does not try another route. Revoking the trusted key ends its sessions on both routes.
dualRemote.test.ts exercises both connections with an isolated host and fake carriers. This does not demonstrate a live public tunnel, staging pairing, or physical-device acceptance. Private relay pairing in the host dialog uses the Po app; Cloud browser bootstrap is a separate acceptance requirement.
Help and authoring
The package publishes src/prompts/help-how-to-remote/SKILL.md through a named resource route and llms.txt. Keep additional guides package-owned and in the publish allowlist; do not export Markdown or copy it into dist.
The build generates host entries from named src/extensions routes. For extension layout, scoped services and lifecycle obligations, follow Po architecture.
Development
Run the package's build, typecheck, test, and lint scripts from this directory. Use npm pack --dry-run to inspect published contents before release.
License
Business Source License 1.1: free for personal use, organisations under USD 1M revenue, non-profits and education. See LICENSE and https://agimon.ai/licensing.