Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.insaion.com/llms.txt

Use this file to discover all available pages before exploring further.

The Insaion Agent can be installed as a Linux systemd service on the target device, or run as a Docker container. The systemd installation is the standard method for robots, gateways, and edge computers running Ubuntu. Docker installation is available for containerized deployments. For systemd: You no longer need to download a package manually or start the agent with a one-off command. The installer configures the machine, installs the agent, enables the service, and starts it automatically. For Docker: Copy and run a generated docker run command with your configuration options.

​
Installation methods

​
Systemd installation

After installation, the device has:
  • A background service: insaion-agent.service
  • A runtime configuration file: /etc/default/insaion-agent
  • Persistent agent state: /var/lib/insaion-agent
  • A local pairing UI on port 9090 for manual registration when the device is not yet enrolled

​
Docker installation

After running the docker command, you have:
  • A running container named insaion-agent
  • Volume mounts for persistent state (/var/lib/insaion-agent), system access (/proc, /sys, /dev), and optional ROS workspaces
  • Environment variables for registration and ROS configuration
  • A local pairing UI on port 9090 for manual registration (pairing method only)

​
Supported environment

​
Systemd installation

  • Ubuntu Linux with systemd
  • Ubuntu 22.04 and 24.04 for generic host installs
  • ROS2-enabled Ubuntu systems, where the installer detects the installed ROS environment and configures the matching agent package automatically
  • Outbound internet access to Insaion services and package repositories
  • sudo or root access

​
Docker installation

  • Linux host with Docker installed and running
  • Any Ubuntu, Debian, or compatible Linux distribution
  • Outbound internet access to Insaion services and container registries
  • Docker socket access (for running as privileged container)
  • Optional: GPU support with nvidia-docker or --gpus flag
  1. In the Insaion web app, go to Devices and click Add Device.
  2. Choose your installation method: Ubuntu (systemd) or Docker.
  3. Choose your registration method: Enrollment Key or Pairing Token.
  4. Configure optional settings: ROS distribution, custom workspace, DDS middleware, etc.
  5. Copy the generated installation command from the wizard.
  6. Run that command on the target machine.
  7. Verify the agent is running (systemctl status for Ubuntu, docker ps for Docker).
  8. If you chose pairing, finish registration in the local web UI at port 9090. If you chose enrollment, the device registers automatically.

​
Install the agent

​
Systemd installation

The installer used by the dashboard is: 
curl -fsSL https://get.insaion.com/setup.sh | sudo bash
If you selected Enrollment Key or additional ROS or DDS options in the Add Device wizard, the dashboard generates the same command with environment variables inline. For example: 
curl -fsSL https://get.insaion.com/setup.sh | sudo ENROLLMENT_KEY="your-enrollment-key" bash
Run the exact command shown in the dashboard on the target machine.

​
Docker installation

The wizard generates a complete docker run command with your configuration. For example: 
docker run -d \
  --name insaion-agent \
  --network host \
  --pid host \
  --cap-add=NET_RAW \
  --gpus all \
  -v /dev/shm:/dev/shm \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc:/host/etc:ro \
  -v /var/lib/insaion-agent:/var/lib/insaion-agent \
  -e ENROLLMENT_KEY="your-enrollment-key" \
  -e RMW_IMPLEMENTATION="rmw_cyclonedds_cpp" \
  ghcr.io/insaion/agent:latest-jazzy
Run the exact command shown in the dashboard on your Docker host.

​
What happens during installation

​
Systemd installer

When you run the installer, it automatically:
  • Detects whether the machine is a generic Ubuntu system or a ROS2-based system
  • Configures the required package repositories
  • Installs agent dependencies
  • Writes installation-time settings into /etc/default/insaion-agent
  • Installs the Insaion Agent package
  • Enables and starts insaion-agent.service
For most users, that is the entire installation process.

​
Docker container startup

When you run the docker command, it:
  • Pulls the container image (if not already present)
  • Creates a container named insaion-agent
  • Mounts required system volumes for hardware access and ROS network configuration
  • Mounts persistent storage for agent state
  • Applies environment variables for registration and ROS configuration
  • Starts the container in the background
The agent comes online immediately once the container is running.

​
Registration methods

You can register a device in one of two ways.

​
Method 1: Enrollment Key

Use enrollment keys for production deployments, golden images, scripted provisioning, and fleet rollout. Read more on the Add device page.

​
Enrollment steps

  1. In the dashboard, choose Enrollment Key in the Add Device wizard.
  2. Paste or select the enrollment key in the wizard.
  3. Copy the generated install command.
  4. Run the command on the device.
  5. The installer stores the enrollment key in /etc/default/insaion-agent, starts the systemd service, and the agent attempts automatic registration.
  6. After successful registration, the device appears in the Devices page.

​
Verify enrollment

sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent -f
If the key is valid and the device has network access, you should see the device appear in the web app shortly after the service starts.

​
Method 2: Pairing Token

Use pairing tokens for one-off devices, lab setups, demos, and interactive debugging. Read more on the Add device page.

​
Pairing steps

  1. In the dashboard, choose Pairing Token in the Add Device wizard.
  2. Copy the generated install command.
  3. Run the command on the target Linux machine.
  4. Once installation completes, open the local pairing page at http://localhost:9090 or http://<device-ip>:9090.
  5. In the dashboard, generate a pairing token.
  6. Paste the token into the local pairing page and submit it.
  7. After successful registration, the device appears in the Devices page.
Agent local UI

​
Service management

​
Systemd (Ubuntu installation)

The agent is managed like any other systemd service: 
sudo systemctl status insaion-agent
sudo systemctl restart insaion-agent
sudo systemctl stop insaion-agent
sudo systemctl start insaion-agent
sudo journalctl -u insaion-agent -f
Use these commands any time you update configuration, want to inspect logs, or need to restart the agent.

​
Docker

Manage the container using standard Docker commands: 
# Check status
docker ps | grep insaion-agent

# View logs
docker logs -f insaion-agent

# Restart
docker restart insaion-agent

# Stop
docker stop insaion-agent

# Start
docker start insaion-agent

# Remove (WARNING: also removes persistent state)
docker rm insaion-agent

​
Configure the agent

​
Systemd (Ubuntu installation)

The main configuration file is: 
/etc/default/insaion-agent
This file is loaded by the systemd service every time the agent starts. You can edit it manually, then restart the service. 
sudo nano /etc/default/insaion-agent
sudo systemctl restart insaion-agent

​
Docker

When running in Docker, configuration is passed via environment variables in the docker run command. To change configuration after the container is created, either: Option 1: Stop and re-run with new variables 
docker stop insaion-agent
docker rm insaion-agent
# Run docker command again with updated environment variables
Option 2: Edit the container’s environment at runtime (not persistent across restarts) Internally, the container uses /etc/default/insaion-agent just like the systemd version. You can exec into the container to edit it: 
docker exec -it insaion-agent bash
sudo nano /etc/default/insaion-agent
# Restart within container or restart the Docker container
Note: Changes are not persistent unless the container filesystem is committed, so Option 1 (recreating the container) is the recommended approach.

​
Common configuration variables

  • ENROLLMENT_KEY: automatically register the device without manual pairing
  • ROS_DISTRO: ROS2 distribution the agent should source before launch
  • CUSTOM_ROS_SETUP: path to an additional ROS workspace setup script, for example a custom messages workspace
  • 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 setting when used in your deployment
  • 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 config location
  • ZENOH_SESSION_CONFIG_URI: Zenoh session config location
  • ZENOH_ROUTER_CHECK_ATTEMPTS: retry count for Zenoh router availability checks
These settings can be passed by the Add Device wizard in the generated command, or edited later in /etc/default/insaion-agent.

​
Example manual configuration

​
Systemd

sudo nano /etc/default/insaion-agent
Add your variables: 
ENROLLMENT_KEY=your-enrollment-key
ROS_DISTRO=jazzy
CUSTOM_ROS_SETUP=/home/robot/ws/install/setup.bash
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
ROS_DOMAIN_ID=42
CYCLONEDDS_URI=file:///home/robot/dds/cyclonedds.xml
Then restart: 
sudo systemctl restart insaion-agent

​
Docker

When generating your docker command in the wizard, or manually updating it: 
docker run -d \
  --name insaion-agent \
  --network host \
  --pid host \
  --cap-add=NET_RAW \
  --gpus all \
  -v /dev/shm:/dev/shm \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /etc:/host/etc:ro \
  -v /var/lib/insaion-agent:/var/lib/insaion-agent \
  -v /home/robot/dds/cyclonedds.xml:/home/robot/dds/cyclonedds.xml:ro \
  -e ENROLLMENT_KEY="your-enrollment-key" \
  -e ROS_DISTRO="jazzy" \
  -e CUSTOM_ROS_SETUP="/home/robot/ws/install/setup.bash" \
  -e RMW_IMPLEMENTATION="rmw_cyclonedds_cpp" \
  -e ROS_DOMAIN_ID="42" \
  -e CYCLONEDDS_URI="file:///home/robot/dds/cyclonedds.xml" \
  ghcr.io/insaion/agent:latest-jazzy

​
Verify installation

​
Systemd

Use the following checklist after install:
  • sudo systemctl status insaion-agent shows the service as running
  • sudo journalctl -u insaion-agent -f shows normal startup logs
  • The device appears on the Devices page after registration
  • If using pairing, the local UI is reachable on port 9090

​
Docker

Use the following checklist after running the container:
  • docker ps | grep insaion-agent shows the container as running
  • docker logs insaion-agent shows startup logs with no errors
  • The device appears on the Devices page after registration
  • If using pairing, the local UI is reachable on port 9090 on the Docker host
  • Check that /var/lib/insaion-agent on the host has writable permissions for the container

​
Docker-specific considerations

​
Required volumes and capabilities

The generated docker command includes specific mounts and capabilities needed for the agent to function:
  • --network host: Allows the agent to communicate with the robot’s ROS network
  • --pid host: Host PID namespace sharing for monitoring host processes
  • --cap-add=NET_RAW: Required for certain network operations
  • --gpus all: Passes GPU devices to the container (if available)
  • -v /dev/shm:/dev/shm: Shared memory for ROS communication
  • -v /proc:/host/proc:ro: Host process information (read-only)
  • -v /sys:/host/sys:ro: Host system information (read-only)
  • -v /etc:/host/etc:ro: Host etc directory (read-only)
  • -v /var/lib/insaion-agent:/var/lib/insaion-agent: Persistent agent state

​
Custom workspace volumes

If you specify a custom ROS workspace directory when running on Docker, the wizard automatically adds a mount for it: 
-v /home/robot/ros2_ws:/home/robot/ros2_ws:ro
This allows the container to access the workspace setup scripts on the host.

​
Persistent state

The container must have a writable volume for /var/lib/insaion-agent. Ensure the host path (/var/lib/insaion-agent by default) has appropriate permissions for the container processes to write state files.

​
Restarting and updating

To update the agent container: 
docker stop insaion-agent
docker rm insaion-agent
# Pull latest image
docker pull ghcr.io/insaion/agent:latest-jazzy
# Re-run the docker command from the wizard with updated image tag

​
Troubleshooting

​
Systemd

The service is not running Check status and view logs: 
sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent -f
The device does not auto-register Confirm ENROLLMENT_KEY is present and correct: 
sudo cat /etc/default/insaion-agent | grep ENROLLMENT_KEY
Then restart the service: 
sudo systemctl restart insaion-agent
The pairing page is not reachable Verify the service is running and that port 9090 is reachable: 
sudo systemctl status insaion-agent
curl http://localhost:9090
Custom ROS messages are missing Set CUSTOM_ROS_SETUP to your workspace setup.bash in /etc/default/insaion-agent and restart: 
sudo systemctl restart insaion-agent
DDS settings are not applied Confirm environment variables are set and referenced files exist: 
sudo grep -E "RMW_IMPLEMENTATION|CYCLONEDDS_URI|FASTRTPS" /etc/default/insaion-agent
ls -la /path/to/dds/config/file

​
Docker

The container is not running Check container status and logs: 
docker ps -a | grep insaion-agent
docker logs insaion-agent
If the container exited, view the full logs: 
docker logs insaion-agent --tail 100
The device does not auto-register Confirm ENROLLMENT_KEY was passed to the container: 
docker inspect insaion-agent | grep -A 30 '"Env"'
If missing, stop the container and re-run with the enrollment key: 
docker stop insaion-agent
docker rm insaion-agent
# Re-run docker command with -e ENROLLMENT_KEY=...
The pairing page is not reachable Verify the container is running and port 9090 is accessible: 
docker ps | grep insaion-agent
curl http://localhost:9090
If the container is not running, check logs for errors. Custom ROS workspace settings are not applied Confirm the volume mount exists and the setup script is present: 
docker inspect insaion-agent | grep -A 20 '"Mounts"'
ls -la /home/robot/ros2_ws/install/setup.bash
Verify the environment variable is set: 
docker inspect insaion-agent | grep CUSTOM_ROS_SETUP
DDS configuration files are not found Ensure that custom DDS configuration files are mounted and the paths in environment variables match: 
docker inspect insaion-agent | grep -A 20 '"Mounts"'
docker inspect insaion-agent | grep -E "CYCLONEDDS_URI|FASTRTPS"
Verify files exist on the host: 
ls -la /home/robot/dds/cyclonedds.xml
Persistent state is not persisting Confirm the volume mount for /var/lib/insaion-agent is correct and writable: 
docker inspect insaion-agent | grep -A 5 '/var/lib/insaion-agent'
ls -la /var/lib/insaion-agent
sudo touch /var/lib/insaion-agent/test && rm /var/lib/insaion-agent/test