To install a Wazuh agent, run the package on the endpoint with WAZUH_MANAGER set to your Wazuh server’s IP address or hostname, then start the agent service. On Windows that’s msiexec.exe /i wazuh-agent-<version>.msi /q WAZUH_MANAGER="<MANAGER_IP>" followed by NET START WazuhSvc. On Ubuntu it’s apt-get install wazuh-agent with the same variable, then systemctl start wazuh-agent. This free 3-page PDF walks one Ubuntu 24.04 server from a clean install to a working Wazuh stack, then connects a Windows 11 agent.
How to install Wazuh agent: the three steps that apply on every OS
Every Wazuh agent installation follows the same three steps, whatever the operating system.
- Get the server ready. The Wazuh server must be running, and the endpoint must reach it on TCP 1514 (agent events) and TCP 1515 (agent registration).
- Install the agent package with
WAZUH_MANAGERset. According to Wazuh’s Linux agent guide, leaving the deployment variables out installs the agent without registering it. - Start the service and check it. The agent shows as active in the Wazuh dashboard once it’s connected.
One rule saves hours later. Wazuh’s docs say the manager’s version must be the same as or newer than the agent’s, so don’t install a newer agent than your server.
How to install Wazuh agent on Windows
On Windows, download the MSI, run it from an administrator PowerShell with WAZUH_MANAGER set, then start the WazuhSvc service. The PDF uses this exact route on a Windows 11 endpoint.
msiexec.exe /i wazuh-agent-<version>.msi /q WAZUH_MANAGER="<MANAGER_IP>" WAZUH_AGENT_GROUP="default" WAZUH_AGENT_NAME="windows_agent"
NET START WazuhSvcThe PDF saves the MSI to the temp folder as wazuh-agent.msi, so adjust the path to wherever yours lives. Replace <version> with the current agent version. Wazuh’s Windows agent guide showed 4.14.9-1 when this page was written (2026-10-15).
| Variable | What it does |
|---|---|
WAZUH_MANAGER | Server IP address or hostname the agent connects to |
WAZUH_AGENT_NAME | Name shown in the dashboard. Defaults to the computer name |
WAZUH_AGENT_GROUP | An existing agent group to join, for example default |
/q | Runs the installer silently with no wizard |
Wazuh’s deployment variables page lists the rest, including WAZUH_PROTOCOL (TCP by default) and WAZUH_REGISTRATION_PASSWORD for servers that require one.
Two details are worth knowing. You need administrator rights, and the agent installs to C:\Program Files (x86)\ossec-agent. The PDF starts the service with NET START Wazuh, while Wazuh’s current docs use the service name, NET START WazuhSvc. Use the docs form. In PowerShell, Start-Service wazuhsvc does the same job.
Install Wazuh agent on Windows with the installer wizard
If you’d rather click than type, run the MSI without /q and accept the defaults. After the install, open the agent’s configuration window and enter the manager’s IP address, then start the service from the same window.
Wazuh agent download for Windows
Download the MSI from Wazuh’s package server: https://packages.wazuh.com/4.x/windows/wazuh-agent-<version>.msi. Use the exact file name from Wazuh’s docs, and download only from packages.wazuh.com or the Wazuh dashboard’s deployment screen. This free guide is the companion PDF, not the installer.
How to install Wazuh agent on Ubuntu
On Ubuntu, add Wazuh’s APT repository, install wazuh-agent with WAZUH_MANAGER set, then enable and start the service. The PDF installs the Wazuh server on Ubuntu rather than the agent, so this section follows Wazuh’s Linux agent guide instead. Run these as root (sudo -i), the way the docs do:
apt-get install gnupg apt-transport-https curl
curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg
echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
apt-get update
WAZUH_MANAGER="<MANAGER_IP>" apt-get install wazuh-agent
systemctl daemon-reload
systemctl enable wazuh-agent
systemctl start wazuh-agentThe same steps work on Debian and, with the matching package manager commands from the docs, on other Linux distributions. Check the result with systemctl status wazuh-agent. If the service won’t start on your system, Wazuh’s docs say you may need /var/ossec/bin/wazuh-control start.
Before you leave, stop accidental upgrades. Wazuh recommends disabling the repository after the install, because an agent that updates past its manager breaks the version rule above:
sed -i "s/^deb /#deb/" /etc/apt/sources.list.d/wazuh.list
apt-get updateFor Ubuntu command basics, keep our Linux Commands Cheat Sheet open.
Install the Wazuh server first: all-in-one on Ubuntu
To install the Wazuh server, update Ubuntu, install curl, then run Wazuh’s installation assistant. The PDF’s first three steps do exactly that on Ubuntu 24.04 (the guide’s server is a VMware virtual machine):
sudo apt update && sudo apt upgrade -y
sudo apt install curl -y
curl -sO https://packages.wazuh.com/4.14/wazuh-install.sh && sudo bash ./wazuh-install.sh -a -i -oThe assistant installs the Wazuh server, indexer and dashboard on one machine. Here’s what each flag does, checked against the installer’s own help text (4.14):
| Flag | What it does | Use it when |
|---|---|---|
-a | All-in-one: installs the server, indexer and dashboard | Always, for a single-machine install |
-i | Ignores the minimum hardware check (4 GB RAM, 2 CPU cores) | Only in a small lab that falls short |
-o | Overwrites earlier components and erases existing configuration and data | Only on a machine you’re happy to wipe |
The PDF describes -i as an install option, but the installer’s help says it skips the hardware check. On a fresh machine that meets Wazuh’s recommended hardware (4 vCPU and 8 GiB of RAM for up to 25 agents), Wazuh’s quickstart uses plain -a. Don’t add -o unless you mean to start over.
When it finishes, the assistant prints the dashboard address, the admin username and a generated password. Browse to https://<SERVER_IP>. Your browser will warn about the certificate. Wazuh says that’s expected, because the default certificate isn’t issued by a trusted authority. Store the password in a password manager and never paste it into a document. To print it again later, run sudo tar -O -xvf wazuh-install-files.tar wazuh-install-files/wazuh-passwords.txt in the folder where you ran the installer.
For the full options, see Wazuh’s installation assistant guide.
Want to repeat this install until it’s routine? The workbook’s Wazuh installation practice labs cover single-node installs, multi-node clusters and troubleshooting installs, so you can break and rebuild a server safely.
Which ports does Wazuh use?
Wazuh agents talk to the server on TCP 1514 for events and TCP 1515 for registration. The dashboard uses 443, the indexer API uses 9200 and the server API uses 55000. According to Wazuh’s architecture documentation, these are the defaults:
| Component | Port | Protocol | Purpose |
|---|---|---|---|
| Wazuh server | 1514 | TCP | Agent connection (events) |
| Wazuh server | 1515 | TCP | Agent registration |
| Wazuh server | 1516 | TCP | Cluster daemon |
| Wazuh server | 55000 | TCP | Server API |
| Wazuh indexer | 9200 | TCP | Indexer API |
| Wazuh dashboard | 443 | TCP | Web interface |
Wazuh also lists optional syslog ports and indexer cluster ports. Open 1514 and 1515 from every agent to the server first. If the agent installs but never connects, a blocked port is a common cause. Our Common Ports Cheat Sheet covers the other ports you’ll meet on the same network.
How to check that the Wazuh agent is connected
A connected agent shows as active in the Wazuh dashboard, and its service reports as running on the endpoint. The PDF checks the server and the agent in four short steps.
On the server, confirm the three services are running:
sudo systemctl status wazuh-manager wazuh-indexer wazuh-dashboard
curl -u admin:<password> -k https://localhost:9200The second command asks the indexer for its status. A healthy answer is a short JSON block with the node name, the cluster name and a version number. The PDF’s output shows wazuh-indexer, wazuh-cluster and version 7.10.2, so expect a similar shape, not that exact number.
On the endpoint, confirm the agent service:
Get-Service wazuhsvcOn Ubuntu, systemctl status wazuh-agent does the same job.
In the dashboard, open Agents management, then Summary, and look for your agent with an active status. Menu names move between releases, so check yours.
Common Wazuh agent installation problems
Most failed installs come down to four things, and each one has a quick check.
- The agent installed but isn’t registered. You left out
WAZUH_MANAGER. Reinstall with the variable set. - Port 1514 or 1515 is blocked. Test from the endpoint to the server and open the port on the server’s firewall.
- The agent is newer than the manager. Wazuh’s docs require the manager to be the same version or newer. Upgrade the server first.
- The service won’t start. On Ubuntu, try
/var/ossec/bin/wazuh-control start. On Windows, run the installer and the service commands as an administrator.
If a step fails and you want to read the details, add /l*v installer.log to the msiexec command on Windows. Wazuh’s deployment variables page lists it as the verbose install log option.
The Wazuh agent deployment chapter of the workbook walks through deploying agents on Linux, Windows and macOS, which is the fastest way to meet these failures in a safe lab first.
Go deeper
Getting one agent to show Active is step one. Catching an attack with it is the job.
The Wazuh SIEM Workbook: deploy agents, write your own detection rules and run real attack scenarios, with EVE-NG lab files included.
Get the Wazuh SIEM Workbook →Where does this free Wazuh PDF stop?
This PDF shows one server and one Windows agent on a lab network. It doesn’t cover multi-node clusters, agent groups at scale, custom rules or what to do when the alerts start. The Wazuh SIEM Workbook picks up from there. Its chapters cover Wazuh installation and deployment (single-node install, step-by-step component installation, multi-node clusters, Docker and troubleshooting installs) and agent management, including deploying agents on Linux, Windows and macOS. Later chapters move on to decoders, rules, file integrity monitoring, active response and cloud monitoring. There’s a free 25-page sample before you decide.
Prefer containers to virtual machines? Our guide to a Wazuh SIEM home lab with Docker runs the same stack that way.
Once your lab runs, the Network Troubleshooting Commands PDF helps when an agent can’t reach the server.
