---
title: Installing the Agent
description: Installation steps for the QMonitor Agent

url: https://help.qmonitor.app/docs/tasks/agents/installation/index.md
lastmod: 2026-09-16T22:53:51+02:00
---


To start the QMonitor agent installation, download the setup kit for your
operating system (Windows or Linux), copy it to the target machine, and run it.
Running the agent in a container does not require installation steps and is
described in "[Running the QMonitor agent in a container](#running-the-qmonitor-agent-in-a-container)". 
The installation copies files to the chosen installation directory and requires
no user input except for that directory. Additional configuration is required to 
authenticate the agent to your organization and to run it as a background service.

### Setting up the agent on Windows

On Windows we provide two tools to configure the agent. ConfigWizard is a GUI
for users who prefer a visual flow. ConfigWizardCmd is a CLI tool offering the
same functionality in a scriptable, repeatable form.

#### Using ConfigWizard

Open the Start menu, type QMonitor, and launch the QMonitor ConfigWizard.
ConfigWizard displays the organizations configured on the machine in a
dropdown at the top of the window.

To add an organization, click the "+" button and enter the organization name
and the organization key you obtained when creating the org.

If you lost the organization key, regenerate it from the Settings page:
https://portal.qmonitor.app/settings. Warning: regenerating the org key
invalidates the old key and causes all existing agents to stop working until
they are reconfigured with the new key.

Note: the machine-safe organization name may differ from the display name.
You can copy the machine-safe name from the Settings page if needed.

After the server validates the org name and key, agent names appear in the
agents dropdown and you can configure agent services on this machine. The UI
shows whether an agent is installed and the service account in use.

To install an agent, click the service account link, enter service credentials,
and press "Install". This creates a Windows service configured to start
automatically. By default the service runs as NT AUTHORITY\Network Service.

#### Using ConfigWizardCmd

See the full ConfigWizardCmd documentation in `installation_cmd.md`.

ConfigWizardCmd provides the same capabilities as the GUI in a CLI form that
is suitable for automation. See the ConfigWizardCmd reference for parameter
details and examples.

For instance, you can use a similar syntax to install an agent service:

``` cmd
ConfigWizardCmd.exe install --org your_organization_name --key your_organization_key --agent your_agent_name
```

#### Additional considerations

The service account is important because it is used to authenticate the agent
to SQL Server instances when using Integrated Security (Windows auth). Using
Integrated Security is recommended as it avoids storing passwords.

If the service runs as NT AUTHORITY\Network Service it authenticates on the
network using the computer account (DOMAIN\ComputerName$). If the SQL Server
instance is local to the agent host, authentication uses the Network Service
account on that machine.

Windows may show a localized name for the Network Service account (for
example, "NT AUTHORITY\Servizio di Rete"). To get the localized account name,
run this PowerShell command:

```powershell
(New-Object System.Security.Principal.SecurityIdentifier "S-1-5-20").Translate([System.Security.Principal.NTAccount])
```

Example output from an Italian system:

```
Value
-----
NT AUTHORITY\SERVIZIO DI RETE
```

{{< alert color="warning" title="Warning">}}
If you change the service account later, do not just update it in Services.
Use ConfigWizard or ConfigWizardCmd. These tools update service credentials
and ensure required file system permissions and other settings are applied.
{{< /alert >}}

When ConfigWizard or ConfigWizardCmd complete setup, the agent starts and
begins collecting data for associated SQL Server instances. The agent also
contacts QMonitor servers to report its state. On the Instances page click the
green/red icon next to an agent to view its state, service account, and agent
version.

### Setting up the agent on Linux

ConfigWizard is not available on Linux; configure the agent using
ConfigWizardCmd. See the CLI documentation for required parameters and examples.

On Linux, the agent cannot impersonate Windows users, so Integrated Security
is not available. Entra (Managed Identity) authentication may be available if
the Linux VM or container supports a managed identity.

### Running the QMonitor agent in a container

The QMonitor agent runs easily in a container. Configure the container with a
few environment variables that provide secrets and configuration options.

An example command line for docker looks like this:

``` cmd
docker run -d -e OrganizationName=your_organization_name -e OrganizationKey=your_organization_key -e AgentName=your_agent_name qmonitor/agent:latest
```

It is strongly recommended to configure an auto-updater so your agent can receive hotfixes and new features as soon as
they are published.

Sample compose.yaml with `getwud/wud` autoupdater:
```yaml
services:

  qmonitor-agent:
    image: qmonitor/agent:latest
    hostname: "${HOSTNAME}"
    environment:
      OrganizationName: "your-organization-name"
      AgentName: "your-agent-name"
      OrganizationKey: "your-organization-key"
    restart: unless-stopped
    labels:
      - "wud.watch=true"

  autoupdater:
    image: getwud/wud
    environment:
      WUD_WATCHER_LOCAL_WATCHBYDEFAULT: "false"
      WUD_TRIGGER_DOCKER_QMONITOR_AUTO: "true"
    ports:
      - "3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped
```