Why run the Insaion Agent?
- You don’t change your robot’s code. The agent finds your ROS 2 topics and subscribes to them like any other node. There is no SDK to add.
- It copes with bad connections. Telemetry is kept on the device during an outage and sent when the link comes back. Uploads pick up where they stopped, and slow down so they don’t get in the way of your robot’s other traffic.
- Recordings hold up. Recording keeps going while offline, and a sudden power cut loses a second or two of data at most.
- It stays light. Each topic is subscribed to once, for both live telemetry and recording, and every bundled component is built with only what the agent needs.
Key features
- Live telemetry: selected ROS 2 topics, host metrics (CPU, memory, network, disk, temperature, GPU) and logs, streamed to the dashboards and alarms.
- Recording: selected topics written as MCAP to an on-device rolling buffer with a size limit you set, ready to upload and open in the embedded Lichtblick visualizer.
- Uploads on demand: upload any time window from the web app, or let Copilot request one during an incident analysis.
- Device enrollment: automatic registration with an
ENROLLMENT_KEY. - OpenTelemetry: a local OTLP endpoint for your own metrics, logs and traces. See OpenTelemetry.
- Diagnostics: consistent logs across all agent components, and a single command that collects a redacted support bundle.
How data leaves the robot
The agent sends three kinds of data, each in its own way:- ROS 2 telemetry (the topics you monitor) is sent as compressed binary batches over a secure MQTT connection. Messages arrive in the cloud about a second after they are published. Images, point clouds, maps and other large message types are never sent as telemetry. Any single message over 64 KiB is left out too, and the topic gets flagged on the Data Collection page. Record those topics instead.
- Host metrics and logs are sent over HTTPS, compressed.
- Recordings stay on the device until you upload a time window. Uploads go straight to cloud storage in small resumable parts.
When the network drops
- Telemetry is buffered on disk. While the link is down, ROS 2 telemetry is stored in a buffer of up to 1 GiB, enough for about two days at a typical rate. If the buffer passes 70%, each topic is reduced to one message per second so the buffer lasts longer. Only when it is full is the oldest telemetry dropped. Everything in the buffer is sent once the link is back, and nothing shows up twice in your dashboards.
- Host metrics are held in memory for about 30 minutes of outage.
- Recording continues locally, unaffected by the network.
- Uploads wait. An upload in progress resumes from where it stopped. An offline robot retries about once a minute and gives up only after 24 hours without any progress. Uploads requested while the robot is offline are sent to it when it reconnects.
- The agent starts offline. A robot that boots without a connection starts with its last known configuration and begins recording straight away.
- Only Insaion can stop recording. The agent stops collecting only when the Insaion cloud itself refuses the device, for example because the device was deleted or the subscription is unpaid. An error from a proxy or firewall, or a network outage, never stops recording.
When the power drops
Recordings are written to the rolling buffer about once a second, so a sudden power cut loses at most a second or two of the most recent data, on busy and quiet topics alike. Live telemetry waits in memory for up to 5 seconds before it goes to disk, so a power cut can cost up to the last 5 seconds of it. If you can’t afford to lose any of a topic, record it too.Recording on modest hardware
The agent adapts to the storage it runs on. On fast storage, large messages such as camera frames are stored as they arrive. On slow storage such as an SD card, it detects the slow writes and groups data into larger blocks so it keeps up. If the robot ever produces data faster than its storage can take, the agent drops the newest messages and counts them, asros2 bag record does, rather than stalling.
Architecture
The agent runs as a single service. The main process registers the device, subscribes to ROS 2 topics, sends telemetry over MQTT, records, uploads and reports status. It starts and watches two bundled helpers:- ReductStore: the local store that holds the rolling buffer of recordings. It only listens on
127.0.0.1. - Telegraf: collects host metrics and logs. The agent ships a small build with only the plugins it uses.
/var/lib/insaion-agent. The agent prefers to run on the host but can also run in a container, as long as it can reach the ROS 2 network and the host’s hardware information.
Network and disk requirements
Network. The agent only makes outbound connections:- HTTPS (port 443) to
app.insaion.comfor registration, configuration, host metrics and upload coordination. - MQTT over secure WebSocket (port 443) to
wss://app.insaion.com/mqttfor commands and ROS 2 telemetry. - HTTPS (port 443) to the Insaion cloud storage endpoint for recording uploads.
- ICMP ping to
app.insaion.comand8.8.8.8once a minute, to report connectivity.
/var/lib/insaion-agent:
- The rolling buffer: 1 GB by default, set in Device configuration.
- The telemetry buffer: up to 1 GiB, used only during outages.
- About 100 MB per recording set, used only if the local store stalls.
- About 30 MB of rotating logs.
Security
- Devices register with enrollment keys. Rotate enrollment keys periodically.
- All communication with Insaion is encrypted (HTTPS and MQTT over TLS), with certificate validation by default.
- Each device has its own credentials and can only publish and upload its own data.
- The agent runs with only the privileges it needs. Its local storage and OpenTelemetry services listen on
127.0.0.1only. If automatic registration fails, the agent opens a pairing page on port 9090 on all interfaces, which closes once the device is registered.