Skip to main content

See the Broker From MQTT

You do not need a separate monitoring stack to know what the broker is doing. Subscribe to $SYS topics and you get version, license, connected clients, LoT source, connector health, and project state as MQTT messages — the same way you already consume sensor data.
Think of $SYS as the broker’s dashboard in topic form. Subscribe like any other MQTT topic and watch live status, without opening a separate UI.

When to use this

Topics that start with $ are not included when you subscribe to # at the root. Subscribe to $SYS/# (or a more specific $SYS/… filter) explicitly.

The tables below are the map; later sections explain payloads and who may publish or subscribe.

Topic Hierarchy

Read-only (broker → client)

Writable (client → broker)


Command Topics

Send a command and read the reply over MQTT. Subscribe to the output topic before you publish, or you can miss a fast reply.
1

Subscribe to output

Using any MQTT client (such as MQTT Explorer), subscribe to $SYS/Coreflux/Command/Output.
2

Publish the command

Publish the command string to $SYS/Coreflux/Command. Add -requestId <id> when several commands may be in flight.
3

Read the JSON envelope

Every reply is one JSON object on Command/Output. Match requestId when you sent one.

$SYS/Coreflux/Command

Direction: Client → Broker

$SYS/Coreflux/Command/Output

Direction: Broker → Client Replies always use this JSON envelope. Structured list/query results are in data. data is always present ({} when there is nothing to return, or [] for an empty list).
The broker does not publish to $SYS/Coreflux/CommandResponse. The full command list is on Broker Commands.

LoT Entity Topics

Each running Action, Model, Connector, Rule, and panel publishes its LoT (or panel source) on a topic named after that entity. Subscribe to retrieve what is actually deployed — useful for backup, debugging, and Coreflux HUB. When you remove an entity, the broker publishes an empty retained payload on that topic (MQTT tombstone) so subscribers do not keep a stale definition.

$SYS/Coreflux/Actions/{ActionName}

Payload: the complete Action definition (retained). Subscribe with MQTT Explorer or any MQTT client: Payload received:
Related Action topics:

$SYS/Coreflux/Models/{ModelName}

Model LoT (retained).

$SYS/Coreflux/Routes/{connector_name}

Connector LoT (retained). Extra subtopics appear depending on the connector type:

$SYS/Coreflux/Agents/{agent}

Agent source (retained). Agents are not listed under $SYS/Coreflux/Routes/. See Agent topics. The broker does not publish $SYS/Coreflux/Agents/{agent}/Capabilities or …/Metrics.

$SYS/Coreflux/Things/{name}

Every Thing is published retained. An empty payload means the Thing was removed. See LoT THING. Children keep their own topics ($SYS/Coreflux/Routes/…, $SYS/Coreflux/Agents/…). $SYS/Coreflux/Entities/ownership marks each child with thing: { root, chain, clause } and lists each Thing as thing:<name>.

$SYS/Coreflux/Rules/{RuleName}

Rule LoT source.

$SYS/Coreflux/Visus/{PanelName}

Panel source text (retained).

Subscribe to all entities


Broker Information

$SYS/Coreflux/Version

Broker version and build (retained).
The os field is the same prefix used under $SYS/{OS}/….

$SYS/Coreflux/License

License status, tier, feature flags, limits, current usage, activation mode, fingerprint, and organization enrollment (retained). The same status is served on ops GET /license (default port 9100; HTTP names are camelCase). Brokers with no license still publish this topic so you can see Tier (Community), EffectiveLimits, and CurrentUsage. There is no built-in trial: with no license the payload shows Community. A trial is a 30-day Growth-type license from portal.coreflux.org that you activate on the broker. Use the same portal to manage your fleet. See Licensing and Enrollment.
JSON still uses Routes for connectors. Enrollment.Pending: false means no problem was recorded — not proof that the broker is bound to an organization.

$SYS/Coreflux/Resources


Configuration Topics

$SYS/Coreflux/Config

The live broker configuration as JSON. The broker adds a Python object so you can see whether scripts run locally or on the runner sidecar without also subscribing to $SYS/{OS}/Python/Info.
ServerCertificatePassword is masked as ********. Publishing the masked value back to $SYS/Coreflux/Config/New keeps the stored password.
To change configuration, publish JSON to $SYS/Coreflux/Config/New. Most fields still need a restart. See Broker Configuration.

$SYS/Coreflux/Config/New and …/Result

Publish a partial configuration object to $SYS/Coreflux/Config/New. The broker merges that object into the live configuration and keeps every omitted field, including bind addresses. It then writes $SYS/Coreflux/Config/New/Result with success or validation failure text. See Applying Configuration.

$SYS/Coreflux/Certificates/Summary

Retained certificate health for the broker’s TLS identity and mTLS trust store. The broker publishes it after every -brokerCertificates change and at most every 5 minutes otherwise. The HUB status bar reads it. It carries no host paths.
total through unreadable count client certificates in the storage path (revoked ones excluded). alerts adds the server certificate and Root CA. level is expired, expiring, or ok. When the storage path is unavailable, pathOk is false and the counts are 0.

$SYS/Coreflux/Config/Users

Configured users with passwords masked. Groups is the list used by USER IN GROUP in Rules.

MCP Server

When the MCP Server is enabled, the broker republishes two retained topics. Neither payload includes token values or the usernames tokens map to.

$SYS/Coreflux/MCP/Info

Status of the Streamable HTTP listener (status is running or stopped). Subscribe in MQTT Explorer to read http_endpoint, bind_ip, http_port, tokens_active, and the currently advertised tools list.

$SYS/Coreflux/MCP/Tools

An array of { "name": "…" } objects for tools the running server currently advertises. When EnableAllTools is false and EnabledTools is empty, this list is empty.

Connection Monitoring

$SYS/Coreflux/Comms/Sessions

Active MQTT sessions.

$SYS/Coreflux/Comms/Clients

Connected clients, including bytes and packet counts.

$SYS/Coreflux/Comms/Logins

One JSON object per login attempt. The password is not included.
For an OIDC access token, Username is the token subject and DisplayName is the token’s display name (empty when the token has none). A local login leaves DisplayName empty and puts the broker username in Username. Lifecycle Actions (ON CONNECT / ON DISCONNECT) are a better place for automation; this topic is for observability. See Action triggers.

$SYS/Coreflux/Comms/PacketTrace/{clientId}/In and /Out

Optional raw packet traces started with -mqttPacketTrace. Use only while debugging a specific client.

Project Topics

Retained so Coreflux HUB and other clients get the last project state on subscribe, without sending -listProjects first. See Project Commands. Export payloads on $SYS/Coreflux/Projects/{name}/download are not retained (one-shot zip transfer).
Under default rules, $SYS/Coreflux/Projects/# is allowed for the same users who may use -listProjects (AllowedUserManagement, AllowedSystemConfiguration, root, admin) — not every MQTT user.

Platform Topics

These topics are prefixed with the operating system identifier (for example Linux-x64, Windows-x64). Read os from $SYS/Coreflux/Version.

$SYS/{OS}/Python/Info

Python availability and version on that host.
Individual scripts also appear at $SYS/{OS}/Python/Scripts/{scriptName}.

TCP and UDP listeners

Example TCP listeners payload:

Access Control

$SYS uses the SubscribeSys and PublishSys rule scopes. Locked built-in rules already decide who may subscribe to $SYS/#, publish commands, and update config. A custom SubscribeSys rule on $SYS/# does not override those gates. See Rules syntax and RBAC for flags and locked rules.
Publish access to $SYS/Coreflux/Command lets a client run administrative commands. Keep that topic on management users only. /Run and /Invoke are allowed more widely so dashboards can call Actions — restrict those Actions themselves if they are sensitive.

Next Steps

Broker Configuration

Change ports, TLS, and other broker settings

Broker Commands

Full command list published to $SYS/Coreflux/Command
Last modified on October 25, 2026