System ($SYS) Topics - Coreflux Documentation

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, route 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

Goal	Start here
Confirm the broker is up and which build is running	`$SYS/Coreflux/Version`
Send management commands	`$SYS/Coreflux/Command` and `Command/Output`
Inspect or back up LoT source	`$SYS/Coreflux/Actions/#`, `Models/#`, `Routes/#`, `Rules/#`, `Visus/#`
Watch route health	`$SYS/Coreflux/Routes/+/status`
See which project is loaded	`$SYS/Coreflux/Projects/active`

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

$SYS/
├── Coreflux/
│   ├── Command                    # Publish commands
│   ├── Command/Output             # JSON command replies
│   ├── Config                     # Live configuration (includes Python status)
│   ├── Config/New                 # Publish a config update
│   ├── Config/New/Result          # Result of a config update
│   ├── Config/Users               # User list (passwords masked)
│   ├── Version                    # Broker version
│   ├── License                    # License and usage
│   ├── Resources/                 # Memory totals
│   ├── Comms/
│   │   ├── Sessions               # MQTT sessions
│   │   ├── Clients                # Connected clients
│   │   ├── Logins                 # Login events
│   │   └── PacketTrace/…          # Optional packet traces
│   ├── Actions/<name>             # Action LoT
│   ├── Models/<name>              # Model LoT
│   ├── Routes/<name>              # Route LoT
│   ├── Rules/<name>               # Rule LoT
│   ├── Visus/<name>               # Panel LoT
│   ├── Projects/                  # Project list, active, manifest, download
│   ├── Entities/ownership         # Project vs ad-hoc origin
│   ├── Cluster/                   # Role, leader, members (when clustering)
│   ├── Python/Scripts             # Registered Python scripts
│   └── AI/Providers               # Discovered LLM providers
└── <OS>/                          # e.g. Linux-x64, Windows-x64
    ├── Python/Info
    └── Comms/TCP|UDP/…

Read-only (broker → client)

Topic	Content
`$SYS/Coreflux/Version`	Version JSON (retained)
`$SYS/Coreflux/License`	License, tier, limits, current usage (retained)
`$SYS/Coreflux/Config`	Live configuration JSON, including Python backend status
`$SYS/Coreflux/Config/Users`	Users with passwords masked; includes `Groups`
`$SYS/Coreflux/Config/New/Result`	Outcome of the last publish to `Config/New`
`$SYS/Coreflux/Comms/Sessions`	Active sessions
`$SYS/Coreflux/Comms/Clients`	Connected clients
`$SYS/Coreflux/Comms/Logins`	Login event lines
`$SYS/Coreflux/Actions/{name}`	Action LoT (retained)
`$SYS/Coreflux/Models/{name}`	Model LoT (retained)
`$SYS/Coreflux/Routes/{name}`	Route LoT (retained)
`$SYS/Coreflux/Routes/{name}/status`	Route health JSON
`$SYS/Coreflux/Rules/{name}`	Rule LoT
`$SYS/Coreflux/Visus/{name}`	Panel source (retained)
`$SYS/Coreflux/Projects/list`	Stored projects (retained)
`$SYS/Coreflux/Projects/active`	Loaded project (retained)
`$SYS/Coreflux/Entities/ownership`	Running entities → project origin (retained)

Writable (client → broker)

Topic	Purpose
`$SYS/Coreflux/Command`	Run broker commands
`$SYS/Coreflux/Config/New`	Apply a configuration JSON (restart still required for most fields)
`$SYS/Coreflux/Actions/{name}/Run`	Run a callable Action (panels use this)
`$SYS/Coreflux/Actions/{name}/Invoke`	Same as `/Run` (legacy alias)
`$SYS/Coreflux/Routes/{name}/Events/{event}/Trigger`	Fire a named route event from a panel

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.

Subscribe to output

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

Publish the command

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

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

Field	Value
Topic	`$SYS/Coreflux/Command`
Payload	`-addAction DEFINE ACTION Heartbeat ON EVERY 10 SECONDS DO PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"`
Auth	Session allowed for `CommandCall` (`root` or the matching RBAC permission flags)

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

{
  "success": true,
  "command": "AddAction",
  "message": "Action 'Heartbeat' added successfully.",
  "entityType": "Action",
  "entityName": "Heartbeat",
  "data": {}
}

Field	Description
`success`	Whether the command succeeded
`command`	Internal command name (for example `AddAction`)
`message`	Human-readable summary
`requestId`	Echo of `-requestId` when you sent one
`data`	Structured payload for list/query commands
`errors`	Present when `success` is `false`

The broker does not publish to $SYS/Coreflux/CommandResponse. The full command list is on Broker Commands.

LoT Entity Topics

Each running Action, Model, Route, 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:

Field	Value
Topic	`$SYS/Coreflux/Actions/Heartbeat`

Payload received:

DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

Topic	Content
`$SYS/Coreflux/Actions/{name}/Description`	Optional description (retained)
`$SYS/Coreflux/Actions/{name}/Error`	Last Action error (retained when set)
`$SYS/Coreflux/Actions/{name}/Trace`	Execution traces when tracing is enabled (not retained; expire after a few minutes)
`$SYS/Coreflux/Actions/{name}/Run`	Publish here to run a callable Action
`$SYS/Coreflux/Actions/{name}/Invoke`	Same as `/Run`

`$SYS/Coreflux/Models/{ModelName}`

Model LoT (retained).

`$SYS/Coreflux/Routes/{RouteName}`

Route LoT (retained). Extra subtopics appear depending on the route type:

Topic	Content
`$SYS/Coreflux/Routes/{name}/status`	Health and counters. See Route Status Monitoring
`$SYS/Coreflux/Routes/{name}/Certificates`	Certificate-store summary for cert-managed routes (retained)
`$SYS/Coreflux/Routes/{name}/Tools`	MCP tool summary for MCP routes
`$SYS/Coreflux/Routes/{name}/Tools/{tool}`	One MCP tool (schema and capability stats)
`$SYS/Coreflux/Routes/{name}/Events/{event}/Trigger`	Publish to fire that route event

`$SYS/Coreflux/Rules/{RuleName}`

Rule LoT source.

`$SYS/Coreflux/Visus/{PanelName}`

Panel source text (retained).

Entity type	Topic pattern
All Actions	`$SYS/Coreflux/Actions/#`
All Models	`$SYS/Coreflux/Models/#`
All Routes	`$SYS/Coreflux/Routes/#`
All Rules	`$SYS/Coreflux/Rules/#`
All panels	`$SYS/Coreflux/Visus/#`

Broker Information

`$SYS/Coreflux/Version`

Broker version and build (retained).

{
  "version": {
    "major": 2,
    "minor": 14,
    "patch": 0,
    "branch": "release",
    "os": "Linux-x64",
    "stage": "stable",
    "timestamp": "2026-08-26T10:00:00Z",
    "notes": ""
  }
}

The os field is the same prefix used under $SYS/{OS}/….

`$SYS/Coreflux/License`

License status, tier, feature flags, limits, and current artifact usage (retained). Unlicensed or trial brokers still publish this topic so you can see Tier, IsTrial, and CurrentUsage.

{
  "LicensedTo": "N/A",
  "ExpiresUtc": null,
  "IsActive": false,
  "IsTrial": true,
  "TrialDaysRemaining": 14.0,
  "Tier": "Community",
  "InstanceKey": "",
  "Features": {
    "EnableAdvancedRoutes": false,
    "EnableRBAC": false
  },
  "CurrentUsage": {
    "ArtifactCount": 3,
    "Actions": { "Regular": 2, "RouteEvents": 0, "PythonScripts": 0 },
    "Models": 0,
    "Rules": 12,
    "Routes": 1,
    "Panels": 0
  }
}

`$SYS/Coreflux/Resources`

Topic	Description
`$SYS/Coreflux/Resources/MemoryInfoTotal`	Total available memory (bytes)
`$SYS/Coreflux/Resources/MemoryInfoUsage`	Current memory usage (bytes)

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.

{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "AnonymousLogin": false,
  "Python": {
    "Available": true,
    "UsingEmbeddedRuntime": false,
    "UsingRunner": false,
    "Version": "3.11.2",
    "Backend": "python.net",
    "IsolationLevel": "none"
  }
}

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 writes $SYS/Coreflux/Config/New/Result with success or validation failure text.

`$SYS/Coreflux/Config/Users`

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

[
  {
    "UserName": "root",
    "Password": "********",
    "AllowedBaseTopic": "",
    "AllowedSystemConfiguration": true,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false,
    "Groups": []
  }
]

Field	Description
`AllowedBaseTopic`	Optional topic prefix restriction
`AllowedSystemConfiguration`	Can change broker configuration and most management gates
`AllowedUserManagement`	Can manage users
`AllowedLogManagement`	Can manage log traces
`Groups`	Group names for RBAC

Connection Monitoring

`$SYS/Coreflux/Comms/Sessions`

Active MQTT sessions.

[
  {
    "CreatedTimestamp": "2026-08-26T09:01:36.5008146Z",
    "DisconnectedTimestamp": null,
    "ExpiryInterval": 0,
    "Id": "mqtt-explorer-274f0040",
    "Items": {},
    "PendingApplicationMessagesCount": 0
  }
]

`$SYS/Coreflux/Comms/Clients`

Connected clients, including bytes and packet counts.

[
  {
    "BytesReceived": 173,
    "BytesSent": 3943557,
    "ConnectedTimestamp": "2026-08-26T09:01:36.5008189Z",
    "Endpoint": "172.17.0.1:52256",
    "Id": "mqtt-explorer-274f0040",
    "ProtocolVersion": 4,
    "ReceivedApplicationMessagesCount": 16070,
    "SentApplicationMessagesCount": 0,
    "Session": {
      "Id": "mqtt-explorer-274f0040",
      "PendingApplicationMessagesCount": 0
    }
  }
]

Field	Description
`BytesReceived` / `BytesSent`	Totals for this connection
`Endpoint`	Client IP and port
`Id`	MQTT client ID
`ProtocolVersion`	`3` = MQTT 3.1, `4` = 3.1.1, `5` = 5.0

`$SYS/Coreflux/Comms/Logins`

One line per login attempt (password always masked):

ClientId = lotvstudio-a6kjtbkwp, Endpoint = 172.17.0.1:53454, Username = root, Password = ******, CleanSession = True, ReasonCode = Success

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.

Topic	Content
`$SYS/Coreflux/Projects/list`	Stored projects and which one is active (retained)
`$SYS/Coreflux/Projects/active`	Currently loaded project (retained; empty in standalone mode)
`$SYS/Coreflux/Projects/{name}/status`	Git status for that project (retained)
`$SYS/Coreflux/Projects/{name}/manifest`	SHA-256 of stored file bytes, plus entities declared in `.lotnb` cells (retained). Same JSON as `-projectManifest`. Cleared on `-removeProject`
`$SYS/Coreflux/Entities/ownership`	Map of `type:name` → `{ project, file, cell }` for project-owned entities (retained). Absence of a key means the entity is ad-hoc

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.

{
  "Available": true,
  "Version": "3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0]",
  "Scripts": []
}

Individual scripts also appear at $SYS/{OS}/Python/Scripts/{scriptName}.

TCP and UDP listeners

Topic	Content
`$SYS/{OS}/Comms/TCP/Listeners`	Addresses and ports the process is listening on
`$SYS/{OS}/Comms/TCP/ActiveConnections`	Established TCP connections
`$SYS/{OS}/Comms/UDP/Listeners`	UDP listeners
`$SYS/{OS}/Comms/UDP/ActiveConnections`	Active UDP associations

Example TCP listeners payload:

[
  {"Address": "0.0.0.0", "Port": "1883"},
  {"Address": "0.0.0.0", "Port": "80"}
]

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.

Who	Typical access
`root`, `admin`, `AllowedSystemConfiguration`	Subscribe to `$SYS/#`
`CommandCall` gates	Publish to `$SYS/Coreflux/Command` and subscribe to `Command/Output`
Same roles as `-listProjects`	`$SYS/Coreflux/Projects/#`
Any connected client	Publish to `$SYS/Coreflux/Actions/+/Run` and `/Invoke` (panels call Actions this way)

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

​See the Broker From MQTT

​When to use this

​Topic Hierarchy

​Read-only (broker → client)

​Writable (client → broker)

​Command Topics

​$SYS/Coreflux/Command

​$SYS/Coreflux/Command/Output

​LoT Entity Topics

​$SYS/Coreflux/Actions/{ActionName}

​$SYS/Coreflux/Models/{ModelName}

​$SYS/Coreflux/Routes/{RouteName}

​$SYS/Coreflux/Rules/{RuleName}

​$SYS/Coreflux/Visus/{PanelName}

​Subscribe to all entities

​Broker Information

​$SYS/Coreflux/Version

​$SYS/Coreflux/License

​$SYS/Coreflux/Resources

​Configuration Topics

​$SYS/Coreflux/Config

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

​$SYS/Coreflux/Config/Users

​Connection Monitoring

​$SYS/Coreflux/Comms/Sessions

​$SYS/Coreflux/Comms/Clients

​$SYS/Coreflux/Comms/Logins

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

​Project Topics

​Platform Topics

​$SYS/{OS}/Python/Info

​TCP and UDP listeners

​Access Control

​Next Steps

Broker Configuration

Broker Commands

See the Broker From MQTT

When to use this

Topic Hierarchy

Read-only (broker → client)

Writable (client → broker)

Command Topics

`$SYS/Coreflux/Command`

`$SYS/Coreflux/Command/Output`

LoT Entity Topics

`$SYS/Coreflux/Actions/{ActionName}`

`$SYS/Coreflux/Models/{ModelName}`

`$SYS/Coreflux/Routes/{RouteName}`

`$SYS/Coreflux/Rules/{RuleName}`

`$SYS/Coreflux/Visus/{PanelName}`

Subscribe to all entities

Broker Information

`$SYS/Coreflux/Version`

`$SYS/Coreflux/License`

`$SYS/Coreflux/Resources`

Configuration Topics

`$SYS/Coreflux/Config`

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

`$SYS/Coreflux/Config/Users`

Connection Monitoring

`$SYS/Coreflux/Comms/Sessions`

`$SYS/Coreflux/Comms/Clients`

`$SYS/Coreflux/Comms/Logins`

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

Project Topics

Platform Topics

`$SYS/{OS}/Python/Info`

TCP and UDP listeners

Access Control

Next Steps