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, from its vendor's signed packages (version AGENT_VERSION, 4.14.0-1 by default)
With --patching (-Patching on Windows)	The same, plus the Schildmark 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 Schildmark installation.

Supported endpoints

Platform	Monitoring agent	Patching (Schildmark 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 Schildmark 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 monitoring 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):

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):

curl -fsSL --proto '=https' --insecure --pinnedpubkey 'sha256//<pin>' \
  -o /tmp/schildmark-install.sh 'https://soc.example.com/enroll/install.sh' \
  && sudo bash /tmp/schildmark-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:

curl -fsSL --proto '=https' -o /tmp/schildmark-install.sh 'https://soc.example.com/enroll/install-macos.sh' \
  && sudo bash /tmp/schildmark-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 -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.

On Windows desktops the command also installs the tray app, the Schildmark icon in the notification area; on Windows Server it does not unless you add -Tray.

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.

Windows, by hand: the setup wizard

To install one Windows machine without a command line, download the setup wizard from your server and run it:

https://<your domain>/enroll/files/schildmark-setup-windows-amd64.exe

It asks for administrator rights, then takes you through five pages: Welcome, Connect (the console address and the enrolment token), Options (patching, the tray app, the machine name), Installing (each step of the installer as it runs) and Done (the summary, and Open console). It downloads install.ps1 from your server with the same certificate check as the Windows command and runs it; the result is the same as the command's.

• Console address: filled in when the wizard was downloaded from your server (Windows records where a download came from). Otherwise type the address you open the console with.
• Enrolment token: paste it from Add agents. It is passed to the installer without appearing on a command line, and nothing stores it.
• Certificate thumbprint (under Advanced): only with the internal CA. Copy the value after GetCertHashString() -eq from the console's Windows command.
• To fill the pages in for someone else, put a schildmark-setup.json next to the wizard: {"server": "https://soc.example.com", "token": "THS-...", "pin": "", "patching": true}. Treat the file like the token: delete it once the machine is enrolled.

The wizard needs the Microsoft Edge WebView2 Runtime, which Windows 11 and current Windows 10 include. Without it, the wizard says so; use the Windows command instead. It sends nothing anywhere except to the console address you enter. Its SHA-256 is in SHA256SUMS next to it. While the wizard is not signed with a code-signing certificate, Windows SmartScreen may warn "Windows protected your PC" when you open the download: check its SHA-256 against SHA256SUMS (Get-FileHash .\schildmark-setup-windows-amd64.exe), then choose More info → Run anyway.

3. Check it

The installer shows numbered steps, each ending with done, skipped or failed, and then a summary. On Linux, with --patching:

Schildmark Agent installer 0.2.17
Linux, enrolling this machine with soc.example.com

  1/5  Checking this machine ... done
        Machine name web-01, with patching
  2/5  Installing the monitoring component 4.14.0 ... done
  3/5  Installing the Schildmark Agent ... done
  4/5  Enrolling with the console ... done
        agent 001, reports to soc.example.com:1514
  5/5  Starting the services ... done

Schildmark Agent is installed and enrolled.

  Machine       web-01 (agent 001)
  Console       https://soc.example.com
  Monitoring    on, active
  Patching      on, the Schildmark Agent is active
  Check status  sudo theseus-agent status
  Log           /var/log/schildmark-install.log
  Uninstall     the console's Agents page (Remove), or: sudo bash /tmp/schildmark-install.sh --uninstall

Without --patching, step 3 is skipped and the summary says Patching off, run this command again with --patching to turn it on (-Patching on Windows). Windows has a sixth step, the tray app. macOS logs to /Library/Logs/Schildmark/install.log, Windows to C:\ProgramData\Schildmark\install.log.

In a terminal the status words are in colour; set NO_COLOR=1 to turn colour off. When the output goes to a file or another program (the MSI, the setup wizard, a rollout tool), it has no colour and each step has a line when it starts and one when it ends.

When something fails, the installer says what went wrong, how to fix it, and its exit code:

  4/5  Enrolling with the console ... failed

ERROR: the console refused the enrolment (HTTP 403): enrolment token invalid, expired, revoked or used up
How to fix: create a new token in the console (Onboarding -> Add agents) and run the new command
Exit code: 1

On Linux and macOS every failure exits with 1; on Windows the exit code says which failure it was (see exit codes). Run bash /tmp/schildmark-install.sh --help for the options.

With patching, sudo theseus-agent status on the machine (on macOS sudo /usr/local/libexec/theseus-agent status) shows whether the Schildmark Agent reaches the console and when it last checked in. Its exit code is 0 when connected, 3 when not connected and 4 when it needs attention.

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 Schildmark 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)
	-Tray	Install the tray app. Default: on for Windows desktops, off for Windows Server. -Tray:$false leaves it out and removes one installed before
--uninstall	-Uninstall	Remove the monitoring agent and the Schildmark Agent (on Windows also the tray app)
--help		Print the options (Linux, macOS)

What the installer does

1. Installs the monitoring 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 monitoring agent of another version is kept.
2. With patching: installs the Schildmark Agent and creates its Ed25519 key on the machine; only the public half leaves it.
3. 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.
4. Points the monitoring agent at AGENT_HOST:AGENT_PORT (TCP 1514) and starts it.
5. With patching: starts the Schildmark Agent (systemd on Linux, a LaunchDaemon on macOS, a SYSTEM scheduled task on Windows).
6. On Windows desktops (or with -Tray): installs the tray app and starts it for every user who signs in.

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.

Next

• Windows mass rollout
• Disable, enable, remove
• Licence and agent limits
• Agents and enrolment troubleshooting