Realtime channels

Subscribe to live changes and device-control events over Supabase Realtime at wss://api.busymate.net/realtime/v1 — the same socket the dashboard and the iOS app use to stay in sync without polling.

Realtime is authenticated by the same OAuth access token you use for REST and MCP. The token's role gates which channels you may join, so you only ever receive events you're allowed to see.

Two delivery modes

Busymate uses both of Realtime's mechanisms:

• Broadcast — named channels carry small, purpose-built control + firehose messages. This is the primary path: the row-level auth check happens once at channel-join time, so it scales to a high insert rate.
• postgres_changes — table-level change data capture (CDC). Subscribe to INSERT/UPDATE/DELETE on a specific table and receive the changed row. Useful when you want to mirror a table's state.

Connecting

Use @supabase/supabase-js (or any client that speaks the Realtime protocol). Point it at the Busymate host and attach your OAuth token:

import { createClient } from "@supabase/supabase-js";
 
const supabase = createClient("https://api.busymate.net", PUBLISHABLE_KEY, {
  global: { headers: { Authorization: `Bearer ${TOKEN}` } },
});

The client opens wss://api.busymate.net/realtime/v1 under the hood; you work with channels.

Broadcast channels

Each channel carries a fixed set of named events. The table below marks who each channel is for — channels meant for integrators vs. ones that exist to drive a specific Busymate client (you can observe some of them, but they're designed for that client).

Broadcast messages are not durable. For a gap-free viewer, subscribe first, then read the newest window over REST; repeat that bounded read after a stable socket reconnect and deduplicate by event id. The dashboard uses this pattern for device_events:all, so an event emitted during a network handoff appears without a page reload.

PAC/proxy rows use detail.producer: "proxy-server" and carry their process provenance (proxy_build, node_version, process_boot_id, producer_seq) inside detail; iOS-only envelope fields such as ios_version, app_build, boot_id, seq, and device ts are null. The device_health projection remains iOS-only: PAC/proxy and unknown future producers are still durable and live here, but cannot refresh or overwrite phone health.

device:<uuid> events

The per-device channel multiplexes several control flows. The topic name is literally device: followed by the device's uuid (for example device:6f1c…):

Two more events ride the workspace topics from dashboard 838 on, both driven by the server-maintained counters ledger described in Wipe history & counters:

Most device:<uuid> events are a private control plane between Busymate's own tools and a device. They're documented here for completeness; integrators typically use the REST writes or the MCP tools that publish them rather than broadcasting directly.

The entries firehose

Three topics carry captured entries, all with the same envelope — only the audience differs:

The fan-out runs once per ingest statement (a client's upload batch), with a single device lookup per batch, so a burst of captures costs one trigger pass rather than one per row. What arrives depends on a server-side switch:

Per-record mode (the default) — one message per captured row:

{
  "table": "entries",
  "operation": "INSERT",            // or "UPDATE" — a CONNECT envelope closing from active to its final status
  "record": {
    "id": 5821, "ts": "…", "device_uuid": "…", "workspace_id": "…",
    "kind": "http", "host": "api.example.com", "path": "/v1/orders", "url": "…",
    "payload": { /* headers + bodies stripped */ "bodyStripped": true, "headersStripped": true }
  }
}

record is the light row: request/response bodies and headers are stripped (the bodyStripped / headersStripped markers say so) and the search text is null — read the full entry over REST or the get_entry MCP tool when you need it.

Batch mode (off by default) — an operator can flip the workspace-wide setting realtime.entriesBatchBroadcast on the server (no deploy). INSERTs then arrive as one message per topic per ≤ 50 rows of an ingest statement; UPDATEs stay per-record:

{
  "table": "entries",
  "operation": "INSERT",
  "batch": true,
  "count": 37,
  "records": [ /* ≤ 50 light rows, same shape as `record` */ ]
}

A consumer must accept both shapes — payload.record or payload.records[]. Batch mode is on since 2026-09-13 (#2873): one records[] frame per ingest statement (up to 50 rows) per topic. Busymate's own consumers (the dashboard, the /demo feed, the bmc connector) accept both.

Subscribing to a workspace feed

const rows = (payload) =>
  Array.isArray(payload.records) ? payload.records : payload.record ? [payload.record] : [];
 
const channel = supabase
  .channel("ws:" + WORKSPACE_ID, { config: { private: true } })
  .on("broadcast", { event: "INSERT" }, ({ payload }) => {
    if (payload.table !== "entries") return;
    for (const entry of rows(payload)) console.log("entry →", entry.host);
  })
  .on("broadcast", { event: "UPDATE" }, ({ payload }) => {
    for (const entry of rows(payload)) console.log("closed →", entry.id);
  })
  .subscribe();

Treat it as a live tail of new captures + breakpoint changes for that workspace. Subscribe as a plain owner to ws:<workspace_id>:<your_user_id> instead; for a single device, subscribe device:<uuid> and filter on payload.table === "entries" (the other events on that topic carry no table).

Where the /demo feed comes from. The public demo page is a real consumer of this contract: it joins the private device:<uuid>:entries topic of the visitor's own sandbox device (the anonymous visitor owns that device, so the private join passes) and renders the INSERT broadcasts — it does not use postgres_changes on the entries table, which is no longer published for CDC (see below).

postgres_changes (table-level CDC)

For tables you want to mirror, subscribe to row changes directly. The same capability gate applies — a token without the relevant view capability silently receives no rows.

const channel = supabase
  .channel("device-watch")
  .on(
    "postgres_changes",
    { event: "*", schema: "public", table: "devices" },
    ({ eventType, new: row }) => console.log(eventType, row),
  )
  .subscribe();

Tables published for CDC include devices, breakpoint_events, workspace_tabs, tags, service_groups, device_status, settings_global, settings_device, and the single-row service_stats / service_status snapshot tables plus stats_rollup_state (see Stats & status for the live-monitor pattern).

devices is published with full row identity, so UPDATE events include the previous values — handy for detecting renames.

entries is not published for CDC. Captured entries fan out only as the broadcasts above (ws:<workspace_id>, the owner-scoped variant, device:<uuid>:entries); a postgres_changes subscription on entries subscribes successfully and then never receives a row. Decoding every captured row for the WAL poller was the single largest cost of a capture burst, and no live feed needed it.

Access control

Channel subscription is RLS-gated server-side:

• You may join shared channels your role can read.
• device:<uuid> and device-scoped fan-outs are limited to devices you own (or any device, if you're admin).
• A token lacking the relevant capability never receives the events — it just stays quiet.

This is the same role model as REST and MCP. See Roles & permissions.

Troubleshooting