> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# System ($SYS) Topics

> Monitor the broker, read configuration, and control Coreflux over MQTT system topics

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

> [!TIP]
>
> **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` |

> [!WARNING]
>
> 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](/v2.14/mqtt-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.

**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

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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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](/v2.14/mqtt-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:**

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

Related Action topics:

| 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](/v2.14/lot-language/routes/overview#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**).

#### Subscribe to all entities

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

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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`.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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`.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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"
  }
}
```

> [!NOTE]
>
> To change configuration, publish JSON to `$SYS/Coreflux/Config/New`. Most fields still need a restart. See [Broker Configuration](/v2.14/mqtt-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.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
[
  {
    "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](/v2.14/lot-language/rules/rbac) |

***

## Connection Monitoring

### `$SYS/Coreflux/Comms/Sessions`

Active MQTT sessions.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
[
  {
    "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.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
[
  {
    "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](/v2.14/lot-language/actions/events).

### `$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](/v2.14/mqtt-broker/commands#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).

> [!NOTE]
>
> 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.

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
[
  {"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](/v2.14/lot-language/rules/syntax#system-topics-sys) and [RBAC](/v2.14/lot-language/rules/rbac) for flags and locked rules.

> [!WARNING]
>
> 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](/v2.14/mqtt-broker/configuration)**
>
> Change ports, TLS, and other broker settings

> **[Broker Commands](/v2.14/mqtt-broker/commands)**
>
> Full command list published to `$SYS/Coreflux/Command`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.