Skip to main content
The Insaion Agent is designed to work seamlessly with ROS2-based robotics systems. Follow these steps to install the agent on your ROS2-enabled Debian/Ubuntu robot.

​
Prerequisites

  • Debian/Ubuntu-based system
  • ROS2 installed and configured
  • Internet connection for downloading packages
  • Root/sudo privileges

​
Installation Environment

You can install the Insaion Agent either on the host system (recommended) or inside a Docker container.

​
Docker Installation Notes

If installing inside Docker, ensure your container has:
  • ROS2 environment properly configured
  • Network access to reach Insaion services
  • Persistent storage for agent data (mount /var/lib/insaion-agent/)
  • Access to robot hardware/sensors as needed
ENV ROS_DISTRO=humble
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://raw.githubusercontent.com/insaion/assets/main/install-agent.sh | sudo bash -s --
EXPOSE 9090
ENTRYPOINT ["/usr/bin/start-agent.sh"]
Or run interactively: 
docker run -it --network host -p 9090:9090 -v /var/lib/insaion-agent:/var/lib/insaion-agent your-ros2-image bash

​
Download the Installer

Choose your ROS2 distribution and download with wget or curl. Below are the official release bundles. Pick the archive that matches your ROS2 distribution and download it with wget or curl. Use the installer one-liner which autodetects your ROS2 distribution and installs the corresponding Debian package: 
curl -fsSL https://raw.githubusercontent.com/insaion/assets/main/install-agent.sh | sudo bash -s --
If you prefer to skip autodetection and explicitly install for a specific ROS2 distro, pass the --ros flag: 
curl -fsSL https://raw.githubusercontent.com/insaion/assets/main/install-agent.sh | sudo bash -s -- --ros <distro>
Replace <distro> with your ROS2 distribution name (humble, jazzy, rolling). The installer will:
  • Install necessary dependencies
  • Install and configure Insaion Agent
  • Create a script to start the agent: /usr/bin/start-agent.sh

​
Post-Installation

Once the agent is installed, you have to register the device to your Insaion account. No other configuration is required.

​
Register Your Device (Only Once Per Device)

​
Method 1: Enrollement Key

The enrollment key registration method is ideal for fleets of robots where you want to automate the registration process. Read more about enrollment keys here. Once you have your enrollment key from the Insaion dashboard, set the environment variable and start the agent: 
export ENROLLMENT_KEY="your-enrollment-key-here"
start-agent.sh
If the enrollment key is valid, the agent will register automatically and you should see the device appear in the Insaion Device page.

​
Method 2: Pairing Token

This method is suitable for single devices or test setups as it requires manually entering a token. Read more about pairing tokens here. First, start the agent without any environment variables or credentials: 
start-agent.sh
Then follow these steps:
  1. Go to http://localhost:9090 (or http://[ROBOT_IP]:9090)
  2. Enter Manual Pairing Token from the Insaion dashboard
  3. Click “Register”
Agent local UI If the token is valid, the agent will register and you should see the device appear in the Insaion Device page.