Skip to main content
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: 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

​
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

​
Supported environment

​
Systemd installation

  • Ubuntu Linux with systemd
  • Ubuntu 22.04, 24.04 and 26.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. Select an existing enrollment key, or create a new one on the spot.
  4. Switch on any optional settings: ROS distribution, custom workspace, DDS middleware, etc.
  5. Copy the generated installation command.
  6. Run that command on the target machine.
  7. Watch the Agent status block on the same page — it reports when the agent has registered, connected, and discovered topics.

​
The Add Device page

Everything happens on one page: pick the installation method, then scroll. The install command updates live as you change options, and the page detects your device once the agent comes online. Add device page

​
Install the agent

​
Systemd installation

The installer used by the dashboard is:
The Add Device page generates the same command with your enrollment key and any ROS or DDS options inline. For example:
Run the exact command shown in the dashboard on the target machine.

​
Docker installation

The Add Device page generates a complete docker run command with your configuration. For example:
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 method

Devices register using an enrollment key.

​
Enrollment Key

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

​
Enrollment steps

  1. In the dashboard, open Devices → Add Device.
  2. Select an existing enrollment key, or create a new one on the page.
  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.
Enrollment steps

​
Verify enrollment

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. After the device is registered, use Agent Operations for service management, configuration, logs, support bundles, updates, and troubleshooting.

​
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

​
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
  • 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 generated command automatically adds a mount for it:
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. For ongoing management or issue resolution, see Agent Operations.