Appearance
Cloud Connect Message Protocol
The Cloud Connect Message Protocol defines a set of JSON based messages for interating with, controlling and receiving updates from Nodes (typically Experience Agents) connected to the Experience Manager.
The document defines each of the available messages, expected send/receive Topics.
For more information on Cloud Connect and getting started, see: Cloud Connect Overview.
Table of Contents
Message Schema
Messages sent Cloud Connect are sent as stringified JSON and are expected to conform a specific message shema:
| Property | Description |
|---|---|
msg | The message type string literal (see below) |
data | The data payload with schema defined by the message type |
mid | The message ID, typically a random string, sent back with an Ack message to confirm receipt |
Example message template:
json
{
"msg": "",
"data": {},
"mid": ""
}With Python clients, Pydantic is typically used to send and receive messages. A base Pydantic sceme, with received added for clients that receive messages:
python
from datetime import datetime
from pydantic import BaseMessage
class BaseControlMessage(BaseModel):
msg: None
mid: Optional[str] = None
data: Dict = {}
received: datetime = Field(default_factory=datetime.now)
def __str__(self):
return self.__repr__()
def __repr__(self) -> str:
return f'<Message: {self.msg}>'Experience Agent Core
The Atlas Experience Agent may be controlled remotely via Cloud Connect. This section outlines request and response messages core the Experience Agent.
io.upswell.xagent.Ack
Acknowledgement to sender, but receiver that the message was received and processed. Always sent on the ack/<node nanoid> topic.
| Property | Description |
|---|---|
msg | Literal: io.upswell.xagent.Ack |
data | The original payload sent that is being acknowledged |
mid | The mid from the original data payload, or a random 10-char string (if data does not contain an mid) |
success | Was the requested action performed correctly? |
Example:
json
{
"msg": "io.upswell.xagent.Ack",
"mid": "abcdefghij",
"data": {
"msg": "io.upswell.xagent.ApplicationStart",
"mid": "abcdefghij"
},
"received": "0000-00-00 00:00:00Z00",
"success": true
}io.upswell.xagent.Ping
Requests that the Node respond with a Pong message. Ping is used to ensure that a Node is online with Cloud Connect before taking further action in the web console and may be used for any application where you want to check the connection status.
Ping does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.Ping",
"mid": "abcdefghij"
}io.upswell.xagent.Pong
Respond to a Ping message with a Pong via the Node’s ack topic.
Pong does not accept any data parameters and can be left off.
Sent on the ack/<node nanoid> topic.
Example:
json
{
"msg": "io.upswell.xagent.Pong",
"mid": "abcdefghij"
}io.upswell.xagent.Reboot
Requests that the Node reboot its underlying hardware.
Reboot does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.Reboot",
"mid": "abcdefghij"
}io.upswell.xagent.Restart
Requests that the Node restart itself. This is useful for troubleshooting, but may also be used to reload content.
Restart does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.Restart",
"mid": "abcdefghij"
}Node Signals
Node Signals are broadcast by a Node via it’s ack topic providing real-time status update on state and profile information about the Node.
io.upswell.xagent.signal.NodeOffline
NodeOffline is broadcast whenever a Node goes offline (disconnects to the Cloud Connect broker).
NodeOffline does not accept any data parameters and can be left off.
Sent on the ack/<node nanoid> topic.
json
{
"msg": "io.upswell.xagent.NodeOffline",
"mid": "abcdefghij"
}io.upswell.xagent.signal.NodeOnline
NodeOnline is broadcast whenever a Node comes online (connects to the Cloud Connect broker).
NodeOnline does not accept any data parameters and can be left off.
Sent on the ack/<node nanoid> topic.
json
{
"msg": "io.upswell.xagent.NodeOnline",
"mid": "abcdefghij"
}io.upswell.xagent.signal.NodeProfile
The NodeProfile message broadcasts system profile metrics and details about running applications via the Node’s ack topic.
Data properties:
| Property | Description |
|---|---|
cpu | Current CPU load as an average across all cores. |
disk | Percentage of the primary storage device consumed. |
gpu | Current CPU load as an average across all cores. |
memory | Current GPU load (only available for devices with NVIDIA GPU's). |
processes | Key/value object where the key is the namespace of an application assigned to a Node and the value is a boolean indicating if the application is running or not. |
Sent on the ack/<node nanoid> topic.
Example:
json
{
"msg":"io.upswell.xagent.signal.NodeProfile",
"mid":"abcdefghij",
"data":{
"cpu": 3.98,
"disk": 1.7,
"gpu": null,
"memory": 80.0,
"processes":{
"<application namespace>": true
}
},
"received":"2025-07-14T06:53:00.006205"
}Application Manager
The Atlas Experience Agent contains the Application Launcher sub-process which is used to launch and manage application processes (Applications).
The following messages may be used to remotely control the Application Launcher process.
While the Experience Agent may receive Application Launcher messages on the Cluster topic, cluster/<cluster nanoid> it is recommended to send messaged directly to a Node on the node topic: node/<node nanoid>.
io.upswell.xagent.ApplicationRestart
Requests that a running application on a Node be restarted by the applications namespace ID ns (i.e. studio.upswell.MyApplication).
Data properties:
| Property | Description |
|---|---|
id | The Application ns (namespace) of the application to restart. |
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationRestart",
"mid": "abcdefghij",
"data": {
"id": "<application namespace>"
}
}io.upswell.xagent.ApplicationRestartAll
Requests that all running Applications on a Node restart.
ApplicationRestartAll does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationRestartAll",
"mid": "abcdefghij"
}io.upswell.xagent.ApplicationStart
Start/launch an application on a Node by the applications namespace ID ns (i.e. studio.upswell.MyApplication).
Data properties:
| Property | Description |
|---|---|
id | The Application ns (namespace) of the application to start. |
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationStart",
"mid": "abcdefghij",
"data": {
"id": "<application namespace>"
}
}io.upswell.xagent.ApplicationStartAutolaunch
When configuring a Node Template, Applications may be configured to auto-launch when the agent starts. ApplicationStartAutolaunch will request that the Node launch all autolaunch applications. This is useful for testing after calling ApplicationStopAll.
ApplicationStartAutolaunch does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationStartAutolaunch",
"mid": "abcdefghij"
}io.upswell.xagent.ApplicationStop
Stop a running application on a Node by the applications namespace ID ns (i.e. studio.upswell.MyApplication).
Data properties:
| Property | Description |
|---|---|
id | The Application ns (namespace) of the application to stop. |
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationStop",
"mid": "abcdefghij",
"data": {
"id": "<application namespace>"
}
}io.upswell.xagent.ApplicationStopAll
Request that all running Applications on a Node stop/close.
ApplicationStopAll does not accept any data parameters and can be left off.
Sent on the cluster/<cluster nanoid> or the node/<node nanoid> topics.
Example:
json
{
"msg": "io.upswell.xagent.ApplicationRestartAll",
"mid": "abcdefghij"
}Control
io.upswell.xagent.ControlRequest
The ControlRequest message allows for control of devices connected to a Liminal Control Gateway Node using Remote Procedure Calls (RPC). Methods and data payloads will vary by interface see Liminal Control Gateway for more comprehensive documentation.
Data properties:
| Property | Description |
|---|---|
device | The device alias as set when configuring Node Controle (Note may not always be the same as the Node alias). |
method | The name of the method to invoke on the controlled device. |
data | (optional) For methods requiring input, a dictionary/object of named parameters. |
retry | (optional) integer |
Sent on the ctl/<cluster nanoid> or the node/<node nanoid> topics.
json
{
"msg": "io.upswell.xagent.ControlRequest",
"device": "dsp",
"method": "control",
"data": {
"id": "2060"
}
}io.upswell.xagent.ControlResponse
The ControlResponse provides a response to a control request, or may be sent unsolicited when a client implements a streaming TCP connection or status check at a regular interval.
| Property | Description |
|---|---|
device | The device alias the response was sent from. |
method | The name of the method to invoked on the controlled device. |
data | The response values as a dictonary/object, when an error occurs, data will contain the key error with the error message. |
status_code | The status of the requested action as an HTTP status code. |
Sent on the ack/<node nanoid> topics.
json
{
"msg": "io.upswell.xagent.ControlResponse",
"device": "dsp",
"method": "control",
"data": {
"type": "ControlState",
"id": "2060",
"value": 256
},
"status_code": 200
}System
io.upswell.xmanager.Alert
WARNING
Alert is defined, but does not have a stable schema and should not be used until the schema is specified.
io.upswell.xmanager.Update
Broadcast a content update (addition, edit) to a record in the Experience Manager. This is used with objects such as Nodes, CMS Models/Records and Media records to update/refresh the objects state/content with the web console.
Data properties:
| Property | Description |
|---|---|
model | The model (content type) of the object being updates (i.e. clusters.Node) |
id | The uuid of the object being updated. |
Sent on the system topic.
json
{
"msg": "io.upswell.xmanager.Update",
"mid": "abcdefghij",
"data": [
{
"model": "clusters.Node",
"id": "0e0d8a01-8e98-406e-884b-a3b316f5749a"
}
]
}