elizaos--eliza/plugins/plugin-native-gateway

@elizaos/capacitor-gateway

A Capacitor plugin that connects an elizaOS app to an Eliza Gateway server. Provides service discovery via Bonjour/mDNS, authenticated WebSocket connectivity, RPC request/response, and realtime event streaming — with native implementations on iOS (Swift + NWBrowser), Android (Kotlin + OkHttp + NsdManager), and web (browser WebSocket).

---

What it does

• Discovery — finds Eliza Gateway instances on the local network via Bonjour/mDNS (_eliza-gw._tcp). Supports optional wide-area DNS-SD discovery (e.g. via Tailscale). Not available on web.
• Authenticated connection — opens a WebSocket to the gateway, sends a connect frame with credentials (token or password), and negotiates protocol version 3. Returns session ID, role, scopes, and the methods/events the gateway exposes.
• RPC — Gateway.send({ method, params }) sends a JSON request frame and resolves with the response payload or structured error.
• Realtime events — listen to server-pushed events via addListener("gatewayEvent", ...).
• Connection lifecycle — state changes (connecting, connected, disconnected, reconnecting) and errors are surfaced as typed events. Reconnection uses exponential backoff (800 ms → 15 s).

---

Platforms

Platform	Discovery	WebSocket	Notes
iOS	Native Bonjour (NWBrowser)	URLSessionWebSocketTask	Min iOS 15.0
Android	NsdManager	OkHttp	kotlinx.coroutines
Web/Node	Not supported	Browser WebSocket	Discovery returns empty list

---

Installation

npm install @elizaos/capacitor-gateway
npx cap sync

For iOS, add the pod to your Podfile:

pod 'ElizaosCapacitorGateway'

---

API

Import

import { Gateway } from '@elizaos/capacitor-gateway';

Discover gateways

// Start streaming discovery events
await Gateway.addListener('discovery', (event) => {
  if (event.type === 'found') {
    console.log('Found gateway:', event.gateway.name, event.gateway.host, event.gateway.port);
  }
});

await Gateway.startDiscovery({ timeout: 10000 });

// One-shot snapshot
const { gateways } = await Gateway.getDiscoveredGateways();

await Gateway.stopDiscovery();

Connect

const result = await Gateway.connect({
  url: 'wss://192.168.1.42:8080',
  token: 'your-jwt-token',   // or use password: '...'
  clientName: 'my-app',
  role: 'operator',
  scopes: ['operator.admin'],
});

if (result.connected) {
  console.log('Session:', result.sessionId);
  console.log('Role:', result.role);
  console.log('Available methods:', result.methods);
}

Send an RPC request

const response = await Gateway.send({
  method: 'agents.list',
  params: {},
});

if (response.ok) {
  console.log(response.payload);
} else {
  console.error(response.error?.code, response.error?.message);
}

Listen for realtime events

await Gateway.addListener('gatewayEvent', (event) => {
  console.log(event.event, event.payload, event.seq);
});

await Gateway.addListener('stateChange', (event) => {
  console.log('Connection state:', event.state, event.reason);
});

await Gateway.addListener('error', (event) => {
  console.warn(event.message, 'willRetry:', event.willRetry);
});

Disconnect

await Gateway.disconnect();
await Gateway.removeAllListeners();

---

Connection options reference

Option	Type	Default	Description
url	string	required	WebSocket URL (ws:// or wss://)
token	string	—	JWT / bearer token
password	string	—	Password-based auth
clientName	string	"eliza-capacitor"	Client identifier sent in connect frame
clientVersion	string	"1.0.0"	Client version string
sessionKey	string	—	Session key for chat sessions
role	string	"operator"	Role to request from the gateway
scopes	string[]	["operator.admin"]	Scopes to request

---

Building

bun run build        # tsc + rollup → dist/
bun run build:docs   # regenerate README from JSDoc, then build
bun run verify:ios   # pod install + xcodebuild
bun run verify:android  # ./gradlew clean build test

Note: bun run build:docs regenerates this README from JSDoc comments in src/definitions.ts. Manual edits will be overwritten on the next docgen run.