12
Agent-Deployment
Alphaeus Mote edited this page 2026-10-31 21:05:36 -04:00
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Agent Deployment

Add device (the fast path)

Open Devices → + Add device.

Pick Windows, Linux or macOS. Choose a single-use token, a multi-use one (any count up to 9999), or unlimited — all with a 24-hour expiry. Then Generate command issues the token and builds the one-liner:

# Windows (elevated PowerShell)
iwr 'https://control.example.com/api/enrollment/install?token=…' -UseBasicParsing | iex
# Linux / macOS
curl -fsSL 'https://control.example.com/api/enrollment/install?token=…&type=linux' | sudo bash

What the script does:

  • Detects the architecture (x64 / arm64)
  • Downloads the matching agent package from the same origin
  • Installs the service — Windows service, systemd unit, or launchd daemon
  • Configures enrollment and starts the agent

Changing the token options re-issues the token live and revokes the superseded one.

There is no trust checkbox — the command is a plain one-liner. Trust is decided by the server, not the operator.

When the server runs self-signed TLS, the agent installs its managed CA (from /api/enrollment/ca) into the OS trust store and keeps it current across renewals, so ordinary system validation trusts the server. It is not pinned or forced: add a reverse proxy with a real certificate later and that validates normally — the self-signed CA just goes unused. When the server is not self-signed, /api/enrollment/ca returns 404 and the agent installs nothing. insecure (accept any) remains via configure --skip-tls-verify for edge cases.

Agent MSI (GPO / SCCM style)

msiexec /i Agent.msi /qn SERVERURL=https://control.example.com BOOTSTRAPTOKEN=<token>
Property Registry value
SERVERURL ServerURL
BOOTSTRAPTOKEN BootstrapToken (erased after enrollment)
LOGLEVEL LogLevel
ALLOWREMOTESHELL AllowRemoteShell
ALLOWSCRIPTEXECUTION AllowScriptExecution
PROXYURL ProxyUrl (explicit outbound proxy; system proxy otherwise)

Certificate trust is not an MSI property. A self-signed server's CA is fetched and trusted automatically at enrollment. The accept-any escape hatch (TlsSkipVerify, for a private/edge cert the agent cannot validate) is set via configure --skip-tls-verify, the registry, or Group Policy — not the MSI.

The wizard's Connection page edits the server URL and token.

Blank properties never overwrite configured values. Upgrades preserve everything.

Registry, GPO, and the unix config file

Normal config:  HKLM\SOFTWARE\ExecuteR
Runtime state:  HKLM\SOFTWARE\ExecuteR\Runtime
GPO policy:     HKLM\SOFTWARE\Policies\ExecuteR      (wins over everything)

Precedence is simple: GroupPolicy > registry > dev-only environment > defaults.

ADMX/ADML templates ship in src/Installer/Policies. They cover ServerURL, LogLevel, the intervals, AllowRemoteShell, AllowScriptExecution, TlsSkipVerify and ProxyUrl.

Outbound proxy: the agent honors the system or environment proxy (HTTP_PROXY / HTTPS_PROXY / NO_PROXY, or the Windows system proxy) and authenticates to it with the machine account's default credentials — corporate NTLM/Negotiate proxies work unattended. ProxyUrl forces an explicit proxy instead (configure --proxy http://proxy:8080).

On Linux and macOS the same keys live in /etc/executer/agent.json, and credentials sit under /var/lib/executer (mode 600). The CLI writes them for you:

executer-agent configure --url https://… --token … [--skip-tls-verify]

Windows PE

The agent runs in Windows PE, so a device can be reached before it is imaged, and it stays the same device afterwards. Its ID comes from the firmware (SMBIOS UUID, BIOS and board serials, make and model), never from the OS. The installed OS therefore enrolls into the same device row.

  • In WinPE the device shows a WinPE chip, the OS reads Windows PE, and the name is WinPE's random MINWINPC-….
  • When the installed OS enrolls, the name and OS update, and Device History records each step.

A device enrolled from WinPE

Device History after imaging

Boot image components (Dism /Add-Package):

Component Why
WinPE-WMI Required. Identity and inventory come from WMI.
WinPE-PowerShell The PowerShell one-liner and the powershell.exe engine.

Also raise the scratch space, because the agent doesn't fit in the default 32 MB: Dism /Image:<mount> /Set-ScratchSpace:512.

Install. Paste the usual Windows one-liner from Add device at the WinPE prompt. The script detects WinPE, takes the portable ZIP (Windows Installer doesn't run there), and registers and starts the Windows service with ExecuteR-Agent.exe initialize. That calls the Service Control Manager directly, not sc.exe. Everything lives on X: and is gone at reboot.

Without PowerShell, run the agent in the foreground from startnet.cmd:

wpeinit
set AGENT_SERVER_URL=https://control.example.com
set AGENT_BOOTSTRAP_TOKEN=<token>
start "ExecuteR Agent" X:\ExecuteR\ExecuteR-Agent.exe foreground

One token for both phases. Re-enrolling with the token that enrolled the device spends no extra use. It must still be valid when the installed OS enrolls, so give it an expiry longer than imaging takes.

On Enrollment triggers fire once per device. To run something after imaging, aim the trigger at a dynamic group where OS name is not Windows PE.

Agent upgrades

Upgrade Agent… and Roll Back Agent… are in the device menu, the bulk Actions menu, and the right-click menu of any group or folder, nested groups included.

  • Version: pick a version, or leave Newest for Each Device.
  • Offline devices: queued until they come back.
  • Rollback: returns a device to the version its last upgrade came from.

Upgrades queued from the Sites folder

Settings › Agent Upgrades:

Setting What it does
Automatic Upgrades Keeps online devices on the newest version. It never downgrades and never retries a version that failed on that device.
Start Within (Minutes) Large batches go out every 15 seconds, so every queued online device starts its download within this many minutes (default 3). The server is never hit all at once.
Health Deadline (Minutes) How long a new version has to report healthy before the watchdog rolls it back (default 10).
Never Upgrade Groups that automatic upgrades leave alone.
Keep Versions How many agent versions the server keeps for rollbacks (default 5).

Settings › Agent Upgrades

Where versions come from. Every server release carries the agent packages of the same version. The server adds them to its version catalog at startup and keeps the older ones, so a rollback has something to go back to.

The watchdog. Each package installs a second, small service next to the agent: ExecuteRWatchdog on Windows, executer-watchdog on Linux and macOS. It does two things:

  • Keeps the agent running. If the agent stops sending its health beacon, the watchdog restarts it. A deliberate ExecuteR-Agent.exe stop is respected.
  • Applies upgrades. It keeps a new version only if it reports healthy and connected within the health deadline. Otherwise it puts the previous version back by itself. How it upgrades depends on how the agent was installed:
    • Installed by the MSI: the agent upgrades through its MSI, so Programs and Features and detection tools always see the real version. The watchdog starts a detached copy of itself, which installs the MSI through the Windows Installer API in process (no msiexec). The copy outlives the services the MSI stops. A rollback reinstalls the previous MSI, which the installer keeps under %ProgramData%\ExecuteR\packages (or takes from the server).
    • Portable install: the watchdog swaps the files in place.

Versions are semantic: releases are 1.0.0, 1.1.0 and so on, and builds between releases add a fourth number (1.1.0.4). Older calendar versions (2026.10.23.2331) count as older than every semantic version.

Agents installed before the watchdog existed install it during their first upgrade.

Tracking. The device's Agent Upgrades tab and Device History show each attempt and its outcome: upgraded, rolled back or failed, with the reason and the last log lines.

Removing devices

Remove Agent… is in the device menu, the bulk Actions menu, and the right-click menu of any group or folder, nested groups included. It needs the devices.remove permission, which only Admin has by default.

The device leaves the system at once, and then:

  • Online: the agent uninstalls straight away, and its credentials and data are wiped. MSI installs uninstall through Windows Installer in process, so they leave Programs and Features too.
  • Offline: the removal waits for as long as the device stays away, and the agent uninstalls when it returns. Stop Trying ends the wait: the device stays blocked and keeps its agent.

Removed devices in the Devices list

Finding them later. Removals show dimmed in the Devices list for 7 days after their last change, then only under the Removals status filter. The record and its history stay.

Credentials. Agents on 1.1.0 or later hold a 24-hour credential and renew it over HTTPS at every start and at half life. A removed device is refused renewal, so it is cut off within a day, and when it hears why it uninstalls itself. It ignores that answer over plain HTTP or with TlsSkipVerify.

Coming back. Bootstrap tokens created before the removal can't re-enroll the device. A token created after it can.

Agents below 1.1.0 can't take the remove command and hold a credential that never expires. Their removal shows Uninstall It by Hand or Upgrade It First. The server ignores what they report, but they can still connect to NATS.

Version floor. An agent on 1.1.0 or later can't be moved below 1.1.0, because older agents can't renew their credential.

Remote shell

On Windows devices the shell page has a Shell picker:

  • Automatic: the first one the device has, in the order below.
  • PowerShell 7: pwsh.exe.
  • Windows PowerShell: powershell.exe.
  • Built-In PowerShell: the agent's own PowerShell host. It works without anything installed, including in WinPE.
  • Command Prompt: cmd.exe.

A shell you pick that isn't installed fails with a clear message. The choice is remembered per browser.

Lifecycle

Presence beats every 30 seconds. Inventory reports at start and then every 15 minutes (InventoryInterval).

A device offline past the orphan window — 30 days by default (DEVICE_ORPHAN_AFTER_DAYS) — is marked orphaned. Push a new bootstrap token and it re-enrolls, reclaiming its history.