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).

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…):

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.

Subscribing to a workspace feed

const channel = supabase
  .channel("ws:" + WORKSPACE_ID, { config: { private: true } })
  .on("broadcast", { event: "INSERT" }, ({ payload }) => {
    // a newly captured entry
    console.log("entry →", payload.record?.host);
  })
  .subscribe();

The exact event names and payload shape on ws:<workspace_id> mirror the broadcast-from-database envelope ({ record, old_record, … }). Treat it as a live tail of new captures + breakpoint changes for that workspace.

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, entries, breakpoint_events, workspace_tabs, tags, service_groups, device_status, settings_global, settings_device, and the single-row service_stats / service_status snapshot tables (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.

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