elizaos--eliza/plugins/plugin-native-mobile-agent-bridge/README.md

@elizaos/capacitor-mobile-agent-bridge

Outbound tunnel from a phone-hosted Eliza agent so a remote Mac client can reach it. Phone-side companion to the Mac-side TunnelToMobileClient in @elizaos/app-core.

This package owns the phone-to-relay tunnel for a phone-hosted Eliza agent. The JS surface (startInboundTunnel, stopInboundTunnel, getTunnelStatus, stateChange event) is stable. Native implementations hold an outbound WebSocket to the relay and proxy requests into the same local agent route surface used by the rest of the mobile app.

Status

Platform	Status
Web	Fallback. Returns state: "error" with an explanatory message.
iOS	Outbound WebSocket tunnel. Proxies path-only requests through the WebView IPC bridge; no listening port is opened.
Android	Outbound WebSocket tunnel. Proxies path-only requests into the registered ElizaAgentService via reflection; no listening port is opened.

Relay frame protocol

Tunnel frames use a path-only HTTP request envelope. The relay never sends absolute URLs, and the plugin rejects //host and scheme-bearing paths before dispatching to the agent. On iOS, dispatch goes through window.__ELIZA_BRIDGE__?.iosLocalAgentRequest, which is the same Capacitor IPC bridge the UI uses for full-Bun local mode.

Usage

import { MobileAgentBridge } from "@elizaos/capacitor-mobile-agent-bridge";

await MobileAgentBridge.startInboundTunnel({
  relayUrl: "wss://relay.elizacloud.ai/v1/agent-tunnel",
  deviceId: "phone-abc123",
  pairingToken: "...",
});

const status = await MobileAgentBridge.getTunnelStatus();
// { state: "registered" | "error" | ..., relayUrl, deviceId, lastError }

await MobileAgentBridge.stopInboundTunnel();