Native Modules

The Eliza desktop app exposes platform capabilities to the web renderer through a set of native modules running in the Electrobun Bun host. Each module is initialized in initializeNativeModules(), and Bun-side request handlers are wired through registerRpcHandlers().

Renderer code talks to the host through window.__ELIZA_ELECTROBUN_RPC__:

• request.<method>(params) for request/response calls into Bun
• onMessage(name, listener) / offMessage(name, listener) for Bun push events

There are 10 native modules with 140+ request aliases and push messages in total, covering agent lifecycle, desktop integration, network discovery, voice I/O, wake-word detection, screen capture, camera, canvas windows, geolocation, and system permissions.

RPC Alias Conventions

The source of truth still keeps legacy channel-style aliases in rpc-schema.ts using the pattern <module>:<action> (for example agent:start, desktop:registerShortcut, gateway:startDiscovery). The public renderer API maps those aliases onto camelCase request methods and message names.

Examples:

• agent:start → window.__ELIZA_ELECTROBUN_RPC__.request.agentStart()
• desktop:registerShortcut → window.__ELIZA_ELECTROBUN_RPC__.request.desktopRegisterShortcut(...)
• agent:status push event → window.__ELIZA_ELECTROBUN_RPC__.onMessage("agentStatusUpdate", ...)

Direction describes the communication model:

• request — renderer calls Bun and awaits a response
• message — Bun pushes an event to the renderer

const rpc = window.__ELIZA_ELECTROBUN_RPC__;

// Request: call a native module and await its response
const status = await rpc.request.agentStart();

// Message: listen for push notifications from the Bun host
rpc.onMessage("agentStatusUpdate", (status) => {
  console.log(status.state);
});

Modules

• Agent — embedded Eliza runtime lifecycle
• Desktop Manager — tray, shortcuts, windows, notifications, clipboard, shell
• Gateway Discovery — mDNS/Bonjour local network scanning
• Talk Mode — speech-to-text and text-to-speech pipeline
• Swabble — wake-word detection
• Screen Capture — screenshots and screen recording
• Camera — camera enumeration, preview, and recording
• Canvas — auxiliary BrowserWindow management and A2UI injection
• Location — IP-based geolocation
• Permissions — system permission checking and requesting

Agent

Class: AgentManager | Channels: 4 invoke, 1 event

Manages the embedded elizaOS agent runtime lifecycle — starting, stopping, restarting, and monitoring the local agent process.

Return type — AgentStatus:

interface AgentStatus {
  state: "not_started" | "starting" | "running" | "stopped" | "error";
  agentName?: string;
  port?: number;
  startedAt?: string;
  error?: string;
}

Desktop Manager

Class: DesktopManager | Channels: 32 invoke, 20 events

The largest native module. Wraps desktop system APIs for the tray, global shortcuts, auto-launch, window management, native notifications, power monitoring, clipboard, and shell operations.

Tray

Global Shortcuts

Auto Launch

Window Management

Notifications

Power Monitoring

App

Clipboard

Shell

Gateway Discovery

Class: GatewayDiscovery | Channels: 4 invoke, 1 event

Scans the local network for _eliza._tcp services using mDNS/Bonjour and surfaces discovered gateway instances to the renderer.

Talk Mode

Class: TalkModeManager | Channels: 10 invoke, 7 events

Manages the full speech pipeline: speech-to-text via Whisper or the Web Speech API, and text-to-speech via ElevenLabs or the system TTS engine.

Swabble

Class: SwabbleManager | Channels: 6 invoke, 3 events

Runs continuous wake-word detection in the background using fuzzy phrase matching. Whisper is used for transcription when available.

Screen Capture

Class: ScreenCaptureManager | Channels: 9 invoke, 1 event

Provides access to screen sources, screenshots, and screen recording.

• App-window capture uses native OS tooling by default:
  • macOS: screencapture
  • Windows: PowerShell System.Drawing.CopyFromScreen
  • Linux: scrot, falling back to ImageMagick import
• Game URL capture uses a dedicated BrowserWindow path when a game URL is provided.

Camera

Class: CameraManager | Channels: 10 invoke, 0 events

Manages camera enumeration, live preview, photo capture, and video recording via a hidden renderer window. Permission checks are integrated directly into the module.

Canvas

Class: CanvasManager | Channels: 16 invoke, 3 events

Creates and manages auxiliary BrowserWindow instances ("canvas windows") for headless or visible web navigation, JavaScript evaluation, snapshot capture, and A2UI message injection.

Window Lifecycle

Navigation

Snapshots

A2UI Messaging

Visibility and Bounds

Events

Location

Class: LocationManager | Channels: 4 invoke, 2 events

Provides IP-based geolocation with position watching and local caching. Results are pushed as events for watched positions.

Permissions

Class: PermissionManager | Channels: 9 invoke, 1 event

Checks and requests OS-level permissions for accessibility, screen recording, microphone, camera, and shell access. Behavior varies by platform (macOS, Windows, Linux).

Usage Example

const rpc = window.__ELIZA_ELECTROBUN_RPC__;

// Register a global shortcut from the renderer
await rpc.request.desktopRegisterShortcut({
  id: "open-chat",
  accelerator: "CmdOrCtrl+Shift+M",
});

// Listen for the shortcut being pressed
rpc.onMessage("desktopShortcutPressed", ({ id }) => {
  if (id === "open-chat") openChatWindow();
});

// Start the embedded agent
const status = await rpc.request.agentStart();
console.log(status.state); // "starting" | "running" | "error"

// React to live agent state changes
rpc.onMessage("agentStatusUpdate", (nextStatus) => {
  updateAgentIndicator(nextStatus);
});

// Check a permission before using a feature
const cameraPermission = await rpc.request.permissionsCheck({ id: "camera" });
if (cameraPermission.status !== "granted") {
  await rpc.request.permissionsRequest({ id: "camera" });
}

The renderer usually should not call this global directly. Prefer the shared app helpers in eliza/packages/app-core/src/bridge/electrobun-rpc.ts, which wrap the same preload bridge behind request/message helpers used by the app and plugins.

Related

• Desktop App — overview of the desktop application architecture
• Deep Linking — eliza:// URL protocol handled via the Canvas module
• Capacitor Plugins — equivalent native plugin system for iOS and Android