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: 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, 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. 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:
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:
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:
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

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 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
  • 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:
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.