Installing the Agent

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”. 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.qmonitorapp.com/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

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:

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:

(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

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:

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