MQTT topics

All topics are namespaced by vela/{device_id}/.... The {device_id} is the UUID assigned at enrollment. Broker is EMQX Cloud Serverless at port 8883 (TLS).

Device → Cloud (agent publishes)

Topic	QoS	Frequency	Purpose
/heartbeat	0	60s*	Device health, thermal, network, peripherals, Pi hardware
/response	1	per ack	Acknowledgements for commands with `command_id`
/policy_report	1	5 min*	Policy vs actual state — compliance / violations
/apps_report	1	5 min*	Installed apps with package, version, versionCode

* tunable via policy.agent.heartbeat_interval_seconds and policy.agent.compliance_report_interval

Cloud → Device (agent subscribes)

Topic	QoS	Purpose
/commands	1	All admin-initiated commands (see commands reference)
/policy	1	Policy JSON pushes (separate from `policy_update` command)

Example heartbeat payload

vela/{device_id}/heartbeatjson

{
  "ts": 1744545600,
  "cpu_temp": 52.3,
  "cpu_usage": 18,
  "ram_used": 2100000000,
  "ram_total": 8000000000,
  "storage_used": 4100000000,
  "storage_total": 31000000000,
  "uptime": 86400,
  "os_version": "AlmaLinux 10.1 bootc (VelaOS 2.1.0)",
  "agent_version": "2.1.0",
  "display_count": 1,
  "display_1": { "width": 1920, "height": 1080, "refresh_hz": 60 },
  "net_type": "ethernet",
  "net_ip": "192.168.1.42",
  "wifi_signal_dbm": -62,
  "thermal_zones": [
    { "name": "cpu-thermal", "temp_c": 52.3 },
    { "name": "soc-thermal", "temp_c": 48.1 }
  ],
  "cpu_governor": "schedutil",
  "cpu_freq_mhz": 1500,
  "fan_rpm": 1800,
  "rtc_drift_seconds": 2,
  "power_sources": [
    { "source": "USB", "voltage_v": 5.1, "current_a": 1.9 }
  ],
  "storage_device": "mmcblk0",
  "storage_writes": 482194,
  "i2c_devices": [...],
  "bluetooth_devices": [...],
  "usb_devices": [...],
  "hdmi_cec": true
}

Example compliance report

vela/{device_id}/policy_reportjson

{
  "compliant": false,
  "policy_version": 12,
  "policy_hash": "a3f9...",
  "violation_count": 2,
  "violations": [
    {
      "field": "security.camera_disabled",
      "expected": "true",
      "actual": "false",
      "severity": "high"
    },
    {
      "field": "restrictions.install_apps",
      "expected": "blocked",
      "actual": "allowed",
      "severity": "medium"
    }
  ],
  "ts": 1744545605
}

Example apps report

vela/{device_id}/apps_reportjson

{
  "app_count": 42,
  "installed_apps": [
    { "package": "com.citrix.receiver", "name": "Citrix Workspace", "version": "24.12.0", "version_code": 24120000 },
    { "package": "com.vmware.view.client.android", "name": "Horizon Client", "version": "2404", "version_code": 24040 },
    ...
  ],
  "ts": 1744545605
}

Authentication

Every MQTT connection uses per-device mTLS: the agent presents a client cert issued by the tenant CA during enrollment. The broker validates the cert chain and maps the device UUID from the cert's CN — there's no username/password.