@buoy-gg/sync-broker

Host the Socket.IO message router used by Buoy Desktop and MCP. It routes device capabilities, watched snapshots, and remote actions between device and dashboard clients. Most users should run Desktop or MCP instead of hosting this package directly.

Install

npm install @buoy-gg/sync-broker

This is a Node host package. Use the exported createBroker, socketHandle, and protocol types when implementing a custom host.

Host a broker

The host must independently validate its Buoy account and supply admission through canUseDesktop. The default denies access. This integration sketch expects your host's existing account object; hasAccess() must reflect current verified admission, not merely the presence of a key:

import { createBroker, DEFAULT_BROKER_PORT } from "@buoy-gg/sync-broker";

const broker = createBroker({
  port: DEFAULT_BROKER_PORT,
  canUseDesktop: () => account.hasAccess(),
  onListening: (port) => console.log(`Broker listening on ${port}`),
  onError: (error) => console.error(error),
});

// Call when your account lifecycle changes admission:
broker.refreshAccess();

// Call during host shutdown:
await broker.close();

Keep account revalidation and expiry handling active for the host's lifetime. Refresh routing when access changes. Device and client admission is separate from the host callback. A listening HTTP endpoint does not prove that a device has been admitted.

Try connecting to an existing broker before starting another. If startup reports EADDRINUSE, connect to the broker already using that port or resolve the conflict. The default port is 42831.

Existing HTTP server

For an existing Socket.IO server, use socketHandle({ io, canUseDesktop }) and retain its returned refreshAccess function. Your host owns the HTTP server, Socket.IO options, account lifecycle, and shutdown. Do not attach routing twice to the same server.

Message flow

Devices announce capabilities. Dashboard watch requests control adapter subscriptions; the broker consolidates those requests. Device snapshots flow to watching clients, while named actions and their results travel in the opposite directions. Broker logs help diagnose admission, connection, and protocol problems. Offline device history is in memory and can be forgotten or age out.

Network and verification

The standalone server listens without a loopback-only host restriction. Default CORS allows any origin; CORS is not client authentication. Use a trusted development network and review access controls before exposing a custom host beyond it. Account admission does not establish app-specific authorization for every remote action.

Test with a verified host and device account: connect, watch a known tool, and confirm its snapshot. Then revoke host admission and verify that access closes. Reconnect after restoring valid access and check that watch state resumes. See the Desktop guide and MCP guide for supported end-user hosts.