Agent Operations

Use this page after installing the Insaion Agent. It covers routine service management, configuration changes, logs, support bundles, updates, and troubleshooting for systemd and Docker deployments.

Service management

Systemd

The agent runs as insaion-agent.service:

sudo systemctl status insaion-agent
sudo systemctl restart insaion-agent
sudo systemctl stop insaion-agent
sudo systemctl start insaion-agent

Docker

Manage the container with standard Docker commands:

# Check status
docker ps -a --filter name=insaion-agent

# Restart, stop, or start
docker restart insaion-agent
docker stop insaion-agent
docker start insaion-agent

Configure the agent

Systemd

Runtime configuration is stored in /etc/default/insaion-agent. Edit the file and restart the service to apply changes:

sudo nano /etc/default/insaion-agent
sudo systemctl restart insaion-agent

Docker

Docker configuration is supplied through environment variables. To make a persistent change, stop and remove the container, then run the command generated by the Add Device page again with the updated values:

docker stop insaion-agent
docker rm insaion-agent
# Run the updated docker command from the Add Device page.

Removing the container does not remove agent state stored in the mounted /var/lib/insaion-agent host directory.

Common variables

ENROLLMENT_KEY: automatically register the device
ROS_DISTRO: ROS2 distribution sourced before launch
CUSTOM_ROS_SETUP: path to an additional ROS workspace setup script
RMW_IMPLEMENTATION: DDS middleware selection, such as CycloneDDS or Fast DDS
ROS_DOMAIN_ID: ROS domain ID for discovery isolation
ROS_AUTOMATIC_DISCOVERY_RANGE: ROS discovery range
ROS_STATIC_PEERS: static peer list for ROS discovery
ROS_LOCALHOST_ONLY: restrict ROS traffic to localhost when required
FASTRTPS_DEFAULT_PROFILES_FILE: Fast DDS profile path
ROS_DISCOVERY_SERVER: Fast DDS discovery server address
CYCLONEDDS_URI: CycloneDDS configuration URI
ZENOH_ROUTER_CONFIG_URI: Zenoh router configuration location
ZENOH_SESSION_CONFIG_URI: Zenoh session configuration location
ZENOH_ROUTER_CHECK_ATTEMPTS: retry count for Zenoh router availability checks

Telemetry settings

These settings tune how live ROS 2 telemetry is sent and buffered. The defaults suit most robots; change them only for a specific need. They require agent 1.0.0 or later.

Variable	Default	What it does
`INSAION_METRICS_MAX_MESSAGE_BYTES`	`65536` (64 KiB)	Largest single message sent as live telemetry. Larger messages are dropped from telemetry and the topic is flagged in Data Collection. Recording is not affected.
`INSAION_TELEMETRY_SPOOL_MAX_BYTES`	1 GiB	Disk space for telemetry buffered during an outage.
`INSAION_TELEMETRY_SPOOL_MIN_FREE_BYTES`	512 MiB	Free space the telemetry buffer always leaves on its disk, so recordings never run out of room. `0` turns the reserve off.
`INSAION_CDR_BATCH_LINGER_MS`	`1000`	Longest time telemetry waits to be batched before it is sent. Lower values reduce latency at the cost of more, smaller messages.
`INSAION_CDR_SPILL_AFTER_MS`	`5000`	How long unsent telemetry stays in memory before it is written to disk. This is the most live telemetry a power cut can lose while online.
`INSAION_CDR_MEMORY_MAX_BYTES`	16 MiB	Memory used for telemetry waiting to be sent.

Logging and diagnostics

The agent uses a standardized log format across its components. Each record includes a timestamp, severity level, and thread identifier. Persistent agent logs also include the source file and line number. Output from managed Telegraf and ReductStore processes is captured in the same stream with a component tag, making events easier to follow in chronological order. For systemd, follow live service logs with:

sudo journalctl -u insaion-agent -f

For Docker, use:

docker logs -f insaion-agent

The agent also keeps rotating logs and recent diagnostic snapshots under /var/lib/insaion-agent/. Mount this directory as persistent storage in Docker to retain diagnostics across container restarts.

Check the agent’s status

The agent writes a status summary to /var/lib/insaion-agent/agent_status.json every 10 seconds. It is a quick way to see, on the robot, what the agent is doing:

sudo cat /var/lib/insaion-agent/agent_status.json

Useful sections:

cdr_uplink: live telemetry. records_published and bytes_published grow while telemetry flows; spool_bytes_pending shows telemetry buffered during an outage, waiting to be sent; records_dropped and records_throttled count telemetry dropped or reduced because the buffer was full; spool_low_disk is true when the buffer is shrinking to leave room for recordings.
recording: recording health. segments_dropped counts recorded data dropped because storage could not keep up.
ros2: the topics being monitored and recorded, and rejected_oversize_messages_count, the messages dropped from telemetry for being too large.

Create a support bundle

When reporting an issue, generate a redacted support bundle:

sudo insaion-agent --support-bundle

The command requests a fresh diagnostic snapshot without stopping the running service. It writes a compressed .tar.gz archive to /tmp and prints the full path when complete. Choose a specific output path with:

sudo insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz

The bundle includes available agent and service logs, runtime status, recent failure and shutdown diagnostics, host health information, Telegraf configuration, and ROS2 graph information when ROS2 is enabled. Configuration secrets are replaced with [REDACTED], and device tokens are not included. Review the archive before attaching it to an issue or sending it to Insaion support. For Docker, create the bundle inside the container and copy it to the host:

docker exec insaion-agent insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
docker cp insaion-agent:/tmp/insaion-support.tar.gz ./insaion-support.tar.gz

Update the agent

Systemd

If the Insaion package repository is still configured, update the agent with the standard system upgrade workflow:

sudo apt update
sudo apt upgrade

This upgrades the agent together with other eligible system packages. The package preserves /etc/default/insaion-agent and the state stored under /var/lib/insaion-agent, then restarts the service after the agent upgrade. You can also re-run the installation command generated by the Add Device page. This is useful when you want to update only the agent or restore its package repository configuration. If APT keeps the agent back or reports a Telegraf version conflict, re-run the current installation command to remove package holds created by older installer versions, then run the upgrade again.

Upgrading from 0.10.x to 1.0.0

The upgrade needs no extra steps. The device keeps its registration, its configuration and the recordings already in its rolling buffer, and recordings made by the older agent can still be uploaded. After the upgrade:

ROS 2 telemetry moves from HTTPS to the agent’s existing secure MQTT connection. No firewall change is needed: it uses the same host and port 443.
The recording split duration disappears from Data Collection for this device: 1.0.0 writes recordings about once a second and ignores it.
The Uploads settings appear in the rolling buffer panel.
Topics with messages over 64 KiB are flagged as too large for live telemetry. They were already too heavy to monitor well; record them instead.

Upgrade the robots before relying on the new upload behaviour: resumable uploads, upload priority and link-sharing need agent 1.0.0 on the robot.

Docker

Pull the current image and recreate the container with the same configuration and persistent state mount:

docker stop insaion-agent
docker rm insaion-agent
docker pull ghcr.io/insaion/agent:latest-jazzy
# Run the updated docker command from the Add Device page.

Replace latest-jazzy with the image tag used by your deployment.

Troubleshooting

The service or container is not running

For systemd:

sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent --since "30 minutes ago" --no-pager

For Docker:

docker ps -a --filter name=insaion-agent
docker logs insaion-agent --tail 100

The device does not register automatically

Confirm that ENROLLMENT_KEY is present in the systemd configuration:

sudo grep '^ENROLLMENT_KEY=' /etc/default/insaion-agent
sudo systemctl restart insaion-agent

For Docker, verify that the variable was supplied to the container:

docker inspect insaion-agent | grep ENROLLMENT_KEY

If it is missing, recreate the container using the command from the Add Device page.

Custom ROS messages are missing

Set CUSTOM_ROS_SETUP to the workspace setup.bash path. For Docker, also mount that workspace into the container at the configured path. Restart or recreate the agent after the change.

DDS settings are not applied

Check the configured middleware variables and verify that referenced files exist:

sudo grep -E 'RMW_IMPLEMENTATION|CYCLONEDDS_URI|FASTRTPS' /etc/default/insaion-agent
ls -la /path/to/dds/config/file

For Docker, confirm that the same paths are mounted inside the container.

Live telemetry stopped but the device is online

Check whether the topic is flagged too large in Data Collection. Then check the telemetry section of the status file:

sudo grep -A 25 '"cdr_uplink"' /var/lib/insaion-agent/agent_status.json

If spool_bytes_pending keeps growing, telemetry is being buffered instead of sent: the agent cannot reach wss://app.insaion.com/mqtt. Check that outbound WebSocket connections on port 443 are allowed. Buffered telemetry is delivered once the connection returns.

The disk is filling up

The rolling buffer is limited by its size in Device configuration, and the telemetry buffer by INSAION_TELEMETRY_SPOOL_MAX_BYTES. Check what is using the space:

sudo du -sh /var/lib/insaion-agent/*

The telemetry buffer always leaves 512 MiB free for recordings, so a long outage cannot stop recording. If the disk is still too small, lower the rolling buffer size or INSAION_TELEMETRY_SPOOL_MAX_BYTES.

Docker state is not persisting

Confirm that /var/lib/insaion-agent is mounted and writable on the host:

docker inspect insaion-agent | grep -A 5 '/var/lib/insaion-agent'
ls -la /var/lib/insaion-agent
sudo touch /var/lib/insaion-agent/test && sudo rm /var/lib/insaion-agent/test

If an issue remains unresolved, create a support bundle and include it with the issue report.

Getting Started

Insaion Agent

Insaion Copilot

Devices

Sites

Monitoring

Alarms

Logs

Settings

Reference

Service management

Systemd

Docker

Configure the agent

Systemd

Docker

Common variables

Telemetry settings

Logging and diagnostics

Check the agent’s status

Create a support bundle

Update the agent

Systemd

Upgrading from 0.10.x to 1.0.0

Docker

Troubleshooting

The service or container is not running

The device does not register automatically

Custom ROS messages are missing

DDS settings are not applied

Live telemetry stopped but the device is online

The disk is filling up

Docker state is not persisting

​Service management

​Systemd

​Docker

​Configure the agent

​Systemd

​Docker

​Common variables

​Telemetry settings

​Logging and diagnostics

​Check the agent’s status

​Create a support bundle

​Update the agent

​Systemd

​Upgrading from 0.10.x to 1.0.0

​Docker

​Troubleshooting

​The service or container is not running

​The device does not register automatically

​Custom ROS messages are missing

​DDS settings are not applied

​Live telemetry stopped but the device is online

​The disk is filling up

​Docker state is not persisting

Service management

Systemd

Docker

Configure the agent

Systemd

Docker

Common variables

Telemetry settings

Logging and diagnostics

Check the agent’s status

Create a support bundle

Update the agent

Systemd

Upgrading from 0.10.x to 1.0.0

Docker

Troubleshooting

The service or container is not running

The device does not register automatically

Custom ROS messages are missing

DDS settings are not applied

Live telemetry stopped but the device is online

The disk is filling up

Docker state is not persisting