> ## 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.

# Installation

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

## Recommended workflow

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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](../devices/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

```bash theme={null}
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](../devices/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.

<img src="https://mintcdn.com/insaion/_EjWRpi818l6Nv0B/assets/agent/agent-web-server.png?fit=max&auto=format&n=_EjWRpi818l6Nv0B&q=85&s=a1306763b57fd1b8f28c31f13e75d036" alt="Agent local UI" width="823" height="622" data-path="assets/agent/agent-web-server.png" />

## Service management

### Systemd (Ubuntu installation)

The agent is managed like any other systemd service:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
/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.

```bash theme={null}
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**

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
sudo nano /etc/default/insaion-agent
```

Add your variables:

```bash theme={null}
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:

```bash theme={null}
sudo systemctl restart insaion-agent
```

### Docker

When generating your docker command in the wizard, or manually updating it:

```bash theme={null}
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:

```bash theme={null}
-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:

```bash theme={null}
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:

```bash theme={null}
sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent -f
```

**The device does not auto-register**

Confirm `ENROLLMENT_KEY` is present and correct:

```bash theme={null}
sudo cat /etc/default/insaion-agent | grep ENROLLMENT_KEY
```

Then restart the service:

```bash theme={null}
sudo systemctl restart insaion-agent
```

**The pairing page is not reachable**

Verify the service is running and that port `9090` is reachable:

```bash theme={null}
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:

```bash theme={null}
sudo systemctl restart insaion-agent
```

**DDS settings are not applied**

Confirm environment variables are set and referenced files exist:

```bash theme={null}
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:

```bash theme={null}
docker ps -a | grep insaion-agent
docker logs insaion-agent
```

If the container exited, view the full logs:

```bash theme={null}
docker logs insaion-agent --tail 100
```

**The device does not auto-register**

Confirm `ENROLLMENT_KEY` was passed to the container:

```bash theme={null}
docker inspect insaion-agent | grep -A 30 '"Env"'
```

If missing, stop the container and re-run with the enrollment key:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
docker inspect insaion-agent | grep -A 20 '"Mounts"'
ls -la /home/robot/ros2_ws/install/setup.bash
```

Verify the environment variable is set:

```bash theme={null}
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:

```bash theme={null}
docker inspect insaion-agent | grep -A 20 '"Mounts"'
docker inspect insaion-agent | grep -E "CYCLONEDDS_URI|FASTRTPS"
```

Verify files exist on the host:

```bash theme={null}
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:

```bash theme={null}
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
```

<div className="insaion-footer" role="contentinfo">
  <div className="insaion-footer__card">
    <div className="insaion-footer__content">
      <span className="insaion-footer__icon" aria-hidden="true">
        <svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false" className="insaion-footer__svg" role="img">
          <path fill="currentColor" d="M21 6.5A3.5 3.5 0 0 0 17.5 3h-11A3.5 3.5 0 0 0 3 6.5v5A3.5 3.5 0 0 0 6.5 15H8v3l3-3h6.5A3.5 3.5 0 0 0 21 11.5v-5zM7 8.5a1 1 0 1 1 0 2 1 1 0 0 1 0-2zm4 0a1 1 0 1 1 0 2 1 1 0 0 1 0-2zm4 0a1 1 0 1 1 0 2 1 1 0 0 1 0-2z" />
        </svg>
      </span>

      <div>
        If something's unclear or you hit a blocker, contact us on

        <a href="https://discord.gg/ZJMPfMmu3S" target="_blank" rel="noopener">
          Discord
        </a>

        or <a href="mailto:contact@insaion.com">[contact@insaion.com](mailto:contact@insaion.com)</a>
      </div>
    </div>
  </div>
</div>