Skip to main content
The Insaion Agent is a lightweight, secure runtime that runs on your robots and edge devices to connect ROS2-based systems with the Insaion cloud. It collects telemetry, forwards selected ROS2 topics and logs, and enforces local configuration and storage policies. This page gives a high-level view of what the agent does, how it’s structured, and where to find installation and configuration details.

​
Why run the Insaion Agent?

  • Seamless integration with ROS2: the agent is built to coexist with your ROS2 ecosystem (topics, parameters and lifecycle)
  • Reliable telemetry and logs: buffered and resumable uploads to tolerate intermittent connectivity
  • Secure enrollment & device identity: tokens and enrollment keys for safe fleet registration
  • Extensible: components for custom telemetry, alarms and integrations

​
Key features

  • Telemetry collection: topic sampling, custom metrics, periodic system health checks, and host metrics (CPU, memory, network, GPU, disk)
  • Device enrollment: automatic (ENROLLMENT_KEY) or manual pairing via short-lived tokens
  • Lightweight runtime: minimal dependencies, small installer bundles for common ROS2 distros

​
Architecture (high-level)

  • cpp_agent: core native component that bridges ROS2 and the agent runtime (publishes status, subscribes to configured topics)
  • agent service: supervisor, web UI, enrollment flow, and uploader
  • local storage: persisted credentials under /var/lib/insaion-agent/
The agent prefers to run on the host (recommended) but can also be containerised as long as it has access to the necessary hardware resources and ROS2 system.

​
Telemetry and host metrics

In addition to ROS2 topic telemetry and application metrics, the agent collects host-level metrics to help you monitor device health and performance. Typical host metrics include:
  • CPU usage (per-core and aggregate)
  • Memory usage and swap
  • Network throughput and interface statistics
  • Disk usage and I/O
  • GPU utilization and memory (where available)
Host metrics are automatically collected and can be visualized on the Insaion monitoring dashboard right after registration. For full installation and a step-by-step Quickstart, see the Installation page.

​
Security

  • Enrollment uses single-use or time-limited tokens. Rotate enrollment keys periodically.
  • All outbound communication is over HTTPS with certificate validation by default.
  • Agent runs with only the privileges it needs.
If you need an air-gapped deployment, contact your Insaion representative for an offline enrollment workflow.