Enrol endpoints

One token and one command per machine. Every token can do both; the command decides what the machine gets:

Command	Installs
Without `--patching`	The monitoring agent (the Wazuh agent, from Wazuh's signed packages, version `AGENT_VERSION`, 4.14.0-1 by default)
With `--patching` (`-Patching` on Windows)	The same, plus the Theseus agent for patching (one static binary, outbound HTTPS only)

Patching needs the patch module on the server. Without it, --patching is refused with patch management is not enabled on this Theseus installation.

Supported endpoints

Platform	Wazuh agent	Patching (Theseus agent)
Debian, Ubuntu (amd64, arm64)	yes	yes, apt
RHEL, Rocky, Alma, Amazon Linux, Oracle Linux, Fedora, CentOS (amd64, arm64)	yes	yes, dnf / yum
Windows (x64)	yes, MSI with its Authenticode signature checked	yes, Windows Update KBs and winget pilot
macOS (Apple silicon, Intel)	yes, pkg with its Developer ID signature checked	yes, Homebrew pilot

Endpoints can be ARM; only the Theseus server must be x86-64.

1. Create the install commands

In the console, open Get started → Add your first agent, or Agents → Add agents.

Field	Meaning
Label	What these machines are, for example "linux web servers". Shown in the token list.
Machines	How many machines the token may enrol, 1 to 500
Valid for	How long the token works, 1 to 30 days
Agent groups	Optional Wazuh agent groups, comma-separated (up to 10)

Both forms propose 25 machines for 7 days, the same defaults as ./theseus enroll token. (In 0.1.0 the Agents drawer proposed 10 machines for 1 day and had no groups field.)

You get one command each for Linux, Windows and macOS, and the command line for the Windows MSI (tab Windows (MSI, for Intune/ConfigMgr/GPO), with a Download the MSI link; see Windows mass rollout). Copy them now: the token is shown once. Turn on Also enable patching to add --patching (-Patching on Windows) to the command shown; it is the same token either way, so you can copy both forms, or add the flag by hand later.

From the server, the same (--patching here only adds the flag to the printed commands):

bash

cd /opt/theseus && sudo ./theseus enroll token --patching --label "linux web" --groups linux,web --max 50 --days 3

Earlier tokens

Tokens created earlier with Include patching off work with --patching too: the token no longer decides patching.

2. Run the command on the machine

The commands below show the form. Use the ones the console gives you: they carry your address, your token, and, with the internal CA, the pin of your certificate.

Linux

As root (or with sudo):

bash

curl -fsSL --proto '=https' --insecure --pinnedpubkey 'sha256//<pin>' \
  -o /tmp/theseus-install.sh 'https://soc.example.com/enroll/install.sh' \
  && sudo bash /tmp/theseus-install.sh --token 'THS-...' --patching

With a public certificate there is no --insecure --pinnedpubkey part. --pinnedpubkey makes the download succeed only from your server, even though its certificate is not from a public CA.

macOS

The same form, with install-macos.sh:

bash

curl -fsSL --proto '=https' -o /tmp/theseus-install.sh 'https://soc.example.com/enroll/install-macos.sh' \
  && sudo bash /tmp/theseus-install.sh --token 'THS-...'

With patching on a Mac that uses FileVault: after a restart, the Mac reconnects only once a user logs in.

Windows

In PowerShell as Administrator:

powershell

powershell -NoProfile -ExecutionPolicy Bypass -Command "[Net.ServicePointManager]::SecurityProtocol='Tls12'; & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://soc.example.com/enroll/install.ps1'))) -Token 'THS-...' -Patching"

With the internal CA, the console's command also sets a certificate check that accepts only your server's certificate thumbprint.

The Windows installer ends with an exit code that says what failed (for example 20 for a refused token, 21 for the licence limit): see exit codes. To roll out to many Windows machines with Intune, Configuration Manager or Group Policy, use the Windows MSI.

3. Check it

The installer ends with a summary. On Linux, with --patching:

text

Theseus agent - enrolling 'web-01' with patching
  - security monitoring component 4.14.0
  - Theseus agent (patch management)
  - enrolment
  - agent 001 -> soc.example.com:1514

===============================================================
  Theseus agent installed and enrolled.
  Agent       : web-01 (id 001) -> soc.example.com:1514, active
  Patching    : on - Theseus agent active, checks in at https://soc.example.com/agent
===============================================================

Without --patching the last line reads Patching : off (re-run this command with --patching to enable patching) (-Patching on Windows). Run bash /tmp/theseus-install.sh --help for the options.

The machine appears in Get started → Enrolled machines within a minute, and on the Agents page as Connected once the agent reports.

Installer options

Linux / macOS	Windows	Meaning
`--token THS-...`	`-Token`	The enrolment token. Required
`--patching`	`-Patching`	Also enable patching: install the Theseus agent. Any token allows it; the `patch` module must be on
`--name <name>`	`-Name`	Agent name. Default: the short host name, plus 4 characters of the machine's id when another machine has that name already. 1 to 63 characters: letters, digits, `.`, `_`, `-`. Rename agents later in the console
`--new-identity`	`-NewIdentity`	Register as a new agent even though this machine already has an agent key (the old key is kept as `client.keys.before-theseus`)
`--uninstall`	`-Uninstall`	Remove the monitoring agent and the Theseus agent
`--help`		Print the options (Linux, macOS)

What the installer does

Installs the Wazuh agent package, checking the package signature (repository key on Linux, Authenticode on Windows, Developer ID on macOS). On Debian and Ubuntu the package is held, so routine upgrades do not change its version. An existing Wazuh agent of another version is kept.
With patching: installs the Theseus agent and creates its Ed25519 key on the machine; only the public half leaves it.
Makes one enrolment call to your server. The server checks the token, registers the agent with the manager and returns its key; with patching it records the machine's public key.
Points the Wazuh agent at AGENT_HOST:AGENT_PORT (TCP 1514) and starts it.
With patching: starts the Theseus agent (systemd on Linux, a LaunchDaemon on macOS, a SYSTEM scheduled task on Windows).

Patching later

To turn patching on for a machine that is already enrolled, run the install command on it again with --patching (-Patching on Windows); any valid token works. A machine that proves it holds its existing agent key is not counted again and uses no token place.

Tokens

Format THS- followed by 32 characters. Only a hash is stored; the token cannot be shown again.
Statuses in Get started → Install commands issued: active, used up, expired, revoked.
Revoke a token there. Machines already enrolled with it stay enrolled.
A token cannot place machines in the theseus-disabled group.

Rate limits

Enrolment is limited to protect the server:

20 requests per 10 minutes from one address;
after 5 failures in 10 minutes, that address is blocked for an hour;
300 successful enrolments per hour in total.

A refusal because of the licence limit does not count as a failure. When you roll out to many machines behind one NAT address, stagger the rollout.

Enrol endpoints ​

Supported endpoints ​

1. Create the install commands ​

2. Run the command on the machine ​

Linux ​

macOS ​

Windows ​

3. Check it ​

Installer options ​

What the installer does ​

Patching later ​

Tokens ​

Rate limits ​

Next ​

Enrol endpoints

Supported endpoints

1. Create the install commands

2. Run the command on the machine

Linux

macOS

Windows

3. Check it

Installer options

What the installer does

Patching later

Tokens

Rate limits

Next