> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmdr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AirMDR Remote Agent – Installation Guide

> The AirMDR Remote Agent enables secure, controlled connectivity between AirMDR and customer-managed environments. Once installed, the agent runs as a system service and facilitates data collection and task execution as required by enabled AirMDR integrations. 

### Overview

This guide explains how to install, verify, manage, and remove the AirMDR Remote Agent on a Linux system.

### Pre-requisites

Ensure the following requirements are met before installation:

* **Operating System:** Linux
* **Architecture:** amd64
* **Privileges:** Root or sudo access
* **Service Manager:** `systemd`
* **Network Access:** Outbound connectivity to the AirMDR backend (as configured in `config.json`)

  <Note>
    The Remote Agent does not require inbound network access.
  </Note>

### Installation Procedure

<Steps>
  <Step title="Transfer the Installation Package">
    1. Copy the downloaded Remote Agent ZIP package to the target Linux machine.\
       **Example using SCP:**

       ```
       scp remote-agent-linux_amd64.zip user@target-machine:/tmp/
       ```
    2. You may also use:
       * SFTP or secure file transfer tools
       * Direct download on the target machine
    3. Login to target Linux machine.
  </Step>

  <Step title="Extract the Package">
    * Unzip the package and move into the extracted directory:

      ```
      unzip remote-agent-linux_amd64.zip -d remote-agent-client
      cd remote-agent-client
      ```
  </Step>

  <Step title="Verify Package Contents">
    Confirm that the required files are present:

    * **Agent binary:**\
      `airmdr-remote-agent-v*-linux-amd64` (or `airmdr-remote-agent`)
    * **Configuration file:**\
      `config.json`
    * **Installation script:**\
      `scripts/install.sh`

    **Verify using:**

    ```
    ls -la
    ls -la scripts/install.sh
    ```
  </Step>

  <Step title="Run the Installation Script">
    Run the installer with root privileges:

    ```
    sudo bash scripts/install.sh
    ```

    **What the Installer Does**

    The installation script performs the following actions:

    1. Copies the agent binary to:

       ```
       /opt/airmdr-remote-agent/
       ```
    2. Copies `config.json` to:

       ```
       /opt/airmdr-remote-agent/config.json
       ```
    3. Creates a systemd service:

       ```
       airmdr-remote-agent.service
       ```
    4. Enables and starts the service automatically
  </Step>

  <Step title="Verification - Confirm Agent Status">
    Verify that the Remote Agent service is running:

    ```
    sudo systemctl status airmdr-remote-agent
    ```

    Expected status:

    ```
    active (running)
    ```
  </Step>

  <Step title="View Agent Logs (Optional)">
    To monitor agent logs in real time:

    ```
    sudo journalctl -u airmdr-remote-agent -f
    ```

    Press `Ctrl + C` to exit.
  </Step>
</Steps>

## Service Management

Use the following commands to manage the Remote Agent service:

### Start the Agent

```
sudo systemctl start airmdr-remote-agent
```

### Stop the Agent

```
sudo systemctl stop airmdr-remote-agent
```

### Restart the Agent

```
sudo systemctl restart airmdr-remote-agent
```

### Enable Auto-Start on Boot

```
sudo systemctl enable airmdr-remote-agent
```

### Disable Auto-Start on Boot

```
sudo systemctl disable airmdr-remote-agent
```

## Troubleshooting

### Agent Fails to Start

If the service does not start, inspect recent logs:

```
sudo journalctl -u airmdr-remote-agent -n 50 --no-pager
```

#### Common Causes

* ****`Missing config.json:`****\
  Ensure the file exists at `/opt/airmdr-remote-agent/config.json`
* **Invalid configuration values:**\
  Verify required fields such as `server_url`
* **Network connectivity issues:**\
  Confirm the AirMDR backend is reachable
* **Permission issues:**\
  Ensure the binary is executable

## Reinstallation

To reinstall the Remote Agent:

1. Stop and disable the service:

   ```
   sudo systemctl stop airmdr-remote-agent
   sudo systemctl disable airmdr-remote-agent
   ```
2. Remove existing files:

   ```
   sudo rm -rf /opt/airmdr-remote-agent
   sudo rm /etc/systemd/system/airmdr-remote-agent.service
   sudo systemctl daemon-reload
   ```
3. Re-run the installation steps starting from **Run the Installation Script**.

## Uninstallation

To completely remove the AirMDR Remote Agent:

```
# Stop and disable the service
sudo systemctl stop airmdr-remote-agent
sudo systemctl disable airmdr-remote-agent

# Remove the service definition
sudo rm /etc/systemd/system/airmdr-remote-agent.service
sudo systemctl daemon-reload

# Remove the agent installation directory
sudo rm -rf /opt/airmdr-remote-agent
```

## Support

For additional assistance:

* Contact [**AirMDR Support**](mailto:support@airmdr.com) through your designated support channel.