@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.

Packages

Package details

extension

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's po/remote-gateway; createRemoteApi, the /api/remote package API; relayDevProxySocket for the web server's dev proxy; and createDefaultHubFederation.
  • @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.