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

# Agent Operations

> Manage, configure, diagnose, update, and troubleshoot an installed Insaion Agent.

Use this page after installing the Insaion Agent. It covers routine service management, configuration changes, logs, support bundles, updates, and troubleshooting for systemd and Docker deployments.

## Service management

### Systemd

The agent runs as `insaion-agent.service`:

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

### Docker

Manage the container with standard Docker commands:

```bash theme={null}
# Check status
docker ps -a --filter name=insaion-agent

# Restart, stop, or start
docker restart insaion-agent
docker stop insaion-agent
docker start insaion-agent
```

## Configure the agent

### Systemd

Runtime configuration is stored in `/etc/default/insaion-agent`. Edit the file and restart the service to apply changes:

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

### Docker

Docker configuration is supplied through environment variables. To make a persistent change, stop and remove the container, then run the command generated by the Add Device wizard again with the updated values:

```bash theme={null}
docker stop insaion-agent
docker rm insaion-agent
# Run the updated docker command from the Add Device wizard.
```

Removing the container does not remove agent state stored in the mounted `/var/lib/insaion-agent` host directory.

### Common variables

* `ENROLLMENT_KEY`: automatically register the device without manual pairing
* `ROS_DISTRO`: ROS2 distribution sourced before launch
* `CUSTOM_ROS_SETUP`: path to an additional ROS workspace setup script
* `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
* `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 configuration location
* `ZENOH_SESSION_CONFIG_URI`: Zenoh session configuration location
* `ZENOH_ROUTER_CHECK_ATTEMPTS`: retry count for Zenoh router availability checks

## Logging and diagnostics

The agent uses a standardized log format across its components. Each record includes a timestamp, severity level, and thread identifier. Persistent agent logs also include the source file and line number. Output from managed Telegraf and ReductStore processes is captured in the same stream with a component tag, making events easier to follow in chronological order.

For systemd, follow live service logs with:

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

For Docker, use:

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

The agent also keeps rotating logs and recent diagnostic snapshots under `/var/lib/insaion-agent/`. Mount this directory as persistent storage in Docker to retain diagnostics across container restarts.

### Create a support bundle

When reporting an issue, generate a redacted support bundle:

```bash theme={null}
sudo insaion-agent --support-bundle
```

The command requests a fresh diagnostic snapshot without stopping the running service. It writes a compressed `.tar.gz` archive to `/tmp` and prints the full path when complete.

Choose a specific output path with:

```bash theme={null}
sudo insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
```

The bundle includes available agent and service logs, runtime status, recent failure and shutdown diagnostics, host health information, Telegraf configuration, and ROS2 graph information when ROS2 is enabled. Configuration secrets are replaced with `[REDACTED]`, and device tokens are not included. Review the archive before attaching it to an issue or sending it to Insaion support.

For Docker, create the bundle inside the container and copy it to the host:

```bash theme={null}
docker exec insaion-agent insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
docker cp insaion-agent:/tmp/insaion-support.tar.gz ./insaion-support.tar.gz
```

## Update the agent

### Systemd

If the Insaion package repository is still configured, update the agent with the standard system upgrade workflow:

```bash theme={null}
sudo apt update
sudo apt upgrade
```

This upgrades the agent together with other eligible system packages. The package preserves `/etc/default/insaion-agent` and the state stored under `/var/lib/insaion-agent`, then restarts the service after the agent upgrade.

You can also re-run the installation command generated by the Add Device wizard. This is useful when you want to update only the agent or restore its package repository configuration.

If APT keeps the agent back or reports a Telegraf version conflict, re-run the current installation command to remove package holds created by older installer versions, then run the upgrade again.

### Docker

Pull the current image and recreate the container with the same configuration and persistent state mount:

```bash theme={null}
docker stop insaion-agent
docker rm insaion-agent
docker pull ghcr.io/insaion/agent:latest-jazzy
# Run the updated docker command from the Add Device wizard.
```

Replace `latest-jazzy` with the image tag used by your deployment.

## Troubleshooting

### The service or container is not running

For systemd:

```bash theme={null}
sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent --since "30 minutes ago" --no-pager
```

For Docker:

```bash theme={null}
docker ps -a --filter name=insaion-agent
docker logs insaion-agent --tail 100
```

### The device does not register automatically

Confirm that `ENROLLMENT_KEY` is present in the systemd configuration:

```bash theme={null}
sudo grep '^ENROLLMENT_KEY=' /etc/default/insaion-agent
sudo systemctl restart insaion-agent
```

For Docker, verify that the variable was supplied to the container:

```bash theme={null}
docker inspect insaion-agent | grep ENROLLMENT_KEY
```

If it is missing, recreate the container using the command from the Add Device wizard.

### The pairing page is not reachable

Confirm that the agent is running, then test the local endpoint:

```bash theme={null}
curl http://localhost:9090
```

The pairing page is available only while the device is not registered.

### Custom ROS messages are missing

Set `CUSTOM_ROS_SETUP` to the workspace `setup.bash` path. For Docker, also mount that workspace into the container at the configured path. Restart or recreate the agent after the change.

### DDS settings are not applied

Check the configured middleware variables and verify that 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
```

For Docker, confirm that the same paths are mounted inside the container.

### Docker state is not persisting

Confirm that `/var/lib/insaion-agent` is mounted and writable on the host:

```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 && sudo rm /var/lib/insaion-agent/test
```

If an issue remains unresolved, create a support bundle and include it with the issue report.

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