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

# Setup guideline VMS agent collector

> Deploy agents by script and configure probe monitoring

<div style={{ width: '100%', height: 4, marginBottom: 24, borderRadius: 2, background: 'rgba(0,0,0,0.08)' }}>
  <div style={{ width: '75%', height: '100%', borderRadius: 2, background: 'linear-gradient(90deg, var(--accent-primary) 0%, var(--accent-light) 50%, var(--accent-dark) 100%)' }} />
</div>

The VMS agent collector runs on the customer host to collect metrics, checks, and logs, then pushes them to VMS Master over HTTPS.

## Agent Deployment Overview

<img src="https://mintcdn.com/vero-35a9bc05/YT70Sr2qWE1qMbL1/images/vms_agent_deployment.png?fit=max&auto=format&n=YT70Sr2qWE1qMbL1&q=85&s=82ca8c14ee2117bca418e5b907fc3ef7" alt="VMS Agent Deployment" width="1024" height="1024" data-path="images/vms_agent_deployment.png" />

***

## Prerequisites (Agent)

| Prerequisite | Description                     |
| ------------ | ------------------------------- |
| OS           | **Linux** or **Windows**        |
| Connection   | Outbound HTTPS to `INGRESS_URL` |

***

## Deployment Flow on Linux

<Steps>
  <Step title="1. Run the install script">
    * **Step**: On the target host, run the script (no sudo required):
      ```bash theme={null}
      curl -fsSL "<agent.sh link>" | sh
      ```
    * **Check**: The script prints `Step 1/6 ... 6/6` progress.
    * **Result**: `SUCCESS (verified): vms-monitor-agent <version> installed`.

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/01-install.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=7ab245956f81f3a4257719964905e8e5" alt="Output of the agent install script on Linux" width="4749" height="3007" data-path="images/agent-install/01-install.png" />
  </Step>

  <Step title="2. Check the service">
    * **Step**: Query the service status:
      ```bash theme={null}
      systemctl --user status vms-monitor-agent --no-pager
      ```
    * **Check**: Status shows `active (running)`.
    * **Result**: Binary at `~/.local/bin/vms-monitor-agent`, config at `~/.config/vms-monitor-agent/agent.env`.

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/02-service-status.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=ce4a618ac51e29c863c654ca60aff863" alt="vms-monitor-agent service active and running" width="4016" height="1256" data-path="images/agent-install/02-service-status.png" />
  </Step>

  <Step title="3. Verify connection logs">
    * **Step**: Tail live logs:
      ```bash theme={null}
      journalctl --user -u vms-monitor-agent -f
      ```
    * **Check**: Look for the `agent started` line with `agentKey`, `probes`, and `configVersion`.
    * **Result**: A JSON log line appears, e.g.:

      ```json theme={null}
      {"level":"INFO","msg":"agent started","agentKey":"web-01/appuser","configVersion":12,"probes":8}
      ```

          <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/03-logs.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=8d72095624b490ed9ed69037efdb3ffd" alt="JSON &#x22;agent started&#x22; log on Linux" width="5116" height="823" data-path="images/agent-install/03-logs.png" />
  </Step>
</Steps>

Once installed, the agent appears in **Agent Config (FLEET)** on the Dashboard (`https://<VMS_MASTER_IP>/dashboards/agent-config`):

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/09-agent-online.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=9075bdca2e4a362b721763400194cc4a" alt="Agent online in the FLEET panel on the Dashboard" width="1397" height="896" data-path="images/agent-install/09-agent-online.png" />

***

## Deployment Flow on Windows

<Steps>
  <Step title="1. Run the install script">
    * **Step**: Open PowerShell (no Administrator required):
      ```powershell theme={null}
      irm "<agent.ps1 link>" | iex
      ```
    * **Check**: The script prints `Step 1/6 ... 6/6` progress.
    * **Result**: `SUCCESS (verified): vms-monitor-agent <version> installed`.
  </Step>

  <Step title="2. Check the agent status">
    * **Step**: Inspect the auto-start task and the agent process:
      ```powershell theme={null}
      Get-ScheduledTask -TaskName vms-monitor-agent
      Get-Process vms-monitor-agent
      ```
    * **Check**: The task exists and an agent process is running.
    * **Result**: Binary at `%LOCALAPPDATA%\vms-monitor-agent\vms-monitor-agent.exe`.
  </Step>

  <Step title="3. Check logs / version">
    * **Step**: Print the version:
      ```powershell theme={null}
      & "$env:LOCALAPPDATA\vms-monitor-agent\vms-monitor-agent.exe" version
      ```
    * **Check**: Prints version, commit, and build date.
    * **Result**: Agent is online on the Dashboard.
  </Step>
</Steps>

***

## Managing the agent from the command line

After install, open a **new terminal/PowerShell** and use the `vms-monitor-agent` command (no `sudo`/Administrator needed).

| Command                       | What it does                                                            |
| ----------------------------- | ----------------------------------------------------------------------- |
| `vms-monitor-agent status`    | Show installed / running / auto-start / version                         |
| `vms-monitor-agent start`     | Start and enable auto-start at login/boot                               |
| `vms-monitor-agent stop`      | Stop **permanently** and disable auto-start — it will **not** come back |
| `vms-monitor-agent restart`   | Restart, leaving auto-start unchanged                                   |
| `vms-monitor-agent uninstall` | Self-remove the agent (add `--purge` to also wipe state)                |
| `vms-monitor-agent version`   | Print version, commit, build date                                       |
| `vms-monitor-agent help`      | Print the full usage guide                                              |

`status` shows whether the agent is installed / running / auto-start / version:

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/04-agent-status.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=2c022e5d79cb9996c35ff86a3d08038d" alt="Output of vms-monitor-agent status" width="2649" height="966" data-path="images/agent-install/04-agent-status.png" />

`stop` (permanent) then `start` again — notice `running` and `auto-start` change accordingly:

<img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/05-lifecycle.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=cc342ea7d18c67a8282018207af47d08" alt="Agent stop and start lifecycle" width="3782" height="1620" data-path="images/agent-install/05-lifecycle.png" />

<Info>
  **`stop` is permanent**: it stops the process and disables auto-start. The agent **does not come back after a reboot**. Use `start` to resume or `uninstall` to remove.

  If `command not found`, open a new shell or use the full path (`~/.local/bin/vms-monitor-agent` on Linux, `%LOCALAPPDATA%\vms-monitor-agent\vms-monitor-agent.exe` on Windows).
</Info>

***

## Updating the agent

Re-run the install command:

* **Linux**:

  ```bash theme={null}
  curl -fsSL "<agent.sh link>" | sh
  ```

  The script compares versions and asks before replacing the binary.

  If already up to date, the script reports `already current`:

  <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/07-update.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=042b2baebd5fa52dd6fcdc3905415885" alt="Re-running the install command when already on the latest version" width="3782" height="2132" data-path="images/agent-install/07-update.png" />

* **Windows**:
  ```powershell theme={null}
  irm "<agent.ps1 link>" | iex
  ```

***

## Uninstalling the agent

Run `uninstall` from the binary, or re-fetch the script with `uninstall`:

* **Linux**:

  ```bash theme={null}
  # Remove on the host with the binary; add --purge to also wipe state:
  vms-monitor-agent uninstall
  # Or, on a host without this command, re-fetch the script:
  curl -fsSL "<agent.sh link>" | sh -s -- uninstall
  ```

  <img src="https://mintcdn.com/vero-35a9bc05/3Jj1PaRU569Y86dW/images/agent-install/06-uninstall.png?fit=max&auto=format&n=3Jj1PaRU569Y86dW&q=85&s=e7f4bfd0663d478ab64327cc4a11695d" alt="Uninstalling via the vms-monitor-agent uninstall command" width="3482" height="1113" data-path="images/agent-install/06-uninstall.png" />

* **Windows**:
  ```powershell theme={null}
  # Remove on the host with the binary; add --purge to also delete the install dir:
  vms-monitor-agent uninstall
  # Or re-fetch the script:
  & ([scriptblock]::Create((irm "<agent.ps1 link>"))) uninstall
  ```

***

## Troubleshooting

| Symptoms                         | Likely Cause                   | Resolution                                          |
| -------------------------------- | ------------------------------ | --------------------------------------------------- |
| Agent fails to start immediately | Missing ingress URL or API key | Check agent logs for the error detail               |
| `401` Authentication blocked     | Invalid or rotated API key     | Get a new key from VMS Master and re-run the script |