Agents

The agent is the probe that runs on your server to check what can’t be seen from outside.

An agent only talks outbound to xNode360 (no ports to open) and repeats a cycle every 30 seconds: it downloads its assigned checks, runs them locally, sends the results. Sending is also its heartbeat.

Agent status

Assigning a node to an agent

The quickest way: open the node and press + Add agent. The wizard creates the agent (named after the node), assigns it to the node and gives you the command to paste on the server; in the last step you see the agent connect. Alternatively, in the inspector pick the “agent” runner and the agent from the list. A node with the agent runner but no agent selected will never be checked.

With MCP you can ask your AI assistant to do it for you: create_agent creates the agent, assigns the nodes and returns the command to run on the server. The assistant can’t install anything on its own: you run the command.

Pause, delete and uninstall

• Pause — from the agent list (or via MCP) you switch its checks off without touching the server: the agent stops running probes, its nodes go back to unknown (“agent paused”) and it sends just one heartbeat every 5 minutes. Resume with “resume”.
• Delete — removes the agent and revokes its token immediately. Assigned nodes are left without an agent (“agent missing”) until you reassign them.
• Uninstall — on the server the agent stays installed until you remove it with curl -fsSL https://xnode360.com/install.sh | sudo bash -s -- --uninstall. xNode360 can’t delete files or services remotely: that would be an open door into your servers.

How it communicates

By default the agent sends its results over HTTPS every 30 seconds. It can instead use MQTT over TLS (port 8883, falling back to 443 over WebSocket), always and only outbound: an agent going down is noticed within seconds and a node changing state is reported at once, without waiting for the next cycle.

• It needs a three-part token (mapId.agentId.secret, the ones the app creates now): old two-part tokens stay on HTTP.
• For now it’s opt-in: in /etc/xnode360/agent.env add XNODE360_MQTT_URL=mqtts://mqtt.xnode360.com:8883 and restart with sudo systemctl restart xnode360-agent.
• If the broker can’t be reached the agent falls back to HTTP on its own and retries MQTT. In the logs you see → mqtt or → report.

With MQTT, when the agent stops being heard its nodes turn unknown at once (“agent unreachable”) and, after a one-minute confirmation, the dedicated alert fires.

Alerts and notifications

Token

On creation the agent gets a token in the form mapId.agentId.secret, shown only once. Only the hash of the secret stays in the database. Deleting the agent makes the token stop working.

“Reset” (↺) on a map also deletes the map’s agents: their tokens must be recreated.

Agent installation and security · Health checks and runners