Copy with Ctrl+Shift+C, Ctrl+Insert or Ctrl+C over a selection (Ctrl+C alone still interrupts); paste with Ctrl+V, Ctrl+Shift+V or Shift+Insert through the browser's own paste; right-click copies the selection or pastes. Copy and Paste buttons on the shell page and the pop-out toolbar. Terminal Settings: right-click behaviour, Copy on Select, and Ask Before Multi-Line Paste for shells that would run each pasted line. Pastes over 1 MiB are refused; input goes to the device in 32 KiB pieces. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
243 KiB
ExecuteR
Secure cross-platform endpoint management: a self-contained .NET agent enrolls over ordinary HTTPS, establishes scoped NATS messaging over WebSocket through the same reverse-proxy edge, publishes live state, accepts durable work, runs PowerShell in-process, and provides a secured interactive terminal — while the browser uses a WebSocket-connected NATS client for near-real-time UI updates with no SignalR, SSE, or polling.
- Agent — single self-contained executable for Windows, Linux and macOS (x64 + arm64, .NET 10), running as a Windows service / systemd unit / launchd daemon. Deterministic hardware identity, secure one-time bootstrap, hardware inventory, in-process PowerShell (System.Management.Automation) plus PowerShell 5 and Bash engines, interactive remote shell (ConPTY on Windows, forkpty on Linux/macOS), presigned-URL file delivery.
- Backend — ASP.NET Core control plane: REST API, SQLite, local + OIDC auth, RBAC, NATS operator/JWT issuance, JetStream command dispatch, live event relay.
- WebUI — React + MUI console (Mantis Pro shell): live device status, a nested group tree, run now and schedules, Monaco PowerShell editor with typed parameters and reusable Functions, live job output and progress, xterm.js remote shell.
Table of contents
- Architecture
- Component flow
- Agent-to-component flow
- Prerequisites
- Deploy to a server
- Local development
- Required secrets
- Generating local secrets
- Docker Compose
- Standalone server binary
- Server installer
- Networking and TLS
- Message security
- Reverse proxy routes
- Agent foreground mode and service lifecycle
- Agent upgrades and the watchdog
- MSI public properties
- Registry paths and GPO precedence
- Agent settings precedence and profiles
- Bootstrap and URL install
- Windows PE
- Sign-in
- Custom roles and permissions
- Typed script parameters and Functions
- Script engines
- Sequences
- Secrets providers and $Secrets
- Device groups and script triggers
- Group runs and schedules
- Database providers
- Logging
- Device lifecycle: reconnect or orphan
- Removing devices
- Agent installer delivery
- Agent upgrades from the server
- Device files
- Device registry
- Remote View
- S3 file delivery
- CI/CD and GITEA_* variables
- Versioning
- Branding
- Troubleshooting
- Screenshots
- Licence
Architecture
Network topology — every arrow crossing the edge is HTTP/HTTPS on port 443. Agents and browsers never contact NATS directly: their NATS client speaks WebSocket to the reverse proxy, which forwards to the NATS WebSocket listener.
flowchart LR
A["Windows Agent"]
B["Browser / React console"]
P["Reverse Proxy :443"]
A -->|"HTTPS: bootstrap, install"| P
A <-->|"WSS: NATS session"| P
B -->|"HTTPS: REST API"| P
B <-->|"WSS: NATS session"| P
subgraph Stack ["Docker stack (private network)"]
UI["React WebUI"]
API["ASP.NET Core Backend"]
N["NATS: WebSocket + TCP"]
DB[("SQLite / Postgres / SQL Server")]
JS[("JetStream")]
end
P -->|"/"| UI
P -->|"/api/*"| API
P -->|"/messaging/agent"| N
P -->|"/messaging/browser"| N
API <-->|"NATS TCP (internal only)"| N
API --> DB
N --- JS
The only externally reachable route is HTTP/HTTPS on the edge proxy. NATS TCP (4222) is never published to the public network.
Message flow over those sessions — once the WSS sessions above are established, messages travel in both directions on them. The subjects each party may use are enforced by its NATS JWT.
flowchart LR
A["Agent"]
N["NATS"]
API["Backend"]
B["Browser"]
A -->|"presence, inventory, job output/progress/state, shell output"| N
N -->|"durable commands: script, inventory, file, shell"| A
N <--> API
API -->|"republished, session-scoped events"| N
N -->|"browser.session.* only"| B
B -->|"browser.session.shell.input only"| N
Both agent and browser traffic in this second diagram physically rides the proxied WebSocket session from the topology diagram.
Component flow
How a request or event moves through the internal components.
flowchart TB
subgraph Browser
UI["React pages"]
BN["Browser NATS client (WSS)"]
end
subgraph Backend
REST["REST API + Auth + RBAC"]
ISS["NATS credential issuer"]
DISP["Command dispatcher (JetStream)"]
WORK["Messaging workers"]
BR["Browser event broadcaster"]
SB["Shell bridge"]
S3["S3 presign service"]
EF[("EF Core / SQLite")]
end
subgraph Fabric
CORE["NATS Core"]
JSS["JetStream: COMMANDS, JOB_EVENTS"]
end
UI -->|"login, CRUD, run"| REST
UI -->|"POST /api/messaging/credential"| ISS
BN -->|"subscribe browser session subjects (via proxy)"| CORE
REST --> EF
REST --> DISP
DISP --> JSS
WORK -->|"consume presence/inventory/output/state"| CORE
WORK --> EF
WORK --> BR
BR -->|"publish browser session events"| CORE
CORE --> BN
SB -->|"forward shell input, relay output"| CORE
REST --> SB
REST --> S3
Agent-to-component flow
What the agent does after it starts, and which backend component handles each message.
sequenceDiagram
participant A as "Agent"
participant API as "Backend REST"
participant N as "NATS / JetStream"
participant W as "Messaging workers"
participant DB as "SQLite"
participant U as "Browser"
A->>A: "CIM fingerprint to deterministic ClientId"
A->>A: "Generate User NKey (seed stays local)"
A->>API: "POST /api/enrollment/bootstrap"
API->>DB: "Consume token, bind device, audit"
API-->>A: "Scoped NATS user JWT"
A->>N: "WSS connect (JWT + NKey)"
A->>N: "presence (30s), inventory (start + interval)"
N->>W: "presence / inventory"
W->>DB: "upsert device + inventory"
W->>U: "authorized browser session events"
API->>N: "durable script/file command (JetStream)"
N->>A: "command (explicit ack after durable record)"
A->>N: "job output / progress / state"
N->>W: "persist + relay"
W->>U: "live job updates"
Full script-execution, enrollment, and remote-shell sequence diagrams are in docs/sequences.md.
Prerequisites
- .NET SDK 10 (
dotnet --versiongives 10.x) - Node.js LTS (22+) and npm — for the WebUI
- Docker + Docker Compose — to run the stack
- Windows — required to build/run the agent (CIM, ConPTY, DPAPI, Windows service). The backend and WebUI are cross-platform.
- WiX Toolset v5 (restored automatically) — for the MSI
- Visual Studio Build Tools with Desktop development with C++ (MSVC, and the
ARM64 build tools for win-arm64) — the Native AOT linker for the Being Viewed
banner (
scripts/Package-Agent.ps1); the CIwindows-hostrunner needs it too
Deploy to a server
One command on any Docker host brings up the whole stack — no clone, no checkout. It pulls the published images, falling back to building from source only if a pull is not possible:
curl -fsSL https://prod.git.gracesolution.info/gsadmin/ExecuteR/raw/branch/main/scripts/deploy.sh | bash
That writes .env with a generated admin password, prepares the bind-mount
tree, and generates real NATS keys by running the backend image's own
nats-auth CLI — so the host needs nothing but Docker (Compose 2.20.2 or
newer).
Database — a new install runs on the bundled Postgres container
(EXECUTER-DB-00001, on the internal network only, no host port); deploy.sh
generates its password into .env (DATABASE_PASSWORD). An install that
already has a SQLite database (API/Data/app.db) and names no provider in
.env stays on SQLite: deploy.sh writes DATABASE_PROVIDER=sqlite and
says how to move (see Moving from SQLite to
Postgres). An .env that already says
DATABASE_PROVIDER=sqlite is left as it is.
To pull the published images instead of building, set the registry in
.env before running (a private repo also needs a token — any Gitea account
token works):
REGISTRY=prod.git.gracesolution.info/gsadmin
REGISTRY_USERNAME=<gitea-user> # private repo only
REGISTRY_TOKEN=<gitea-token> # private repo only
The stack assumes you already run an edge proxy terminating TLS on :443 (see
Networking and TLS and
Reverse proxy routes). To have the stack run its own
nginx edge instead, opt in and give it your public hostname:
curl -fsSL https://prod.git.gracesolution.info/gsadmin/ExecuteR/raw/branch/main/scripts/deploy.sh \
| bash -s -- --with-proxy --host control.example.com
First sign-in — no admin password is prompted for. The backend generates a
one-time password on first boot and writes it to
<data>/initial-admin-password.txt (/data/… in the container); the first
sign-in forces a new one. Locked out? Mint a fresh one-time password with:
docker exec EXECUTER-API-00001 dotnet Backend.dll reset-admin
Prefer not to pipe curl into a shell? Clone the repo and run
./scripts/deploy.sh (same flags). For a single self-contained binary with no
Docker at all, see Standalone server binary.
Local development
# One-time setup: restores packages, installs WebUI deps, generates secrets
./scripts/Initialize-Repository.ps1
# Build everything with one version (from git: 1.4.0.7, see Versioning)
./scripts/Build.ps1 -IncludeWebUI
# Run tests
./scripts/Test.ps1 # unit
./scripts/Test.ps1 -IncludeWebUI # + WebUI typecheck and lint
Run the full stack from your working tree (builds images locally):
docker compose --env-file .env -f IaC/compose/docker-compose.yml -f IaC/compose/docker-compose.dev.yml up -d --build
Run pieces directly for a fast inner loop:
# Backend (Development seeds a demo script; DEV_SEED=1 adds sample devices/jobs)
$env:ASPNETCORE_ENVIRONMENT='Development'; $env:ASPNETCORE_URLS='http://127.0.0.1:19080'
$env:INITIAL_ADMIN_USERNAME='admin'; $env:INITIAL_ADMIN_PASSWORD='DemoPass123!'
dotnet run --project src/Backend
# WebUI (proxies /api and /messaging to the backend + NATS)
npm --prefix src/WebUI run dev
Required secrets
Committed: .env.example, secrets/README.md, scripts/New-LocalSecrets.ps1.
Never commit generated secrets (enforced by .gitignore).
| Secret | Purpose |
|---|---|
INITIAL_ADMIN_PASSWORD |
Optional first-boot admin password; empty generates one into <data>/initial-admin-password.txt |
NATS_OPERATOR_SEED |
NATS operator identity |
NATS_ACCOUNT_SEED |
Application account identity |
NATS_ACCOUNT_SIGNING_SEED |
Backend signs user JWTs with this |
DATABASE_PASSWORD |
The database password; for the bundled Postgres generated by deploy.sh / New-LocalSecrets.ps1 and set on its first start (losing it means resetting that database's password by hand) |
OIDC_CLIENT_SECRET |
Only when OIDC is enabled |
GITEA_TOKEN |
CI release/push automation |
S3_SECRET_KEY |
Only with an external S3 store |
S3_EMBEDDED_SECRET_KEY |
Only with replicas, which share one store (Swarm, Kubernetes) |
Non-secret identifiers (NATS_*_PUBLIC_KEY, GITEA_URL, GITEA_OWNER,
GITEA_REPOSITORY, CONTAINER_REGISTRY) may live in .env.
Generating local secrets
./scripts/New-LocalSecrets.ps1
This generates real Ed25519 NATS keys (operator, APP account, account
signing key, SYS account/user) and the resolver preload using the backend's
nats-auth CLI — the same NATS.Jwt/NATS.NKeys code the backend uses at runtime,
so no fake seeds:
dotnet run --project src/Backend -- nats-auth init --output secrets/nats
It writes .env (with a random admin password, the account signing seed and,
for a new .env, a generated DATABASE_PASSWORD for the bundled Postgres)
and secrets/nats/resolver.conf (mounted into the NATS container). With
-Force an existing .env's database settings are kept.
Docker Compose
Deployment manifests live under IaC/: IaC/compose (single-host
Docker Compose), IaC/swarm (multi-node Docker Swarm with replicas), and
IaC/k8s (Kubernetes). All three follow the stack conventions and share the
same images: use Compose for a single host, and Swarm or Kubernetes to scale
out with replicas.
The Compose stack uses EXTERNAL + INTERNAL bridge networks, container
names EXECUTER-{DB,NATS,API,WEB}-00001, service-name networking, and uncommon
host ports.
| Service | Container | Host port | Internal |
|---|---|---|---|
| postgres | EXECUTER-DB-00001 |
none (opt-in, below) | 5432, INTERNAL network only |
| nats | EXECUTER-NATS-00001 |
19222 (WebSocket) |
4222 TCP, 8222 monitor |
| backend | EXECUTER-API-00001 |
19080 |
8080 |
| webui | EXECUTER-WEB-00001 |
13080 |
3000 |
Volumes bind under ${STACK_BINDMOUNTROOT}/${STACK_NAME}/{Tier}/Data
(Postgres/Data for the database, which runs as PUID:PGID like the
backend). The NATS and Postgres images are pinned by digest
(NATS_VERSION, POSTGRES_VERSION). See .env.example for every variable.
The postgres service is in the Compose profile postgres, which
COMPOSE_PROFILES=postgres in .env turns on. deploy.sh keeps that in line
with the database: on for the bundled Postgres, off for
DATABASE_PROVIDER=sqlite or a DATABASE_CONNECTION_STRING that points
elsewhere, so the container is then neither pulled nor started. The backend
waits for it to be healthy when it runs (depends_on … required: false, which
needs Compose 2.20.2). To reach it from the host (psql, pgAdmin), set
POSTGRES_BIND (e.g. 127.0.0.1) and POSTGRES_PORT (default 15432);
deploy.sh then adds docker-compose.postgres-port.yml (by hand:
-f IaC/compose/docker-compose.postgres-port.yml).
# from the repository root
docker compose --env-file .env -f IaC/compose/docker-compose.yml up -d --build
# ...or just: ./scripts/deploy.sh
Standalone server binary
For a quick spin-up without containers, one self-contained ExecuteR-Server
binary serves the WebUI (static SPA), the API, the /messaging/* WebSocket
relay, and supervises a nats-server sidecar. CI publishes
ExecuteR-Server-<version>-win-x64.zip, …-linux-x64.zip and
ExecuteR-Server-<version>.msi
(build locally with ./scripts/Package-Server.ps1):
ExecuteR-Server setup
Generates NATS keys, the sidecar config and appsettings.json — and
downloads nats-server for this OS/architecture if it is not bundled.
TLS: the managed self-signed chain by default; --tls-source store
--tls-thumbprint <hex> (Windows) or --tls-source file --tls-cert-file
<pfx|pem> [--tls-key-file <pem>] [--tls-password <pw>] serves your own
(checked here, so a wrong path or password fails setup); --tls 0 for HTTP.
--data <dir> puts the data folder elsewhere (default: data\ beside the
binary); once appsettings.json names one, setup keeps it.
ExecuteR-Server run in the foreground on https://0.0.0.0:9080
ExecuteR-Server service install Windows service / systemd unit
ExecuteR-Server service uninstall
ExecuteR-Server reset-admin [--user <name>] [--password <pw>]
Lockout recovery, run elevated on the server (service running or not)
No administrator password is asked for. At its first start the server
creates the built-in admin account with a generated one-time password
and writes it to data\initial-admin-password.txt (beside the binary;
/data/initial-admin-password.txt in the container). Only Administrators,
SYSTEM and the account the server runs as can open that file (inheritance
off; mode 600 off Windows), and the log only says where it is — logs are
shipped and bundled far more widely than the data folder, so the password
never goes there. The first sign-in demands a new password before any
session is issued, and the file is deleted once it has been changed.
--admin-user / --admin-password (MSI ADMINUSERNAME / ADMINPASSWORD)
still set one for scripted installs; a literal admin forces the same reset.
Locked out, or the file is gone? From an elevated prompt on the server:
ExecuteR-Server reset-admin new one-time password for the break-glass account, printed here
ExecuteR-Server reset-admin --user jdoe that built-in account instead
ExecuteR-Server reset-admin --password '<pw>' that password (still changed at the next sign-in)
It reads the same appsettings.json as the server, so it reaches the same
database whether the service is running or stopped; it turns the account
back on, clears its sign-in back-off, ends its sessions, turns Built-In
sign-in back on (OIDC redirect off), and is audited
(identity.break-glass.reset). No restart is needed. In a container:
docker exec EXECUTER-API-00001 dotnet Backend.dll reset-admin.
auth-reset is the same verb.
The Windows MSI wraps the same flow in a wizard (folders, database, certificate, server address) — see Server installer for its pages, every property, silent examples and upgrades. The MSI installs exactly one instance — multi-instance boxes use the ZIP with distinct ports and service names.
Bundles ship the agent installers (agent-package/ with Agent.msi,
Agent.zip, the unix zips and VERSION), so the URL install command works
immediately — no seeding, no S3. Agents enroll against the same base URL. Put
a TLS-terminating reverse proxy in front for production use; the compose stack
remains the recommended deployment for anything long-lived.
The standalone binary is configured through flat keys in the generated
appsettings.json next to the binary, or the same names as environment
variables (env wins). It honors the default proxy trust (loopback / RFC1918
/ CGNAT), so it works behind a typical reverse proxy untouched; setup
pre-writes the optional knobs — TLS_SELF_SIGNED, TLS_CERT_SOURCE,
TLS_CERT_THUMBPRINT, TLS_CERT_FILE, TLS_CERT_KEY_FILE,
TLS_CERT_PASSWORD, TLS_DISTRIBUTE_CA, TLS_CERT_DIR,
PUBLIC_SERVER_URL, TRUSTED_NETWORKS, TRUSTED_HOSTS, TRUST_PROXY — as
placeholders ready to fill. Because it carries the NATS signing seed and any
certificate password, setup restricts appsettings.json to Administrators,
SYSTEM and the account that ran it.
Multiple instances on one box: one directory per instance, distinct ports at setup, distinct service names at install:
ExecuteR-Server setup --http-port 9081 --nats-port 4223 --nats-ws-port 9223 --nats-monitor-port 8223
ExecuteR-Server service install --name ExecuteRServer2
--bind <ip> controls the HTTP bind address (default 0.0.0.0; e.g.
--bind 127.0.0.1 to serve only to a local reverse proxy). The NATS sidecar
always binds loopback — its ports are never exposed. Ports and bind land in
appsettings.json (Urls), so they can also be edited there afterwards.
Everything an instance owns — config, database, keys, NATS state, agent packages — lives inside its own directory, so instances never share state.
Server installer
ExecuteR-Server-<version>.msi installs the standalone server as the
ExecuteRServer service. A next-next-next install just works: SQLite in the
install folder's data\, HTTPS on 9080 with the managed self-signed chain,
the firewall opened for that port. Each page's labels are short; the detail is
in the tooltips.
| Page | What it asks |
|---|---|
| Folders | Install, data, log and backup folders, each with Browse. The data, log and backup folders follow a changed install folder while they are still its defaults. Enable Windows Long Paths shows while Windows has them off. |
| Database | SQLite (in the data folder), PostgreSQL (server, port, database, SSL mode, username, password) or SQL Server (server or server\INSTANCE, optional port, database, Windows authentication or SQL login, Encrypt, Trust Server Certificate). Create If Missing (on). Test Connection signs in as you and shows the server's own answer, error code included; Next needs a passing test, or Continue Without a Successful Test after a failed one. |
| Certificate | Self-Signed (managed, renewed), Certificate Store (a thumbprint in Local Computer › Personal), File (PFX, or PEM certificate and key) or None (HTTP Only) — see Your own certificate. |
| Server Address | The port (HTTPS, or HTTP with None) and Redirect HTTP From a second port; Listen On all addresses or one of this computer's (listed); the NATS WebSocket bind and its client, WebSocket and monitor ports; the built-in object store's port; the Public URL; Open Firewall Ports. Next names the program holding a port that is taken. |
The wizard's banner and Welcome/Finish artwork are drawn from the product icon
(assets/installer/, regenerated with scripts/Generate-Icons.ps1), and the
icon shows in Programs and Features.
Every choice is a public property, so a silent install gives the same
result. The same checks run for /qn (ValidateServerSettings, before
anything changes): a wrong value, a port in use or a database that cannot be
reached fails the install with 1603 and the reason on a
ValidateServerSettings: line of the log (/l*v).
| Property | Default | Meaning |
|---|---|---|
INSTALLFOLDER |
C:\Program Files\ExecuteR\Server\ |
Program files. Held to what keeps every installed file within 260 characters (Windows Installer installs nothing deeper). |
DATAFOLDER |
[INSTALLFOLDER]data\ |
Database, keys, certificates, NATS state (DATA_PATH; a local drive; long paths allowed). |
LOGFOLDER |
[INSTALLFOLDER]logs\ |
LOG_DIRECTORY. |
BACKUPFOLDER |
[DATAFOLDER]backups\ |
DATABASE_BACKUP_PATH; a share is allowed (the service reaches it as the computer's account). |
ENABLELONGPATHS |
1 turns Windows long paths on (LongPathsEnabled; never turned off). Required for a SQLite database deeper than 260 characters. |
|
DBPROVIDER |
Sqlite |
Sqlite, PostgreSQL or SqlServer (postgres, mssql also read). |
DBSERVER |
Host; SQL Server also host\INSTANCE. |
|
DBPORT |
5432 (PostgreSQL) |
SQL Server: empty for 1433 or the named instance's own. |
DBNAME |
ExecuteR |
Created when missing (DBCREATE). |
DBAUTH |
Windows |
SQL Server: Windows (the service signs in as this computer: NT AUTHORITY\SYSTEM when SQL Server is local, DOMAIN\COMPUTER$ otherwise) or Sql. PostgreSQL is always a user and password. |
DBUSER, DBPASSWORD |
The login. DBPASSWORD is hidden from the log and stored DPAPI-protected. |
|
DBSSLMODE |
Prefer |
PostgreSQL: Disable, Allow, Prefer, Require, VerifyCA, VerifyFull. |
DBENCRYPT, DBTRUSTCERT |
1, off |
SQL Server: Encrypt; Trust Server Certificate. |
DBCREATE |
1 |
Create the database when it is missing and the account may. |
DBSKIPTEST |
1 installs without a successful test (the server creates the database at its first start if its own account may). |
|
BINDADDRESS |
0.0.0.0 |
The listen address: all, or one of this computer's. |
HTTPPORT |
9080 |
Console, API and agents; HTTPS unless TLS is off. |
HTTPREDIRECTPORT |
A plain HTTP port that only redirects to HTTPS (HTTP_REDIRECT_PORT), such as 80. |
|
NATSPORT, NATSWSPORT, NATSMONITORPORT |
4222, 9222, 8222 |
The NATS sidecar; client and monitor on 127.0.0.1. |
NATSBIND |
127.0.0.1 |
The NATS WebSocket bind; 0.0.0.0 for an edge proxy on another host. |
OBJECTSTOREPORT |
9199 |
The built-in S3 store, on 127.0.0.1 (S3_EMBEDDED_PORT). |
PUBLICSERVERURL |
PUBLIC_SERVER_URL; empty takes it from each request. |
|
FIREWALL |
1 |
Inbound rules (ExecuteR Server (…)) for the server's port, the redirect port and an exposed NATS WebSocket, each tied to its program; 0 for none. Removed with the server. |
ENABLETLS, TLSSOURCE, TLSTHUMBPRINT, TLSCERTFILE, TLSKEYFILE, TLSCERTPASSWORD |
1, selfsigned |
The Certificate page. |
ADMINUSERNAME, ADMINPASSWORD |
A first administrator of your own (otherwise a one-time password is generated). | |
PURGEDATA |
On removal, 1 deletes the data and log folders, keys and the self-signed chain. |
Flags take 1 for on, and 0, false, no or off for off (left out, a flag takes its default).
# SQLite, everything default
msiexec /i ExecuteR-Server.msi /qn /l*v install.log
# SQLite on another drive, logs and backups elsewhere, HTTP redirected from 80
msiexec /i ExecuteR-Server.msi /qn DATAFOLDER="D:\ExecuteR\Data" LOGFOLDER="D:\ExecuteR\Logs" `
BACKUPFOLDER="\\backup01\ExecuteR" HTTPREDIRECTPORT=80 PUBLICSERVERURL=https://executer.example.com
# PostgreSQL, the database created if missing
msiexec /i ExecuteR-Server.msi /qn DBPROVIDER=PostgreSQL DBSERVER=pg01.example.com DBPORT=5432 `
DBNAME=executer DBUSER=executer DBPASSWORD="<password>" DBSSLMODE=Require
# SQL Server, Windows authentication (the installing account creates the database and gives this computer's account db_owner)
msiexec /i ExecuteR-Server.msi /qn DBPROVIDER=SqlServer DBSERVER="sql01\PROD" DBNAME=ExecuteR DBAUTH=Windows
# SQL Server, SQL login over an encrypted connection to a self-signed certificate
msiexec /i ExecuteR-Server.msi /qn DBPROVIDER=SqlServer DBSERVER=sql01 DBPORT=1433 DBNAME=ExecuteR `
DBAUTH=Sql DBUSER=executer DBPASSWORD="<password>" DBENCRYPT=1 DBTRUSTCERT=1
How it is configured. The binary's own setup runs first (keys, the
sidecar, appsettings.json with the listeners and --data), then the
installer writes its keys into appsettings.json beside the binary:
DATABASE_PROVIDER, DATABASE_CONNECTION_STRING (never with a password),
DATABASE_PASSWORD, LOG_DIRECTORY, DATABASE_BACKUP_PATH,
PUBLIC_SERVER_URL, HTTP_REDIRECT_PORT and S3_EMBEDDED_PORT; anything an
administrator added to the file is kept as it was. The database password goes
in as dpapi: and a DPAPI blob in the machine's scope (only this computer
reads it back, so a copy of the file carries no password), and it never
reaches the installer log: DBPASSWORD and the deferred actions' data are
hidden properties, and the password travels protected from the moment the
installer reads it. appsettings.json and the data, log and backup folders the
installer creates are restricted to SYSTEM and Administrators. With Windows
authentication on SQL Server the installing account creates the database and
gives the service's login (NT AUTHORITY\SYSTEM, or DOMAIN\COMPUTER$ for a
remote server) db_owner; when it may not, the log says what to grant.
Long paths. The data, log and backup folders may be longer than 260
characters: the installer creates and secures them through the \\?\ form,
the server's .NET code and its Go sidecars (nats-server, the object store)
open long paths by themselves, and the server's manifest is longPathAware.
SQLite, a native library, opens a database beyond 260 characters only when
Windows has long paths on (LongPathsEnabled, the Enable Win32 long paths
policy, or ENABLELONGPATHS=1); the installer refuses a SQLite data folder
that deep while they are off. The install folder itself stays within the
limit, since Windows Installer cannot install files beyond it. Paths with
spaces are quoted everywhere (the service's ImagePath, setup's arguments).
Upgrades and repairs go from Welcome straight to Ready: the configuration
in effect is kept, the install folder is found again from the registry, and
setup keeps the data folder appsettings.json names. The database changes
only when an upgrade's command line gives a different one (DBPROVIDER and
the rest; the data in the old database is left untouched); FIREWALL follows
the last install's choice, and the rules are rebuilt for the ports in effect.
Nothing an upgrade or repair runs drops or moves data. The choices other than
the password are remembered under HKLM\SOFTWARE\ExecuteR\Server\Install, so a
reinstall over kept data offers them again.
Removal stops and removes the service and the firewall rules and keeps the
data, sign-in and self-signed chain, so a reinstall resumes where it left off.
Remove All Data, Keys and Self-Signed Certificates on the Remove Data page,
or PURGEDATA=1 on a silent uninstall, deletes appsettings.json, the data
and log folders (wherever they are, never a drive root or the install folder),
secrets, the remembered choices, and the self-signed root, intermediate and
leaf in the Windows stores; a backup folder outside the data folder is kept.
The same cleanup is ExecuteR-Server.exe purge. The finish page of a first
install says where the one-time administrator password is and offers to open
the console.
Networking and TLS
ExecuteR encrypts its own listener by default with a self-managed certificate chain — see Self-Signed TLS below. Public TLS termination still belongs at a dedicated edge: it terminates TLS once with real certificates, renews them automatically via ACME, and gives you layer-7 visibility — access logs, request metrics, rate limiting, WAF hooks — for everything behind it.
The recommended edge is Nginx UI — a web console for nginx with ACME renewal built in, and it installs on Windows too.
Put it in front on :443 and forward the routes below. Because forwarded
headers are trusted from private address space by default (next section),
this works with zero ExecuteR-side configuration. For the standalone
Windows server the shortest path is installing Nginx UI on the same host
and proxying localhost:9080.
Self-Signed TLS (on by default)
The server encrypts its own listener by default: HTTPS with a chain it
manages itself — root CA → intermediate → leaf, issued on first boot and
auto-renewed in the background (leaf yearly, re-issued 30 days early and
hot-swapped without a restart). Opt out with TLS_SELF_SIGNED=0, setup --tls 0, or None (HTTP Only) on the server MSI's Certificate page
(ENABLETLS="" silently).
The reverse proxy then has two equally valid options — pick per your organization's security standards:
- Skip verification (nginx
proxy_ssl_verify off, Caddytls_insecure_skip_verify, HAProxyssl verify none). This is not insecure: the traffic on the hop is still fully encrypted — the self-signed roots simply are not distributed, so there is nothing for the proxy to verify against. - Establish trust: import the root and intermediate certificates into
the proxy's trust store (
fullchain.crtsits next to the PEMs for pinning). Be aware this adds a rotation duty — when the chain rotates at expiry, the proxy needs the new roots re-imported.
On Windows the chain lives in the machine certificate stores exactly
where each link belongs — root in Trusted Root Certification Authorities,
intermediate in Intermediate Certification Authorities, leaf in
Personal — so browsers on the server itself trust it with no warning.
The same chain is also mirrored as PEM files (certs, keys and
fullchain.crt under <data>/tls), refreshed on every renewal, so a local
Caddy / Nginx UI / nginx can bind or trust the files directly and stay
current. On Linux/macOS/containers the PEM files are the primary store
(TLS_CERT_DIR overrides; keep it on a persisted volume in containers).
For distribution, the root and intermediate alone — never the leaf,
never a key — are also written to <data>/ca-certificates
(root-ca.cer/.pem, intermediate-ca.cer/.pem, ca-chain.pem) and
rewritten on every renewal, so an administrator can push them by Group
Policy (Computer Configuration › Windows Settings › Security Settings ›
Public Key Policies: the root into Trusted Root Certification Authorities,
the intermediate into Intermediate Certification Authorities) or to a proxy.
Your own certificate
Instead of the managed chain, the listener can serve a certificate you provide — from the Windows certificate store or a file — with the managed chain staying the default:
| Setting | setup flag |
MSI property | |
|---|---|---|---|
TLS_CERT_SOURCE |
--tls-source |
TLSSOURCE |
self-signed (default), store, file |
TLS_CERT_THUMBPRINT |
--tls-thumbprint |
TLSTHUMBPRINT |
LocalMachine\My, with its private key (Windows) |
TLS_CERT_FILE |
--tls-cert-file |
TLSCERTFILE |
a PFX/P12, or a PEM (a fullchain PEM brings its intermediates) |
TLS_CERT_KEY_FILE |
--tls-key-file |
TLSKEYFILE |
the PEM key, when it is not in TLS_CERT_FILE |
TLS_CERT_PASSWORD |
--tls-password |
TLSCERTPASSWORD |
the PFX password, or an encrypted PEM key's |
TLS_DISTRIBUTE_CA |
1/0 overrides whether agents are given the issuing chain |
A provided certificate turns HTTPS on by itself and is reloaded without a restart: a replaced file within a minute, and a store certificate renewed by auto-enrollment (the configured one archived or within 14 days of expiry, its successor with the same subject and issuer) is followed, with the new thumbprint logged. The handshake sends the intermediates. A certificate that cannot be loaded stops the first start with the reason; a later failed reload keeps the current one in service.
When the provided certificate's issuing chain is not publicly trusted —
an enterprise CA — it is treated like the managed chain: the server's own
machine stores get the intermediate (Windows), /api/enrollment/ca serves
the intermediates and root (never the leaf), bootstrap tokens carry that
root's fingerprint, and <data>/ca-certificates holds the same files for
Group Policy. A publicly trusted chain (Windows: the root is in the
Third-Party Root Certification Authorities store; elsewhere, in the system
bundle rather than a locally added anchor) distributes nothing:
/api/enrollment/ca stays 404 and agents just validate it.
Settings › Server Certificate
The console shows the certificate in use — source, subject, names, issuer,
expiry, thumbprint, the chain and whether it is public or private, the
distribution folder, and whether agents get the chain pinned — and, on a
Windows server, the certificates in Local Computer › Personal that could
serve TLS (current, a private key the service can open, Server
Authentication or no EKU; unusable ones are listed disabled with the reason
on hover). Administrators (settings.manage) can Bind one, switch to
Self-Signed, or Use Configured again; each change is audited
(tls.certificate.bind, tls.certificate.self-signed,
tls.certificate.unbind) and applied without a restart.
A binding is not a thumbprint. It stores the certificate's identity — subject, issuer, DNS names and the certificate template an enterprise CA stamps in — and every minute each server picks the certificate to serve:
- Windows' own renewal link first: when the certificate it served was renewed (auto-enrollment archives it and records its successor), the successor, followed through several renewals, if usable.
- Otherwise the newest usable certificate matching the identity (latest issued, then latest expiry): the same template when the bound one had one (then from any issuing CA of that template), else the same issuer; and the same subject or the same set of DNS names.
So renewals and reissues need nobody; the page shows Following Renewals
and when this server last switched. The binding is a database setting (key
tls.serverCertificate), so every replica follows the same identity in its
own store; a Linux replica says it cannot use the Windows store and keeps its
configured certificate.
Precedence: a certificate setting in the process environment
(TLS_CERT_SOURCE, TLS_CERT_THUMBPRINT or TLS_CERT_FILE — a container or
service definition) decides, and the page says so; otherwise the console
binding wins over appsettings.json, which is what setup and the MSI write
and stays the default when no binding exists. A listener started on plain
HTTP needs TLS turned on and a restart before a certificate can be bound.
When a switch brings a new private root, the page calls it out for 30 days (New Root Since): agents enrolled before cannot validate the new chain until that root is pushed to them (from the distribution folder) or they enroll again; new bootstrap tokens already carry its fingerprint. Renewals under the same CA need nothing — the handshake sends the new intermediates and the agents' CA refresh installs them.
API (settings.manage): GET /api/settings/server-certificate,
POST /api/settings/server-certificate/bind { "thumbprint": "…" },
POST /api/settings/server-certificate/self-signed,
DELETE /api/settings/server-certificate/binding.
How agents trust the server
It just works when the agent talks to the server directly. Every
channel — enrollment, the HTTPS API, downloads and upgrades, and the NATS
WebSocket — first validates the certificate normally; if that succeeds the
agent does nothing more (a public certificate, a proxy's, or a CA already
trusted, for instance by Group Policy). Only when validation fails on an
untrusted chain does the agent use the fingerprint in the bootstrap token
(<secret>.<sha256 of the root's public key>): it fetches the chain from
/api/enrollment/ca, keeps only the root matching the fingerprint and the
CAs that chain to it (anything else in the response is dropped), installs
them into the OS trust store (LocalMachine Root / Intermediate CA on Windows,
the system anchors on Linux, the System keychain on macOS), keeps them as its
own anchors (%ProgramData%\ExecuteR\server-ca.pem) and connects again with
normal validation. Those anchors back every later connection should the OS
store lose the CA, and a background refresh over the validated connection
keeps them and the store current as the server renews. Name mismatches are
never accepted. The install scripts' package download follows the same
rule: validate first, and only on a trust failure fetch the CA and accept the
server through a chain that ends at the pinned root (PowerShell 5.1, or
curl --cacert after an openssl check). For an accept-any escape hatch,
insecure / TlsSkipVerify=1 remains.
Agents enrolled before a switch to a certificate from a different CA cannot validate the new one through their old anchors: give them a new bootstrap token (or push the new CA by Group Policy first).
Message security
On top of TLS and the per-agent NATS permissions, every application message between the server and an agent is sealed, signed and checked for freshness and replays at the application layer (envelope v2). TLS ends at the reverse proxy, and NATS permissions only say who may publish where; this layer keeps message contents private and unalterable even to someone who can reach NATS itself.
Threat model
| Who | Without sealing | With sealing |
|---|---|---|
| The NATS server, its operator, its disk (JetStream) | reads and changes every message; script content, $Secrets values and file contents sit in plaintext on disk |
sees subjects, sizes and timing only; JetStream holds ciphertext |
| The plain WebSocket hop between a reverse proxy and NATS | reads and changes everything | same as above |
| A stolen account signing key (can mint any NATS user) | can publish commands to any agent, impersonate agents, subscribe to everything | can still connect and publish, but cannot produce a message an agent or the server accepts, nor read one |
| Someone replaying captured messages | a replayed command or event runs again | refused: expired, or seen before |
| A compromised agent | can publish job output/state claiming another device's jobs | a job message must be signed by the device it names |
Out of scope: a compromised server (it holds the keys), a compromised endpoint (it holds its own), traffic analysis, and denial of service (anyone who can publish on a subject can still flood it; the receivers drop what does not verify).
Keys
- Server: one key set — a command-signing key (Ed25519, an NKey) and an
ECDH P-256 key — under a key id (
kid). Kept as one secret application setting, encrypted at rest with the server's Data Protection key ring (shared by every replica), never in plaintext in the database or the logs. Made on the first start; every replica reloads it every minute (and at once when a message names a key it does not hold). - Agent: an ECDH P-256 key pair kept with its credentials (DPAPI LocalMachine on Windows, mode 0600 in a 0700 directory on Linux/macOS); it signs with the NKey it already authenticates to NATS with, whose public key the server bound to the device at enrollment.
- Browser tab: an ECDH P-256 key pair made with WebCrypto (the private half never leaves the tab's memory), and one the server makes for that browser session.
Every key and nonce comes from the operating system's secure random generator
(.NET RandomNumberGenerator, WebCrypto getRandomValues). No crypto library
beyond the .NET BCL, WebCrypto and the NKeys library NATS already uses.
Key exchange
- New enrollment: the agent sends its ECDH public key with its NKey and the bootstrap token; the answer carries the server's keys, which the agent pins. Re-enrollment replaces both keys (and an enrollment without a message key, an older agent, drops the old one).
- Agents enrolled before sealing: the exchange rides on the credential
renewal, which runs at every agent start and at half the credential's life,
over HTTPS. The agent adds its ECDH public key and signs
{clientId}|{timestamp}|{messageKeyPublic}with its enrolled NKey; the server records the key and answers with its own, which the agent pins. The server side is not trust on first use: the key is bound to the identity the server enrolled. The agent's side trusts the server's keys as it trusts the renewal itself — TLS validated against the OS store or the CA pinned at enrollment. This runs over HTTPS and not over NATS on purpose: whoever can reach NATS (the very threat above) could otherwise put keys of their own in between. While an upgrade could still roll back the renewal waits, so the agent starts sealing only once the upgrade is kept.
Envelope v2
{ "v": 2, "kid": "k1a2b3c4d5e6f", "type": "command.script", "messageId": "…",
"issuedUtc": "…", "expiresUtc": "…", "sender": "backend" | "<clientId>",
"subject": "agent.<id>.command.script", "nonce": "…", "ciphertext": "…", "signature": "…" }
The plaintext (the v1 envelope, or a bare reply) is AES-256-GCM encrypted
with a key made for this message alone: HKDF-SHA256 over the ECDH secret,
with the message id as salt and the direction (s2a, a2s) as info, and a
random 96-bit nonce. The associated data binds the key id, type, message id,
issue and expiry times, sender and subject, so a message cannot be moved to
another subject or have its expiry stretched. The Ed25519 signature covers the
header, nonce and ciphertext: the server's signing key from the server, the
agent's NKey from an agent. v1 messages are still parsed, from agents that do
not seal.
The ciphertext travels in base64, so a sealed message is about a third larger
than the same message in v1. The shipped nats.conf (and the standalone
server's) sets max_payload: 8MB; at the NATS default of 1 MB a script near
the library's limit (1,000,000 characters) no longer fits once sealed, and its
dispatch fails with the sizes in the server log. A NATS server you run yourself
needs the same setting.
Remote View and device file transfers seal each frame with a key per stream
(HKDF over the ECDH secret, the stream id as salt, screen or files as
info, one key per direction) and a 64-bit counter as nonce; a receiver takes
only counters higher than the last it took, so a duplicated, replayed or
reordered frame is dropped (a lost one is caught by the stream's own offsets).
Browser tabs: their NATS traffic (activity, job events, shell output and
keystrokes) uses the same envelope with the tab's and the session's ECDH keys
(s2b, b2s), without a signature — only the tab and the server hold that
key, so AES-GCM itself shows which of the two sealed a message. A tab outside
a secure context (no WebCrypto) gets the old unsealed channel.
Replay protection
Every message carries its issue and expiry time. Live messages (shell, Remote
View and file requests, presence, events, job output) live 2 minutes;
queued commands (scripts, files, inventory, upgrades, removals, key rotations)
live as long as the command stream keeps them (2 days), so an agent offline
that long still runs them; job states as long as their stream keeps them
(7 days). A receiver refuses an expired message, one issued in its future,
and one claiming a longer life than its kind may have, all with a clock skew
tolerance of 5 minutes (agent: MessageClockSkew in seconds, registry or
GPO; server: MESSAGE_CLOCK_SKEW_SECONDS), and logs the skew it sees (at most
every 10 minutes).
Message ids are remembered until the message could no longer be accepted:
- Agent: requests and queued commands in its local job store (SQLite), across restarts; a queued command only once it is acknowledged, so one redelivered after a crash still runs (job-id de-duplication then applies). Shell keystrokes in memory: their session ends with the process.
- Server: agent events (they start scripts: At Logon, On Demand, agent
ready) in the database (
SeenMessages), so no replica takes one twice (requests on the event subject, such as settings pulls and CLI runs, a batch per insert); everything else in a bounded in-memory window per node (presence, inventory, job output and states are idempotent: a replay to another node rewrites the same row). Job states are remembered once acknowledged.
Rollout and Require Sealed Agents
Sealing switches itself on per agent: a new agent at enrollment, an upgraded one at its first renewal after the upgrade is kept. Until then the server sends it v1 and takes v1 from it. Once the server holds an agent's key it sends that agent only sealed messages and refuses unsealed ones from it (a queued message stored before the key exchange is still taken, on both sides, for as long as such a message can still be in its stream). The device list and device page show a Sealed / Unsealed chip (the hover tells why), and the agent reports its state in inventory.
Settings › Message Security › Require Sealed Agents (off by default): the server refuses every unsealed message and sends nothing to an agent that does not seal (commands fail to dispatch; shell, files and Remote View answer that the device does not seal). Turn it on once the fleet has upgraded and the Unsealed count is zero.
An upgrade to an agent version older than the one that made a device's key exchange drops its key (that version may not seal); a version that does seal exchanges keys again at its next renewal.
Key rotation
Settings › Message Security › Rotate Keys makes a new key set; the old one stays accepted for 7 days. Every sealed agent is sent the new keys in a queued command sealed and signed with the old key it pinned; one that misses it gets them at its next renewal, or at once when a message names a key it has not pinned (it asks for a renewal). Agents keep accepting the previous key, so commands queued before the rotation still run.
What is and is not covered
| Path | Protection |
|---|---|
| Queued commands: script, file download, inventory, upgrade, remove, key rotation (JetStream) | v2, signed by the server, 2-day lifetime, replay-checked on ack |
| Shell open, input, resize, close; output and state | v2 both ways (keystrokes replay-checked in memory) |
| Remote View open/close requests and reply | v2 |
| Remote View stream frames | per-stream AES-GCM, counter nonces |
| Device files, logs (list, tail, read) and registry requests and replies | v2 |
| Device file, log and registry transfers | per-stream AES-GCM, counter nonces |
| Presence, inventory, agent events (ready, logon, upgrade, removal) | v2, signed by the agent; events replay-checked in the database |
| CLI run requests and replies (and any other request on the agent's event subject) | v2 both ways; replies (which may carry bearer credentials such as presigned URLs) are sealed for the asking device |
| Job output, progress, state | v2, signed by the agent; the device a job message names must be its signer |
| Browser activity, job and shell events; shell keystrokes | sealed per browser session (tabs in a secure context) |
| HTTPS API, enrollment, renewal, downloads | TLS (unchanged) |
| Subjects, message sizes, timing | not hidden |
Reverse proxy routes
The stack assumes an existing external reverse proxy terminating TLS on :443
and forwarding to the host ports above:
| Public path | Upstream |
|---|---|
/ |
webui :13080 |
/api/* |
backend :19080 |
/messaging/agent |
nats websocket :19222 |
/messaging/browser |
nats websocket :19222 |
The proxy must preserve the WebSocket upgrade and send X-Forwarded-For,
X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Prefix. Links the
server builds (install commands, Remote View) use the address the browser
used, port included: reached directly, a non-default port is kept from the
Host header; behind a proxy, send the client's host with its port
(X-Forwarded-Host $http_host in nginx), or send X-Forwarded-Port, which is
used when the forwarded host has no port and the port isn't the scheme's
default. PUBLIC_SERVER_URL overrides all of this. The backend
processes forwarded headers before auth and trusts them by default from
private address space — loopback, RFC1918 (10/8, 172.16/12, 192.168/16) and
CGNAT (100.64/10) — so dropping the stack behind a cloud or LAN reverse proxy
needs zero trust configuration. Setting TRUSTED_PROXIES /
TRUSTED_NETWORKS replaces those defaults with an explicit allow-list
(narrow this when untrusted peers share your private network), and
TRUST_PROXY=0 disables forwarded-header processing entirely. If path-based
proxying conflicts with your NATS WebSocket config, use dedicated hostnames
behind the same :443 edge.
Ready-to-adapt single-file edge samples ship for all three common choices — each with the same shape: banner header, BEFORE-USE placeholders, forwarded headers, WebSocket handling, commented IP allow-lists and the self-signed upstream variant:
- src/Infra/nginx — nginx-ui friendly site with edge rate limiting and long-lived WebSocket timeouts
- src/Infra/caddy — automatic HTTPS via ACME, runs on Windows too
- src/Infra/haproxy — stick-table rate limits and tunnel timeouts for the WebSocket sessions
The OIDC callback (/api/auth/oidc/callback) rides the /api/* route in
all of them — no extra route is needed. So does Remote View's WebSocket
(/api/devices/<id>/screen/<session>/socket): it needs the upgrade headers and
a read timeout above its 20-second pings (Remote View).
Agent foreground mode and service lifecycle
The one binary supports:
ExecuteR-Agent.exe foreground run interactively (console logging)
ExecuteR-Agent.exe install create/update the Windows service (idempotent)
ExecuteR-Agent.exe start start the service
ExecuteR-Agent.exe stop stop the service
ExecuteR-Agent.exe initialize install + start
ExecuteR-Agent.exe remove stop + remove the service
ExecuteR-Agent.exe status JSON line (service, version, server, credential) + human-readable
ExecuteR-Agent.exe version unified build version
ExecuteR-Agent.exe run <name|id> start an On Demand script (see "On Demand and the device CLI")
ExecuteR-Agent.exe upload <path> send files up to S3 (see "Device uploads to S3")
Launched by the SCM with no argument, it runs as a service (LocalSystem,
Automatic start, restart-on-failure recovery). Service manipulation uses
the Windows service APIs (advapi32 / ServiceController) — never sc.exe.
Start type. The agent is plain Automatic, not Automatic (Delayed Start), so
it is up early after a restart (Restart After Run relies
on it). install (which the MSI runs on every install and upgrade) sets it and
clears a Delayed Start an earlier version set; and the agent itself, starting
as a service, switches an Automatic (Delayed Start) registration to Automatic,
so an install upgraded by the watchdog's swap switches too. Manual or Disabled,
an administrator's choice, is left alone. The watchdog is plain Automatic as
well: it keeps the agent running and applies upgrades, so it starts with it.
On linux the systemd unit is WantedBy=multi-user.target with
After=network-online.target / Wants=network-online.target, enabled at
install; on macOS the launchd daemon has RunAtLoad.
Linux and macOS: the same commands work with the portable executer-agent
binary (install writes a systemd unit executer-agent or a launchd daemon
info.executer.agent, and symlinks the binary into /usr/local/bin so
executer-agent is on PATH; remove deletes both). Configuration lives in
/etc/executer/agent.json instead of the registry, credentials under
/var/lib/executer (mode 600).
On startup the agent idempotently installs PowerShell 7 when missing (Homebrew
on macOS, the official install script on Linux) — scripts run via the embedded
PowerShell SDK either way, so this only matters for operator convenience.
Remote shell works on every platform — ConPTY on Windows, a forkpty-backed
PTY (with a real controlling terminal, so job control and Ctrl-C behave) on
Linux and macOS.
On Windows devices the shell page's Shell picker chooses what starts:
Automatic (the default) takes the first of PowerShell 7 (pwsh.exe,
Program Files or PATH), Windows PowerShell, the agent's Built-In
PowerShell and Command Prompt (%ComSpec%); an explicit choice that is not
installed fails with a clear message instead of falling back. The last
choice is remembered per browser, and the shell page shows which shell
Automatic started. Built-In PowerShell is the agent's own embedded engine in
the SDK console host (the hidden ExecuteR-Agent.exe shell-host verb, with
the bundled modules on PSModulePath), so a PowerShell prompt is available
even where none is installed — Windows PE without the WinPE-PowerShell
component, for example. Linux and macOS agents ignore the choice and start
the login shell ($SHELL, else bash/zsh/sh).
In the console, Pop Out moves a shell into its own browser window without interrupting it: the session, scrollback and anything running carry over, and it keeps running while you use the rest of the console. Return to Console (or Bring Back on the shell page) docks the same terminal back. Closing the window brings it back when the console is showing that device's shell and ends the session otherwise; reloading or closing the console tab ends every popped-out shell, since they run on its page.
Terminal Settings (the Tt button; theme and text size also sit in a pop-out's toolbar) are remembered per browser and apply to every open shell at once: a theme (Dark, Classic, PowerShell Blue, Solarized Dark, Dracula, One Dark, Monokai, Nord, Gruvbox Dark, Tokyo Night, Ubuntu, High Contrast, Green Phosphor, Amber, Light, Solarized Light), the text size (9-28 px; in the terminal Ctrl + = / Ctrl + - or Ctrl + mouse wheel, Ctrl + 0 resets) and the scrollback, the output lines kept above the screen (1,000 to 25,000; 10,000 by default). Older lines drop off as new output arrives.
Clipboard. Copy and paste work as in Windows Terminal:
- Copy: Ctrl+Shift+C or Ctrl+Insert, or Ctrl+C while text is selected (with nothing selected, Ctrl+C still interrupts).
- Paste: Ctrl+V, Ctrl+Shift+V or Shift+Insert.
- macOS: ⌘C and ⌘V.
- Right-click copies the selection, or pastes when nothing is selected.
- The Copy and Paste buttons sit on the shell page and in a pop-out's toolbar.
The browser asks once for permission to read the clipboard; the keyboard paste needs no permission. On plain HTTP the browser gives no clipboard reading: the keys and copying still work, but there is no Paste button, and a right-click with nothing selected opens the browser's menu.
Terminal Settings can:
- make right-click open the browser menu instead;
- turn on Copy on Select;
- turn off Ask Before Multi-Line Paste.
That question appears when a paste has line breaks and the shell would run each line as it arrives. A shell in bracketed paste mode, such as bash 5.1 or later, takes the paste as one edit and isn't asked about. Pastes over 1 MiB are refused, and large pastes go to the device in 32 KiB pieces.
Run As picks whose account a new shell runs as: the Agent Account
(LocalSystem, root; the default each time) or the Signed-In User: the
console's user, else the only user signed in (several users and nobody at the
console is ambiguous, so the shell is refused rather than guessed), or one of
the signed-in users by name. The agent reports who is signed in with every
shell it opens, and with a refused run-as-user open, so the menu lists them;
it refuses a name that is not signed in (on macOS, anyone but the console's
user). Windows
starts the shell with that user's own token (WTSQueryUserToken), environment
and profile folder on their desktop, headless: no window appears for them.
Linux and macOS start the user's login shell through su -l. The server
refuses it for agents older than 1.13.0, which would ignore it and start the
agent's account instead; the audit entry records which account was asked for.
Agent upgrades and the watchdog
Every agent package (zip and MSI) carries a second, small binary beside the
agent: the watchdog (ExecuteR-Watchdog.exe, executer-watchdog on
Linux/macOS; self-contained, trimmed, about 12 MB). It runs as its own service,
keeps the agent running and applies the upgrades the server sends (see
Agent upgrades from the server for starting,
pacing and rolling them back).
| Windows | Linux | macOS | |
|---|---|---|---|
| Watchdog service | ExecuteRWatchdog (LocalSystem, Automatic, restart on failure) |
systemd executer-watchdog.service |
launchd info.executer.watchdog |
| Install folder | %ProgramFiles%\ExecuteR\Agent |
/opt/executer/agent |
/opt/executer/agent |
| Upgrade files | %ProgramData%\ExecuteR\upgrade |
/var/lib/executer/upgrade |
/var/lib/executer/upgrade |
| Watchdog log | <install>\Logs\ExecuteR-Watchdog.log |
<install>/Logs/executer-watchdog.log |
same |
The MSI installs and starts both services. ExecuteR-Agent.exe install /
initialize also register (and start) the watchdog when its binary sits next
to the agent, and remove takes the watchdog out first, so it cannot start the
agent again meanwhile. The watchdog has the same service verbs itself
(install, remove, start, stop, status, version, foreground). An
install from before the watchdog existed gets it with its first upgrade: the
agent copies it out of the downloaded package and registers it before handing
the package over.
How an upgrade runs on the device
- The agent takes the
command.agent.upgradecommand. It answers at once, without downloading, when it cannot or need not upgrade: unsupported (not running as the installed service, the package is for another platform, or a zip for an agent the MSI installed and the other way round), busy (another hand-over, swap, MSI run or unreported outcome is pending), or succeeded / already (it runs that version). A redelivered command (same upgrade ID) is ignored. - It waits a random start jitter (0 to the seconds the server sends), then
downloads the package (a server path resolved against the configured server
URL, or a presigned URL as is; the configured proxy and TLS trust apply) to
upgrade/downloads/<sha256>.zip, reporting downloading with progress. Size and SHA-256 must match the command (else failed / hash). It unpacks toupgrade/staging/<version>-<id>/(no agent binary inside: failed / package), makes sure the watchdog runs, writesupgrade/handover.jsonand reports installing. A hand-over the watchdog has not taken within 10 minutes fails as watchdog. - The watchdog checks the staging again (location, safe relative paths, every
file's size and SHA-256), stops the agent service, copies the files into
<install>/.next/<id>/and checks them there, moves the files they replace into<install>/.previous/<id>/and the new ones into place, and starts the agent. A move is retried only while another process holds the file (10 × 500 ms). Failures before any file moved leave the agent running and are tried again, three times in all, then end as failed / watchdog. - The new version is kept only when its health beacon reports the new
version, connected (command consumer bound and NATS open), written after
the start, within the health deadline the server sends (10 minutes by
default). Then
.nextand.previousgo and the outcome is succeeded. - Otherwise it is rolled back: the new files go to
<install>/.failed/<id>/(and are then deleted),.previouscomes back, the previous agent is started and given 5 minutes to report healthy. The reason is health-deadline, crashed (the new version exited three times, which ends the wait early) or swap (a file could not be moved), with up to 40 log lines: the new agent's own for a health or crash failure, the watchdog's for a swap. - The outcome is written to
upgrade/outcome.jsonand reported by whichever agent version runs afterwards as soon as it is connected; then the file is deleted, and old downloads and staging folders are removed (the newest is kept).
What a swap touches: the files the package brings, and every file inside a
top-level folder it ships (Modules\, so a module the new version dropped goes
too). Logs\, an operator's own files and the running watchdog binary are
never moved. The watchdog replaces its own binary last, after the new agent
is kept, and only when the package's watchdog is newer and runs (version
exits 0 within 30 s); it then restarts onto it through the service manager.
Agents the MSI installed
A swap would leave Windows Installer, Programs and Features and every
detection tool that reads them showing the version the MSI installed, so an
agent the MSI installed upgrades (and rolls back) through its MSI instead.
The agent finds out at start: Windows Installer holds a product of the agent's
UpgradeCode (MsiEnumRelatedProductsW) installed in its own folder; no
product, another folder, or no Windows Installer at all (WinPE) is a portable
install. It reports msi or portable on presence, the device page shows it
(Installed by MSI / Portable), and the server sends an MSI install the
version's Agent.msi (a version the server holds no MSI of is skipped as
no-package; it never gets the zip). Nothing runs msiexec.exe or
PowerShell: the MSI is installed in process through the Windows Installer API.
- The agent downloads and checks the MSI (same jitter, size and SHA-256 as a
zip) into
upgrade/msi/ExecuteR-Agent-<version>.msiand confirms it is the agent's MSI of that version (its UpgradeCode andUNIFIEDVERSION). For a rollback it sets the MSI of the version it runs now beside it (upgrade/msi/rollback/): its own kept copy, else the copy the server sends with the command (downloaded, checked and kept). Without either the upgrade still goes ahead, and the hand-over and the outcome say a new version that is not healthy cannot be rolled back automatically. - The watchdog checks both MSIs again, writes
upgrade/msi.json, copies its own binary toupgrade/msi/runner/and starts the copy detached (its own process group, out of the service's job, no console), because the MSI stops both services. No file is swapped. - The runner calls Windows Installer with no UI and a verbose log
(
/l*v) in<install>\Logs\agent-msi-<version>-<id>.log, withREBOOT=ReallySuppress. 0, 3010 and 1641 mean installed; 1618 (another installation under way) is tried again every 30 s for up to 10 minutes, then the upgrade fails as installer-busy; any other code, or 30 minutes without an answer, fails as msi with the code, the log path and its last lines (Windows Installer's own transaction leaves the previous version in place). - The MSI starts the new services; the runner keeps the version when its
beacon reports it, connected, within the health deadline. Otherwise it
installs the previous version's MSI again with
ALLOWDOWNGRADE=1(its own log,agent-msi-<previous>-<id>.log) and ends rolled back with the new agent's last log lines; with no MSI to go back to, the new version stays and the upgrade fails as health-deadline. A Roll Back Agent from the console installs the older MSI withALLOWDOWNGRADE=1from the start. - The runner leaves both services running, writes the outcome and exits. A
watchdog that starts meanwhile (the new version's, started by the MSI)
leaves a live runner alone; one that died is started again from
msi.json, at most three times, and the agent is never started by the watchdog while the run is pending.
MSIs are kept for later rollbacks in %ProgramData%\ExecuteR\packages\<sha256>\:
the one the device was installed from (the installer keeps it) and every one an
upgrade brought, the newest three. The first upgrade of an MSI install that has
none kept yet rolls back with the server's copy of its version, when the server
still holds it.
What you see on disk
| Path | Meaning |
|---|---|
upgrade/health.json |
the agent's beacon (version, PID, connected, time), every 5 s; written only by the installed service |
upgrade/handover.json |
a package waiting for the watchdog |
upgrade/handover.taken.json + upgrade/journal.json |
a swap under way; the journal names the phase (stopping, swapping, verifying, committed, rolling-back, rolled-back) and the SHA-256 of every file on both sides |
upgrade/outcome.json |
how the last swap ended, until the agent has reported it |
upgrade/downloads/, upgrade/staging/ |
the newest package, zipped and unpacked |
<install>/.next, .previous, .failed |
exist only during a swap |
upgrade/msi.json, upgrade/msi.lock |
an MSI upgrade under way: its phase (installing, verifying, rolling-back), Windows Installer's last code and busy retries; the runner holds the lock while it lives |
upgrade/msi/ |
the MSI being installed, the one to go back to (rollback/) and the runner's copy of the watchdog (runner/) |
<install>\Logs\agent-msi-<version>-<id>.log, ExecuteR-Watchdog-msi.log |
Windows Installer's verbose log of each MSI run, and the runner's own log |
%ProgramData%\ExecuteR\packages\<sha256>\ |
agent MSIs kept for rollback (the newest three) |
upgrade/removal.json |
a removal under way, or one that failed until the agent has reported it (On the device) |
If the watchdog itself stops part way (power loss, a kill), its next start
finishes or undoes the run from the journal: stopping starts over (the agent
runs meanwhile), swapping and rolling-back put the previous version back,
verifying goes on waiting for the new version (at least another minute when
the deadline has passed) and keeps or rolls it back. An upgrade that has a
journal or an outcome is never applied a second time.
When the watchdog restarts the agent
The watchdog never fights an admin. It acts only while the agent service is set to start automatically, and then only in two cases, at most once every 3 minutes:
- the agent runs, has run for over 3 minutes, and its beacon is older than 3 minutes: it hangs, so it is restarted (an agent that writes no beacon at all, an older version, is left alone);
- the agent stopped with a failure and is still stopped 3 minutes later (the service manager's own restarts gave up): it is started.
A clean stop is never undone. To stop the agent without the watchdog starting it again:
ExecuteR-Agent.exe stop # stays stopped until started or the next boot
Set-Service ExecuteRAgent -StartupType Manual # also across reboots: the watchdog leaves a non-automatic service alone
ExecuteR-Watchdog.exe stop # or stop the watchdog too
On Linux systemctl stop executer-agent (and systemctl disable for reboots).
On macOS the agent's launchd KeepAlive restarts a killed agent by itself; use
launchctl bootout system/info.executer.agent to keep it stopped.
For development, ExecuteR-Watchdog.exe foreground --agent process --install-dir <dir> --data-dir <dir> runs the same loop with console logging
against an agent it starts as a child process instead of a service (an agent
in the foreground refuses upgrade commands itself, so drive it with a
hand-made handover.json).
MSI public properties
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 |
ALLOWRESTART |
AllowRestart (see Restart After Run) |
ALLOWFILEACCESS |
AllowFileAccess |
ALLOWREGISTRYACCESS |
AllowRegistryAccess (see Device registry) |
ALLOWREMOTEVIEW |
AllowRemoteView (see Remote View) |
REMOTEVIEWASKFIRST |
RemoteViewAskFirst |
REMOTEVIEWALLOWUNATTENDED |
RemoteViewAllowUnattended |
REMOTEVIEWBANNER |
RemoteViewBanner (see Being Viewed banner) |
SKIPTLSVERIFY |
TlsSkipVerify (self-signed servers; hop stays encrypted) |
PROXYURL |
ProxyUrl (explicit outbound proxy; system proxy otherwise) |
JOBROOT |
JobRoot (where script jobs run; see Where scripts run) |
The installer never overwrites a non-blank existing value with a blank property, preserves configuration on upgrade, and removes runtime credentials only on a real uninstall (never during an upgrade).
Registry paths and GPO precedence
Normal config: HKLM\SOFTWARE\ExecuteR
Runtime state: HKLM\SOFTWARE\ExecuteR\Runtime
GPO policy: HKLM\SOFTWARE\Policies\ExecuteR
Effective configuration precedence is GroupPolicy > Agent Settings profile >
normal registry > dev-only environment > compiled defaults (each value carries
its provenance). The profile layer applies only to the settings profiles manage;
see Agent settings precedence and profiles.
Group Policy templates live in
src/Installer/Policies (ExecuteR.admx +
en-US/ExecuteR.adml).
Outbound proxy: the agent honors the system/environment proxy
(HTTP_PROXY/HTTPS_PROXY/NO_PROXY, or the Windows system proxy) for
enrollment and the persistent WebSocket connection, authenticating to the
proxy with the process account's default credentials — corporate
NTLM/Negotiate proxies work unattended. ProxyUrl (registry, GPO, MSI
PROXYURL, or configure --proxy) forces an explicit proxy instead. The
server does the same for its outbound HTTP (S3, OIDC, secrets providers,
downloads).
Job folder root: JobRoot (registry, GPO, MSI JOBROOT, or the
agent.json value of the same name on linux/macOS) moves script job folders
out of the agent's temp folder; see Where scripts run.
Agent settings precedence and profiles
Agent settings can be set four ways. Per setting, the highest one that sets it wins:
Group Policy (HKLM\SOFTWARE\Policies\ExecuteR) domain admins keep the final say
> Agent Settings profile (from the server) Settings › Agent Profiles
> device registry (HKLM\SOFTWARE\ExecuteR) MSI properties, configure, regedit
/ agent.json "SOFTWARE/ExecuteR" (linux/macOS)
> compiled default
(A dev-only environment variable sits between the registry and the default, in foreground runs only.)
Profiles
Settings › Agent Profiles (permission settings.manage) holds Agent Settings
profiles. A profile has a name, a priority, Enabled, the settings it sets
(each one Not Set, On/Off, or a value) and targets: devices, groups (nested
groups included) or All Devices, minus excluded devices and groups, exactly as on a
schedule. Where several enabled profiles reach a device, the lowest priority
number wins each setting (1 beats 2; equal numbers by name); a setting no profile
sets falls through to the registry/agent.json or the default. The editor previews
how many devices a profile reaches; the device list's Apply Settings… creates a
profile for the selected devices or adds them to an existing one.
A device-scoped role edits only profiles whose targets are inside its scope (never
All Devices), as with schedules. Every create, edit, device addition and delete is
audited (category settings, the profile before and after).
What profiles manage, and what they never do
| Setting | Applies |
|---|---|
AllowRemoteShell, AllowScriptExecution, AllowRestart, AllowFileAccess, AllowRegistryAccess |
live (switching Remote Shell off closes an open session; AllowRestart applies to the next job that ends) |
AllowRemoteView, RemoteViewNotify, RemoteViewAskFirst, RemoteViewAskTimeout (10–120 s), RemoteViewAllowUnattended |
live |
InventoryInterval (60–86,400 s) |
from the next report |
RemoteViewBanner, LogLevel, JobRoot |
after the agent restarts |
JobRoot is checked on the server (absolute, local, not a drive root, no .., not
in a user profile) and again by the agent, which keeps its default when the folder
is unusable.
Never managed, because each could cut the device off from the server or concerns enrollment and the trust of its connection:
| Setting | Why not |
|---|---|
ServerURL |
where the agent connects; a wrong value pushed from the server strands the device and the fix could never reach it |
BootstrapToken |
an enrollment secret, erased after enrollment |
TlsSkipVerify |
the trust of the connection itself; the server must never lower how the device checks it |
ProxyUrl |
the network path to the server |
ReconnectMinDelay, ReconnectMaxDelay |
how the agent finds its way back; a bad value keeps devices offline and the fix only arrives once they reconnect |
MessageClockSkew |
message security: too tight and the device refuses the server's sealed messages (the settings push included), too loose and replay protection weakens |
Delivery
- The server keeps, per device, the resolved set it last decided and a version
that only grows (at least the current Unix time in milliseconds). A profile edit,
a group membership or tag change, a device enrolling, or an inventory report (rule
groups can change with it) recomputes the set; a different set gets a new version
and is pushed as a durable command (
agent.<id>.command.settings, sealed and signed like every command), so an offline device takes it when it connects. A sweep every five minutes catches the rest and retries pushes that did not go out. - On connect the agent also pulls its set (
agent.settings.requeston its event subject, sealed request and reply), sending the version it holds; if that is ahead of the server's record (a restored database), the server answers with a newer one. A pull not answered within 20 s is asked again after 5–10 s, then after pauses that double up to 10 minutes (each a random point in its upper half, so a fleet that missed together asks apart), for as long as the session lasts or until a push newer than what it held arrives. - The server answers pulls apart from other agent events, a batch at a time (a fleet reconnecting asks all at once): the profiles, and every device's groups when a profile names groups, are read once and kept until a profile, group, member or tag change (or 30 s); the batch's devices and stored sets take a query each. A stored set that is what the profiles decide is sent as it is; anything else goes through the full reconcile.
- The agent ignores a set older than the one it holds (a queued push arriving after
a newer reply) and one for another client id. It keeps the last set in
HKLM\SOFTWARE\ExecuteR\Runtime\ManagedSettings(theSOFTWARE/ExecuteR/Runtimesection of agent.json on linux/macOS), so a restart without the server still applies it. A device no longer reached by any profile is sent the empty set, which clears its values back to the registry/agent.json or the default.
Visibility
The agent reports every setting (all but the bootstrap token) with its inventory: the effective value, its source (Group Policy, Profile name, Device, Default), and whether a value waits for a restart. The device page's Agent Settings card shows each one with a source chip (details on hover), Locked by Group Policy where a policy overrides the profile, the profiles that reach the device and what each wins, and Update Pending until the agent runs the server's latest version.
Bootstrap and URL install
The fastest path is Devices → + Add device: pick the platform (Windows / Linux / macOS), choose a single-use token or a multi-use one with any use count up to 9999 — or unlimited (24-hour expiry either way) — and Generate command issues the token and builds the paste-ready one-liner. Nothing is created until you confirm, and Esc / click-outside / Cancel dismisses without side effects:
# Windows (elevated PowerShell)
iwr 'https://control.example.com/api/enrollment/install?token=<token>' -UseBasicParsing | iex
# Linux
curl -fsSL 'https://control.example.com/api/enrollment/install?token=<token>&type=linux' | sudo bash
# macOS
curl -fsSL 'https://control.example.com/api/enrollment/install?token=<token>&type=osx' | sudo bash
The unix script detects the architecture (x64/arm64), downloads the matching
agent zip from the same origin, unpacks to /opt/executer/agent, configures
enrollment through the agent's own configure --url --token CLI and registers
the systemd unit / launchd daemon. Tokens can also be minted under
Settings, and the MSI installs directly:
msiexec /i Agent.msi /qn SERVERURL=https://control.example.com BOOTSTRAPTOKEN=<token>
The agent generates its NKey locally (the private seed never leaves the device), bootstraps over HTTPS, receives a scoped NATS JWT, erases the token, and connects over WSS. The device appears in the UI within seconds.
Running the command again is safe. Every script (Windows, Windows PE,
Linux, macOS) looks at the device before it acts and ends with one outcome
line — Installed, Upgraded, Repaired, Already Installed or
Failed: <reason> (exit code 1):
| What the device has | What the script does |
|---|---|
| No agent | Installs as above (MSI; the portable ZIP in Windows PE or with &type=zip) |
| A healthy agent, as new as the server's package or newer, enrolled with this server | Nothing |
| An older agent | Upgrades in place (the MSI as a major upgrade; Linux/macOS lay the files down again); the enrollment is kept |
| Service missing, disabled, stopped or crash-looping; watchdog not running | Restarts it through the agent's own initialize (re-registers the service as Automatic, starts agent and watchdog); if that does not help, installs the package again |
| Agent binary missing or not running; Windows Installer registration or its cached package gone | Installs the package again: the same MSI build as a repair (REINSTALL=ALL REINSTALLMODE=vamus, re-caching it; a lost cache is first restored from the MSI the agent keeps under %ProgramData%\ExecuteR\packages), another build as an upgrade, every file laid down (amus). Only when Windows Installer refuses that does it uninstall and install again, with %ProgramData%\ExecuteR and HKLM\SOFTWARE\ExecuteR set aside and put back, so the enrollment and settings survive. Linux/macOS move the files in one by one and register the unit / daemon again |
| No usable credential (missing, unreadable, of other hardware), or pointed at another server | Hands the agent this command's bootstrap token and restarts it. A valid enrollment is never replaced, so the device keeps its identity; re-enrolling the same hardware keeps the same device row anyway |
The decision reads executer-agent status / ExecuteR-Agent.exe status,
whose first line is JSON: service state, version, server URL, credential
(valid, missing, unreadable, other-device; an expired credential is
still valid, it renews itself) and whether a bootstrap token is pending —
never the token. Health means the service is registered, enabled and still
running a few seconds later, the watchdog runs, the credential is valid and
the server URL matches (case and a trailing slash aside; a Group Policy
ServerURL pointing elsewhere is a failure, not something the script
overrides). The script embeds the version the package link serves, so a
current device downloads nothing. Interrupted runs do not break a rerun: one
setup runs at a time (a global mutex on Windows, a lock directory on
Linux/macOS), leftover downloads and half-moved files are cleared, a Windows
Installer operation in progress is waited for, and data set aside by an
interrupted last-resort reinstall is put back first. The token goes only to
msiexec's hidden BOOTSTRAPTOKEN, the agent's registry / agent.json, or
configure --token; it is masked out of failure messages.
Windows PE
The agent runs in Windows PE, so a device is reachable before it is imaged —
and it stays the same device afterwards. Its identity is derived from the
hardware (SMBIOS UUID, BIOS/baseboard serials, make and model), never from the
OS, so the installed OS enrolls into the same device row. In WinPE the OS reads
Windows PE (with the real build version, shown as a WinPE chip) and the
hostname is WinPE's random MINWINPC-…; when the installed OS enrolls, both
update and the transition is kept in the device's Device History.
Boot image prerequisites (optional components added with Dism /Add-Package):
| Component | Why |
|---|---|
WinPE-WMI |
Required. Hardware identity and inventory come from WMI; without it the agent logs WMI is unavailable … add the WinPE-WMI optional component and cannot enroll. |
WinPE-PowerShell (brings WinPE-NetFx and WinPE-Scripting) |
The PowerShell install one-liner, and the powershell.exe script engine. |
WinPE-NetFx alone |
Not needed — the agent is self-contained .NET. |
Scripts from the console run in the agent's embedded PowerShell either way. In
the remote shell, Built-In PowerShell (the agent's own PowerShell host)
gives a PowerShell prompt without WinPE-PowerShell, and Command Prompt
(cmd.exe) is always there; Automatic picks the first of PowerShell 7,
Windows PowerShell, Built-In PowerShell and Command Prompt that the device has.
WinPE runs from a RAM drive (X:) whose default scratch space (32 MB) is too
small for the agent — raise it on the image, and keep the default wpeinit
so networking is up:
Dism /Image:C:\WinPE_amd64\mount /Set-ScratchSpace:512
One-liner. The Windows command from Add device works as-is in WinPE
(paste it at the WinPE command prompt; it starts powershell.exe). The script
detects WinPE (HKLM\SYSTEM\CurrentControlSet\Control\MiniNT), takes the
portable ZIP instead of the MSI (Windows Installer does not run in WinPE),
unpacks to X:\Program Files\ExecuteR\Agent with .NET's ZipFile (no
Expand-Archive/CIM cmdlets needed) and registers and starts the Windows
service through ExecuteR-Agent.exe initialize — the Service Control Manager
APIs, not sc.exe. Everything lives on X: and is gone at the next reboot,
by design.
startnet.cmd alternative — no PowerShell needed: copy the portable ZIP's
contents into the mounted image (e.g. <mount>\ExecuteR) and run the agent in
the foreground from Windows\System32\startnet.cmd. Environment variables are
honored in foreground only (a service reads the registry):
wpeinit
set AGENT_SERVER_URL=https://control.example.com
set AGENT_BOOTSTRAP_TOKEN=<token>
start "ExecuteR Agent" X:\ExecuteR\ExecuteR-Agent.exe foreground
To run it as a service there instead, use
X:\ExecuteR\ExecuteR-Agent.exe configure --url <server> --token <token> followed
by X:\ExecuteR\ExecuteR-Agent.exe initialize.
The token after imaging. The installed OS enrolls through its own install
(the MSI or one-liner in the task sequence / SetupComplete.cmd). Re-enrolling
the same device with the token that enrolled it spends no further use, so one
token can cover both phases — but it must still be valid (not expired or
revoked) when the installed OS enrolls. Give it an expiry longer than imaging
takes, and use a multi-use token for a batch of devices.
History. The device page's Device History tab lists Enrolled
(with the name and OS it enrolled as), Renamed (MINWINPC-ABC → LAB-PC-01)
and OS Changed (Windows PE 10.0.26100 → Windows 11 10.0.26100.4351),
newest first; the same trail is GET /api/devices/{clientId}/history
(devices.view, device scope applies). Events are written only when a value
actually changes; each enrollment's audit entry also records hostname and OS.
On-enrollment triggers fire once per device per trigger — so one aimed at
all devices fires at the WinPE enrollment and not again after imaging. Aim it
at a dynamic group with OS name not equals Windows PE to run it in the
installed OS (enrolling a new OS drops the WinPE inventory, so the group sees
the new OS straight away), or equals Windows PE for a pre-imaging step.
Sign-in
Sign-in works as it does in StifleR. There are four methods, each a tab under Settings › Authentication, and several can be on at once:
| Method | What it checks | Groups that bind to roles |
|---|---|---|
| Built-In | ExecuteR's own accounts (PBKDF2-SHA512, at least 12 characters, changed at first sign-in) | Built-in groups |
| Local Windows Accounts | This server's own Windows accounts, checked by Windows (LogonUser); Windows servers only, on by default on Windows Server |
The account's SID and its local groups' SIDs (for example BUILTIN\Administrators) |
| LDAP | A directory or Active Directory: LDAPS, StartTLS, or Kerberos (signed and sealed); user and group filters, nested groups | Group DNs |
| OIDC | Any OpenID Connect provider (authorization code with PKCE); ID token validated; sign-out at the provider | claim=value, for example groups=executer-admins |
The sign-in page offers the built-in form (one form for built-in and local Windows accounts, with an Account Type toggle when the directory is on too) and a Sign In with {provider} button. With Redirect Mode on and OIDC the only way in, it goes straight to the provider, except after an error or a sign-out.
Access comes from groups, never from the person. A role binding names a group (built-in group, Windows SID, directory DN or OIDC claim) and one of ExecuteR's roles. Someone in several bound groups gets all their roles: permissions add up, and so do device scopes (a role with no scope reaches every device). A person whose groups are bound to nothing is refused at sign-in. Each method's tab has its own bindings card.
Sessions are database rows behind an HTTP-only __Host-session cookie.
They end on sign-out at once, on every node. They slide with use up to an
absolute limit (Built-In tab: idle 120 minutes, at most 12 hours by default),
and carry a CSRF token checked on every write.
Safety rails:
- Failed sign-ins back off per account and per address (from 30 seconds, doubling to 15 minutes). Nothing is locked for good.
- Turning a method on or off asks you to confirm it is you (step-up: your password, or your provider again).
- The last method on cannot be turned off.
- Leaving only LDAP, OIDC or Windows on needs a passed Test sign-in through it in this session, with its settings as they are.
- Secrets (the LDAP service password, the OIDC client secret) are write-only and encrypted at rest.
- On a domain-joined Windows server, LDAP sets itself up from the join (Kerberos, the computer account) until you change its settings. A breaker turns it off after repeated directory failures.
Break-glass account. One built-in account always has full access through
no binding, and cannot be turned off or removed. On an empty database it is
created from INITIAL_ADMIN_USERNAME / INITIAL_ADMIN_PASSWORD. Without
a password, it gets a generated one-time password recorded in
<data>/initial-admin-password.txt for administrators only (the log says
where, never what), changed at the first sign-in.
Lockout recovery (an identity-provider outage is never terminal):
AUTH_FORCE_LOCAL=1(environment only) always offers the built-in form.ExecuteR-Server reset-admin(dotnet Backend.dll reset-adminin a container;auth-resetis the same verb) turns Built-In sign-in back on, turns redirect off, turns the account back on, and prints a new one-time password for the break-glass account. Add--user <name>for another built-in account,--password <pw>to choose it.
Upgrading from an earlier ExecuteR happens once, at the first start:
- Each user's role becomes membership of a built-in group named after the role, bound to it.
- The old OIDC settings (saved, or
OIDC_*/AUTH_LOGIN_MODEin the environment) become the OIDC tab. - Roles' claim values and the Admin/Operator/Viewer mappings become
claim=valuebindings. - The old default role has no equivalent. Bind the claim your people carry instead.
Displayed URLs (the OIDC callback <public-url>/api/auth/oidc/callback, its
post-logout <public-url>/sign-in, install commands) use PUBLIC_SERVER_URL
when set, otherwise trusted forwarded headers.
Custom roles and permissions
Access (nav) manages roles and shows people. A role is a named permission set (devices, groups, scripts, functions, jobs, automation, secrets, remote shell, device files, device registry, Remote View, file delivery, settings, access), optionally limited to a device scope. Pick device groups, and holders only see and target those devices: device listing, job dispatch including group fan-out, shell, device files, the registry editor, file delivery, inventory refresh and tags all honor it.
Three system roles are seeded and immutable:
- Admin:
*, which includes future permissions. - Operator: day-to-day operations.
- Viewer: read-only.
Being immutable, each one follows its version: on upgrade it takes what that version grants, so Operator picks up new permissions by itself.
People get roles only through role bindings on their groups (see Sign-in). People lists everyone who has signed in, of every kind, and what they hold and where each grant came from.
Permission and binding edits apply within seconds without signing in again: roles and bindings resolve through short caches on every request.
Safety rails:
- System roles cannot be edited.
- A role still bound cannot be deleted.
- Removing the last binding that manages access is refused while there is no break-glass account to recover with.
Typed script parameters and Functions
Scripts can declare typed parameters whose editor input changes by type:
string, number, boolean, array (with element type), and hashtable. Hashtable
entries are typed per entry — every key and value picks its own primitive
(string/number/boolean) as you add it, carried as native JSON and rebuilt by
the agent, so @{ Name = 'x'; 42 = $true; Retries = 3 } arrives exactly
typed. Values bind with AddParameter, so PowerShell receives real [int],
[bool], [string[]], and [hashtable] values. The builder sits in a
full-width strip above the editor (toggle Define); run-time values stay in
the side panel next to the target.
String values expand on the target device automatically — %TEMP%,
$env:COMPUTERNAME and $(…) resolve with the device's environment
(ExpandEnvironmentVariables, then ExpandString in the job's runspace)
before the script runs. Mark a parameter Literal in the builder to opt out
and pass the raw text through exactly as typed (regex patterns, literal $).
Expansion applies to string scalars, string array elements and hashtable
values — hashtable keys stay literal.
Reusable Functions can be attached to a script; the backend prepends them as a prelude executed first in the same runspace, so individual scripts stay small and duplication is avoided.
Scripts, Functions and Sequences (like the Vault) live in folders: a tree on the
left, a breadcrumb over the open folder, and the folder in the URL
(?folder=/a/b) so links, reload and Back land in the same place. Folders
compare ignoring case and keep their first casing; empty folders stay until
deleted, and a folder can only be deleted once empty. Drag scripts, functions
or folders onto a folder in the tree to move them (or use Move to
Folder…); new items are created in the open folder. Viewing folders takes
the library's View permission, changing them its Manage permission.
Scripts, Functions, schedules, groups (rules and static members included) and roles all support one-click Clone — the copy lands as "Name (copy)" ready to edit. Role clones copy permissions and device scope but never OIDC claim values, so identity mappings stay unambiguous; system roles clone into custom roles, making Admin/Operator/Viewer handy templates.
Snippets
Snippets (under Automation) is a shared library of code to insert: about
fifty built-in snippets ship with the server (try/catch logging, registry,
services, event logs, disk space, installed software, pending restart,
downloads, retries, certificates, local admins, systemctl, journalctl,
apt/dnf, and ExecuteR's own exit 3010, $Secrets, $Files,
$ExecuteRJobDir and $Trigger), and operators add their own (View Scripts
to read, Manage Scripts to change; changes are audited under Scripts).
Built-ins cannot be changed; Copy to Edit makes one your own.
In the script and function editors, snippets for the editor's language appear
in completions and under Snippets in the editor's toolbar, inserting at
the cursor. On a remote shell, Snippets types one at the prompt with its
tab stops filled in and no Enter. A snippet's tab stops are ${1:default},
${1} (the same text again), ${1|a,b|} (a choice) and ${0} (where the
cursor ends); everything else is code as written, Bash's ${1:-default}
included. The API is /api/snippets (GET, POST), /api/snippets/{id}
(GET, PUT, DELETE) and /api/snippets/{id}/copy (POST).
Script engines
Each script picks its Script Engine in the editor — the selector shows a one-line hint describing the selected engine's platform behavior, and Monaco switches syntax highlighting to match:
- PowerShell 7 (default) — the embedded PowerShell SDK in the agent
process on every platform. Full feature set: live progress records, typed
parameters,
$Secrets, Functions preludes. - PowerShell 5 — shells out to
powershell.exeon Windows with near parity: a generated wrapper renders parameters as typed PowerShell literals (hashtables and arrays included), defines the case-insensitive secrets dictionary, dot-sources the prelude and splats the script file. Stdout/stderr stream live; progress records are the accepted limitation. - Bash — for Linux/macOS devices (or Windows with Git Bash). Parameters
and secrets arrive as environment variables; complex values are JSON
strings (
jqfriendly). The prelude is sourced first throughBASH_ENV(and unsets it), so the script file holds only the script.
An engine unavailable on a device (PowerShell 5 on Linux, bash without Git Bash on Windows) fails the job immediately with a clear message instead of running.
Where scripts run
Every job gets its own job folder, whatever the engine:
<JobRoot>\<JobId>\ e.g. C:\Windows\SystemTemp\ExecuteR\3f2c…\
Install-Baseline.ps1 the script, named after it (staged runs)
.executer-wrapper.ps1 PowerShell 5 only: parameters and secrets
.executer-prelude.ps1 / .sh attached Functions (PowerShell 5, Bash)
- Root. By default the agent's own temp folder +
ExecuteR: .NET'sPath.GetTempPath()as the agent's account, which for LocalSystem on current Windows isC:\Windows\SystemTemp\ExecuteR(older builds without SystemTemp:C:\Windows\Temp\ExecuteR);$TMPDIR/ExecuteRor/tmp/ExecuteRon linux/macOS.JobRoot(GPO > Agent Settings profile > registry > default; MSIJOBROOT;agent.jsonon linux/macOS) replaces it. Environment variables expand in the agent's context:%VAR%on Windows (%TEMP%is the service's temp,C:\Windows\TEMP, not a user's),$VAR/${VAR}elsewhere. The value must be an absolute local path: UNC paths, network drives, anything under the user profiles folder (C:\Users,/home,/Users) and folders whose parent non-administrators could rename, delete or re-permission are refused. A refused value is logged as a warning and the default applies; it never fails a job. The device page shows the effective root (Agent › Job Folder, with where it came from on hover). - Locked down. Root and job folders are SYSTEM and Administrators only, inheritance off (0700 and root-owned on linux/macOS), because the PowerShell 5 wrapper holds the job's secrets. A root that is a link or junction, or that someone else owns, is refused.
- Cleanup. The helper files (
.executer-*) are deleted after every run. With Clean Up After Run (default on) the whole job folder goes too; off, it stays for inspection. Job folders older than 7 days are swept when the agent starts.
Per-script options in the editor (Details):
| Option | Default | What it does |
|---|---|---|
| Run From File | off | PowerShell 7 stages the script in the job folder and runs it by path (AddCommand), not from memory. PowerShell 5 and Bash always run from a file. |
| Set Working Directory to Script Folder | off | Starts a staged script in its job folder (the process's directory for 5.1 and Bash; the runspace's location for PowerShell 7, never the shared agent process's). Only with a staged file. Off keeps the engine's usual directory: the agent's own (C:\Windows\System32 for the service), or the user's profile folder or home with Run As Signed-In User. |
| Run As | Agent Account | Each Signed-In User runs the script once per signed-in user, one after another, each run as described below, under one timeout. The output marks each user's part, and the job fails if any run fails, naming those users. Nobody signed in: nothing runs and the job succeeds. Needs agent 1.14.0 or later; the server fails the job for older agents. Signed-In User: below. |
| Run As Signed-In User | off | Runs the script as the person signed in on the device (the console's user, else the only one signed in) instead of the agent's account. Every engine runs out of process: PowerShell 7 in the agent's built-in host, 5.1 in powershell.exe, Bash in bash (through su on Linux and macOS), with output and errors but no progress records. Windows uses the user's token, environment (plus the bundled modules) and profile folder, headless, so nothing appears on their screen. The user is given that job folder only (Windows: Modify on it; Linux/macOS: it becomes theirs and the job root traverse-only). Nobody signed in, or several and nobody at the console, fails the job; so does an agent older than 1.13.0, which the server never sends it to. |
| Clean Up After Run | on | Deletes the job folder when the run ends. |
| Restart After Run | Off | Restarts the device after the run: Always, or When the Script Asks, with an optional delay (up to 60 minutes) and an optional warning for signed-in users. See Restart After Run. |
What a script sees of itself:
| Engine / mode | $PSScriptRoot |
$PSCommandPath |
$MyInvocation.MyCommand.Definition |
|---|---|---|---|
| PowerShell 7, from memory | empty | empty | the script text |
| PowerShell 7, Run From File | the job folder | …\Install-Baseline.ps1 |
…\Install-Baseline.ps1 |
| PowerShell 5 | the job folder | …\Install-Baseline.ps1 |
…\Install-Baseline.ps1 |
| Bash | $0 and ${BASH_SOURCE[0]} are …/Install-Baseline.sh |
Parameters, $Secrets, $Files, Functions, exit codes, output formatting,
progress and cancellation behave the same from a file as from memory. In
PowerShell 7 from a file, exit N reaches the job exactly as with
pwsh -File (exit codes of scripts it calls stay inside them), and the
main script's variables live in its script scope rather than the global one.
Running from a file is subject to execution policy: the agent sets
Bypass for its runspace, but a Group Policy execution policy
(MachinePolicy/UserPolicy) overrides that; under AllSigned an unsigned
staged script fails to load, where the in-memory mode is not checked.
The job folder in every mode. $ExecuteRJobDir (both PowerShell engines,
every mode, in-memory included) and the EXECUTER_JOB_DIR environment
variable (PowerShell 5 and Bash) hold the job folder, so a script can write
beside the job even when it runs from memory. PowerShell 7 runs inside the
agent process, which concurrent jobs share, so it has no per-job
EXECUTER_JOB_DIR; use $ExecuteRJobDir.
# A transcript beside the job (kept when Clean Up After Run is off).
Start-Transcript -Path (Join-Path $ExecuteRJobDir 'transcript.log')
try {
# ... the work ...
} finally {
Stop-Transcript
}
# With Run From File: a file next to the script itself.
Set-Content -Path (Join-Path $PSScriptRoot 'state.json') -Value (@{ ran = Get-Date } | ConvertTo-Json)
Where the agent is. $ExecuteRAgentDir (the agent's folder) and
$ExecuteRAgentPath (the agent executable's full path) are set in both
PowerShell engines, every mode; PowerShell 5 and Bash also get them as the
EXECUTER_AGENT_DIR and EXECUTER_AGENT_PATH environment variables.
PowerShell 7 runs inside the agent process, whose environment every job
shares, so it has the variables only. They name the running agent wherever it
was installed: the MSI's C:\Program Files\ExecuteR\Agent, a portable zip
unpacked anywhere, Windows PE's X: drive, /opt/executer/agent on Linux
and macOS (the /usr/local/bin/executer-agent link resolved to the real
file). Use them to call the agent from a script, for example to send what a
job collected up to S3 (Device uploads to S3):
# PowerShell (either engine): gather, then archive the folder under a named folder in S3.
Copy-Item "$env:WINDIR\Logs\CBS\*.log" $ExecuteRJobDir
& $ExecuteRAgentPath upload (Join-Path $ExecuteRJobDir '*.log') --zip cbs-logs.zip --dest "case-$($env:COMPUTERNAME)" --quiet
if ($LASTEXITCODE -ne 0) { Write-Warning "Upload exit code $LASTEXITCODE" }
# Bash: the app's logs, with their folders kept.
"$EXECUTER_AGENT_PATH" upload '/var/log/myapp/*.log' --recurse --quiet
Output reads the way PowerShell shows it. Both PowerShell engines pipe
the script's output through Out-String -Stream at a 4096-column width, so
objects arrive as their table or list view (a hashtable's Name/Value rows,
an object's properties as columns) rather than a type name such as
System.Collections.Hashtable, still streamed line by line and without
… truncation. Strings pass through unchanged.
Exit codes. A PowerShell 7 script reports what pwsh -File would: exit N
is exit code N and Failed when N is not 0, exit 0 succeeds even after errors,
and a terminating error is exit 1. A native command's non-zero $LASTEXITCODE
only counts if the script exits with it (exit $LASTEXITCODE), and errors the
script silenced do not fail it. One difference, kept on purpose: anything on the
error stream (Write-Error, a failing cmdlet) fails a script that never calls
exit, with exit code 1.
Changed behaviour: agents before this version reported
exit 5as Succeeded with exit code 0, and failed any script whose native command ended non-zero or that silenced an error with-ErrorAction SilentlyContinue. A script relying on either now reports differently.
A failed job also records its first error's exception type, error id and message (for Windows PowerShell and Bash, the first stderr line). For jobs from older agents the run's error groups use the summary or the first error line of the output.
Downloads. A job's output drawer downloads its complete stored output as
COMPUTERNAME.JobID.yyyy.MM.dd.HHmmss.log (optionally with timestamps), and
a run (Jobs › run, or a script's Executions tab) downloads every target's
output in one ScriptName.RunID.yyyy.MM.dd.HHmmss.log with a section per
device and its state and exit code. The time is when the job or run was
created, in UTC on a 24-hour clock. Non-output streams are tagged
([ERROR], [WARNING], …). Endpoints: GET /api/jobs/{jobId}/output/download
and GET /api/executions/{runId}/output/download (?timestamps=true);
device-scoped roles only reach their own devices' output.
Bulk log downloads. On a run, check devices and Download Logs (or
Download All Logs with none checked) saves ScriptName.RunID.yyyy.MM.dd.HHmmss.zip
holding one COMPUTERNAME.JobID.yyyy.MM.dd.HHmmss.log per device, the same
file its drawer downloads. Skipped targets have no log. Endpoint:
POST /api/executions/{runId}/output/archive with { "jobIds": [...], "timestamps": false }
(no jobIds = every job); the zip streams as it is written.
The code editor is meant to feel like VS Code (offline, no language server):
- Highlighting after VS Code's Dark/Light Modern themes: cmdlets,
-Parameters, word operators, types and attributes, and variables and$( … )inside double-quoted and here-strings. - IntelliSense (toggle per browser) that follows the context. After
-it offers the command's parameters (cmdlets, functions in the script and functions in attached modules) or operators after a value. After$it offers variables the script declares, its parameters,$Secretsand$Files. After$Secrets.,$Files.,$env:and[it offers bound names, environment variables and types. It also includes snippets. - Hover cards with syntax and synopsis for cmdlets and functions
(comment-based
.SYNOPSIS), and where a variable is declared. - Navigation: go to symbol (Ctrl+Shift+O), sticky scroll, go to definition (F12), find references (Shift+F12), rename (F2), matching highlights and bracket pair colours.
- Problems: squiggles for unbalanced brackets and for
$Secrets.X/$Files.Xnames not bound to the script (F8 steps through them). - Against the saved version: change bars in the gutter, and Compare with Saved (Ctrl+K D) as a side-by-side diff with per-change revert.
- Status bar: position and selection, problems, the function you're in, indentation (spaces or tabs, convert), LF/CRLF, the command palette (F1), and toggles for word wrap (Alt+Z), sticky scroll and the minimap (remembered per browser).
It also fills the window (Esc restores). The editor is organized in tabs — Code, Parameters, Functions, Secrets, Files, Executions (runs → targets → output) and Schedules — and Run… / Schedule… open the shared run-now and schedule dialogs.
Running a script works the same way from a script and from devices. The Run Script dialog has tabs:
- Script: searchable. It's fixed when you open the dialog from a script.
- Devices: search, a status filter and multi-select, with Choose Results to pick everything the search found. Devices you chose on the Devices page come preselected.
- Groups: the group tree with checkboxes.
- Parameters
- Review: reach (online, offline, orphaned) and Only Devices Online Now.
Starting a run opens its page (/runs/{runId}):
- one progress bar over every target;
- counters for Targets, Online, Pending, Running, Succeeded, Failed and Skipped, each of which filters the target list;
- every target, skipped devices included; a row opens that device's output.
Jobs opens on Runs: recent runs across scripts, each with its progress and source (Run Now, Schedule or Event Trigger). The Jobs tab keeps the per-device job history.
The packaged agent bundles PSResourceGet, Archive and ThreadJob
next to the binary and prepends that directory to PSModulePath — so
Install-PSResource (the modern PSGallery client, no NuGet-provider
bootstrap), Compress-Archive and Start-ThreadJob work on every endpoint
regardless of what is installed there, in the embedded engine and in 5.1
alike. Modules installed with Install-PSResource -Scope AllUsers land on
the standard module path and resolve in subsequent jobs.
Restart After Run
A script option (editor, Details) that Run Script can override for one run, and a sequence step for its own run (Restart On Completion). It is stored and versioned like the other run options: a run's snapshot keeps the value it started with, and the script command carries it to the agent.
| Option | Restarts the device |
|---|---|
| Off (default) | never |
| Always | after every run that ends: succeeded, failed or timed out (never a cancelled one) |
| When the Script Asks | when the script exits 3010 (ERROR_SUCCESS_REBOOT_REQUIRED) or 1641 (ERROR_SUCCESS_REBOOT_INITIATED); on linux and macOS also 194 |
194 is what exit 3010 becomes in an 8-bit exit status (3010 mod 256), so
a Bash script written for both systems asks the same way; it lies above every
signal status (128 + 64) and below the shell's 255, so no crash produces it.
PowerShell 7 runs in the agent's process and returns 3010 itself on every system.
With Restart After Run on, an asking exit counts as Succeeded, as Windows
Installer means it.
| Setting | Default | |
|---|---|---|
| Delay | 0 | 0 to 60 minutes. The agent holds it (not the system): the console can cancel the restart meanwhile, and nobody on the device is notified. |
| Warn Signed-In Users | Off | When on (60 s when turned on; 15 seconds to 10 minutes), and someone is signed in when the delay ends, the system restart notice runs that long first. Off, or nobody signed in: the restart is immediate. |
Mode, delay and warning are one record (RestartSettings), the same for a
script, a run's override (CreateJobRequest.RestartWarningSeconds with the
other two) and a sequence step's Restart On Completion. Scripts that existed
before the warning have it off.
Order of events.
- The run ends; its final state says Restart Requested (or Restart
Refused when
AllowRestartis off, and nothing restarts). - The agent keeps the job's result (final state and output lines) in its local store, then asks the server to confirm it holds them (a request on the device's event subject, sealed like the rest). The server applies the final state from the request if its JetStream copy has not arrived, waits for every output line the job published, then answers; lines it still lacks are sent again.
- With a delay: confirmed, the job shows Restart at time, with a countdown and, for whoever may run jobs (Run Jobs), Cancel Restart (the ✕ on the chip). The due time goes into the agent's local store before the wait, so an agent or service restart during the delay carries on: a due time in the past restarts at once; a boot time newer than the request means the device restarted some other way, and the job shows Restarted. Unreachable after three tries, the agent holds the delay anyway, the result kept here.
- When the delay ends, the agent reads
AllowRestartagain (profiles and GPO included; off: Restart Refused), then asks the server once more (15 seconds at most; still unconfirmed results get three tries). The server answers cancelled for a restart cancelled from the console, so a cancel whose command has not reached the device still stops it. - The job shows Restarting and the agent asks the platform to restart: with the warning as the system's grace period when it is on and someone is signed in, at once otherwise. Unreachable, the agent restarts anyway: the kept result is sent after the restart, before anything else. (In Windows PE nothing local survives a restart, so the agent keeps trying for 10 minutes first.)
- Back from the restart, the device's inventory carries a newer boot time: the job shows Restarted with it. The agent also reports it, along with the result it kept, if any.
- Still up 3 minutes after the warning (after the call, without one), the restart was
cancelled on the device (
shutdown /a,shutdown -c): Restart Cancelled. Restart Failed says why the platform refused.
Cancel Restart (POST /api/jobs/{jobId}/restart/cancel, Run Jobs, within
the caller's device scope) works while the job is Scheduled: the job shows
Restart Cancelled at once, the cancel is audited with who did it, and a durable
command (agent.<id>.command.restart, sealed like the rest) tells the agent to stop
holding the delay. Once the restart is with the system (Restarting) it answers
409: during the warning only shutdown /a / shutdown -c on the device stops it.
Who counts as signed in. Windows: WTSEnumerateSessions sessions that are
Active or Disconnected (a disconnected user's programs and unsaved work are
still there, and they may reconnect during the warning) and have a user; session
0 never counts. Linux: logind ListSessions, each session's properties read
(org.freedesktop.DBus.Properties.GetAll); class user (or user-early) not
closing counts, local or ssh. When sessions cannot be read, the warning is given.
Windows PE has no user sessions: always immediate.
Older agents ignore the warning and the cancel command: they still hand the whole delay to the system as its grace period (the system's notice for the whole delay; the job shows Restarting meanwhile, never Scheduled, so the console offers no cancel).
Each step is audited (jobs category: restart-scheduled, restart-restarting,
restart-restarted, restart-refused, restart-cancelled, restart-failed).
The agent keeps a restart in its local store until the server has heard how it
ended; a future step can record what to do next there (Continuation), and the
agent picks it up once the device is back.
How each platform restarts (never shutdown.exe, Restart-Computer, a
shell, systemctl or a bare reboot(2)):
| Platform | Mechanism |
|---|---|
| Windows | InitiateShutdownW with SHUTDOWN_RESTART | SHUTDOWN_FORCE_OTHERS, the warning (or 0) as its grace period with the message, and a planned Application: Installation reason (SHTDN_REASON_MAJOR_APPLICATION | SHTDN_REASON_MINOR_INSTALLATION | SHTDN_REASON_FLAG_PLANNED), after enabling SeShutdownPrivilege (AdjustTokenPrivileges). During the warning a signed-in user sees the Windows restart notice and can cancel it with shutdown /a; the job then shows Restart Cancelled. A shutdown already under way or scheduled counts as taken. |
| Windows PE | The same API first, grace 0. PE has no shutdown service of its own, so when the call fails, or the machine is still up a minute later, the agent runs %SystemRoot%\System32\wpeutil.exe reboot (Microsoft's PE restart; started directly, no shell, exit code checked, output logged). |
| Linux | systemd-logind over the system bus (Tmds.DBus.Protocol): org.freedesktop.login1.Manager.Reboot(false), or with the warning SetWallMessage(message, true) then ScheduleShutdown("reboot", now + warning), which warns signed-in terminals and shutdown -c cancels. Without logind, org.freedesktop.systemd1.Manager.StartUnit("reboot.target", "replace-irreversibly") after the warning. Either way systemd stops every unit first. |
| macOS | Not supported: no API a root launchd daemon may use for a clean restart. The job shows Restart Failed with the reason. |
AllowRestart (REG_DWORD, default on; GPO > Agent Settings profile >
registry or agent.json > default; MSI property ALLOWRESTART; ADMX
Allow Restart After Run). Off, a requested restart is refused and the job says
so; it is read when the run ends and again when a delay ends.
Restart and Shut Down
Restart… and Shut Down… in a device's menu, a selection's Actions and
a group's menu (permission devices.power: Admin, Operator, Help Desk) start
one run of a built-in script that does nothing but end, with Restart After Run
set to Always. So it is a run like any other (POST /api/power, audited as
jobs/restart or jobs/shut-down), with:
| Option | Default | |
|---|---|---|
| Exclude | none | Devices and groups left out, as a script's run. |
| Delay | 0 | Up to 60 minutes after each device's job; the job's chip cancels it meanwhile. |
| Warn Signed-In Users | Off | The system's own notice, 15 s to 10 min, when someone is signed in. |
| Install Pending Updates | Off | Windows: SHUTDOWN_INSTALL_UPDATES is passed only when on, so updates waiting for Update and restart / Update and shut down stay waiting. An update Windows has already part-installed still finishes on any restart; that is servicing, not a choice. |
| Only Devices Online Now | On | Off: an offline device restarts (or shuts down) as soon as it reconnects. |
| Stagger | Off | Spreads the devices over up to 24 hours, in batches, as a script's run. |
Shutting down is SHUTDOWN_POWEROFF on Windows (a full shutdown, never Fast
Startup's hybrid one; wpeutil shutdown on Windows PE) and logind's PowerOff
/ ScheduleShutdown("poweroff", …) on Linux (poweroff.target without logind).
Console-ordered actions give Windows a planned Other: Maintenance reason.
AllowRestart off refuses both. Shutting down and installing updates need agent
1.14.0 or later: an older agent would restart instead (and skip the
updates), so its job fails with the reason; a plain restart goes to any agent.
A shut-down device's job reads Back On once it is switched on again.
Sequences
A sequence (nav: Sequences, under Functions) is an ordered list of steps, each an existing script with its own settings. It runs on a device one step at a time, and it carries on across restarts: a step restarts the device, and once the device is back the next step runs. No script resumes part way; the next script starts. The server holds the sequence's state, so nothing that must survive lives on the device, and it works the same in Windows PE (whose RAM drive is gone after a restart).
Folders. Sequences live in folders of their own, exactly like
scripts and functions: tree, breadcrumb, ?folder=,
drag or Move to Folder… (several at once), delete only once empty, and the
same path rules. Run… and the schedule editor show each sequence's folder.
Existing sequences start at the top (/). Moving or renaming never touches a
run under way. API: GET/POST/DELETE /api/sequences/folders,
POST /api/sequences/folders/move, POST /api/sequences/move, and folder
on POST/PUT /api/sequences (omitted on update: stays put).
Each step has:
| Setting | Default | What it does |
|---|---|---|
| Script | Any script; its parameters get the step's own values (the Run Script inputs). | |
| Functions | none | Added to the script's own (prepended in order, once each). |
| Enabled | on | A disabled step is Skipped. |
| Condition | none | Run only if every part set holds: the previous step's outcome (Success, Warning, Failure: the last step that ran; Success before any), the platform (windows, linux, macos), Full OS or Windows PE, and in any of / not in groups (nested included). Read when the step comes up, so a step after a restart sees the OS the device came back in. Unmet: Skipped. |
| Restart On Completion | Off (prefilled from the script) | Off, Always, or When the Script Asks (3010, 1641; 194 on linux/macOS), with a delay and Warn Signed-In Users: Restart After Run for this step, over the script's own. The next step waits until the device is back. |
| Continue On Error | off | A Failure goes on to the next step instead of ending the sequence Failed. |
| Exit codes | Success 0, Warning 3010, 1641, Failure * |
Lists of codes and ranges (0, 3010, 2000-2099, hex 0x80070005, negatives -5--1); * is every code no list names, in one list at most; no code in two lists; with no *, an unlisted code is a Failure. On linux/macOS 194 counts as 3010 unless listed. Checked when saving. |
| Files | the script's | Own S3 downloads (the script Files model: selection, Download To, Clean Up Downloads) in place of the script's. |
The outcome comes from the exit code, not the job's state: exit 3010 with
no restart fails the job on the device and is a Warning here. A timed-out or
cancelled job is a Failure. A restart that did not happen (refused by
AllowRestart, cancelled on the device, failed) makes the step a Failure, and
so does a device not back within 24 hours.
A device's run ends Succeeded (every step that ran succeeded), Warning (it reached the end with a Warning or a Failure it continued past), Failed or Cancelled.
Where it runs. Everywhere a script does: Run… (POST /api/jobs with
sequenceId; targets, exclusions, device scope, Only Devices Online Now and the
stagger of each device's first step as for a script), schedules (sequenceId
on POST/PUT /api/triggers; every trigger type, Include/Exclude targeting; no
arguments: the steps carry them), event triggers (an At Logon delay holds the
first step) and On Demand with the device CLI (ExecuteR-Agent run <name|id>;
--param is refused, and --wait returns at once: a sequence outlives the
process). Every step job sees the trigger that started the sequence in
$Trigger.
How it runs. Server-side. A start records the sequence run, one ordinary
run per step holding that step's sealed snapshot (the script as it is now,
the prelude, the step's arguments, files and restart), and each device's run
with its first step's job. Every step is a normal job: the dispatcher sends it
(secrets and presigned URLs resolved at send time, never stored), an offline
device gets it when it reconnects, and job history, output, run pages,
dashboards and the audit treat it like any job. A worker on the
SCHEDULE_WORKER node looks every 2 seconds for devices whose step has a final
state, classifies it, waits while a restart is under way (until the job is
Restarted, or the device's inventory carries a newer boot time), checks the
next step's condition and queues it. Each move is one conditional update with
the next job in the same transaction, so a final state delivered twice, two
workers or a cancel at the same moment advance a device once.
Edits and deletes. A run uses the steps and scripts as they were when it started; editing the sequence or a script affects the next run. A script deleted mid-run fails the step that would run it. Deleting a sequence leaves runs under way to finish; its schedules disable themselves when they fire.
Watching and cancelling. The run page (/sequence-runs/{id}, from Run…,
Jobs › Sequences, and the "Sequence · step N of M" chip on step runs and jobs)
shows each device's step N of M and every step's state (Pending, Running,
Restarting, Succeeded, Warning, Failed, Skipped, Cancelled), with Waiting for
Device when the step's job is not yet delivered to an offline device. Cancel
(POST /api/sequence-runs/{id}/cancel, optional clientIds) ends the run on
its devices in the caller's scope and cancels a step job not yet sent; a step
already on the device runs to its end (jobs have no remote stop), and nothing
after it runs. GET /api/sequence-runs and GET /api/sequence-runs/{id} list
and detail runs within the caller's device scope.
Permissions and audit. Sequences follow scripts: Scripts View to read,
Manage Scripts to create, edit, delete and file them (scripts category:
sequence-created, sequence-updated, sequence-deleted,
sequence-folder-created, sequence-folder-moved, sequence-folder-deleted,
sequence-moved); Run Jobs to run
and cancel (jobs: sequence-run, sequence-cancel), View Jobs for runs;
schedules as before (automation). Sequence runs are kept as long as their
step jobs, and at least a week.
Secrets providers and $Secrets
Every server has a built-in vault, with nothing to set up: it is always the
first provider, so scripts can bind secrets out of the box. Manage it under
Vault (nav): folders and secrets, create, edit, rename, move and delete.
Secrets live in the application database, folder and name in clear for
listing, the value encrypted with the server's Data Protection key ring
(shared by replicas through DATAPROTECTION_PATH, so every node reads what
another wrote). Values are masked; the eye button fetches one with a separate
call that needs the Reveal secrets (secrets.reveal) permission, kept
apart from Manage secrets (secrets.manage, which edits the vault). Every
create, change, move, delete and reveal is audited under secrets, never with
the value. Each save bumps the secret's version, and a save over a version
someone else already replaced is refused.
Configure external vaults under Settings → Secrets providers (Infisical first; the driver interface is pluggable). Connection details are stored as a Data Protection-encrypted blob, secret config fields never return to the browser, and a Test connection validates authentication and listing before you rely on it.
In the script editor's define strip, bind entries of a secrets dictionary to
provider secrets. At dispatch time the server resolves every binding and
sends only the values with the job — devices and browsers never contact the
vault and never hold vault credentials. The agent injects them as a
case-insensitive ordered dictionary session variable (name configurable per
script, default Secrets):
# Bindings: ApiKey ← Infisical API_KEY, DbPassword ← Infisical DB_PASSWORD
Invoke-RestMethod -Uri $Url -Headers @{ Authorization = "Bearer $($Secrets.ApiKey)" }
$cred = ConvertTo-SecureString $Secrets.dbpassword -AsPlainText -Force # case-insensitive
The secret picker browses the vault: folders starting from the provider's default path, then a dropdown of secret names at the chosen path (names only — values never reach the browser), with manual entry as the fallback when the vault is unreachable. Saved providers have a per-row ⚡ Test that validates the stored credentials without re-entering them. A failed fetch at dispatch (vault down, secret missing) fails the job with a value-free error naming the binding and provider. Triggered and scheduled runs resolve secrets the same way as manual runs.
Device groups and script triggers
Groups form a tree. Each group is one of four kinds:
| Kind | Members |
|---|---|
| Folder | None of its own — it organizes the groups nested under it |
| Static | An explicit list of devices |
| Dynamic | The devices matching its rules, evaluated against live device data |
| Script | The devices whose scripts last reported they belong (Script groups) |
A group's membership includes every group nested under it, so running,
scheduling or scoping a role on Sites reaches Sites › Office › Web too.
Groups nest up to eight levels; a group can never be moved inside its own
subtree.
In the console the tree sits beside the device grid (Devices and Groups pages): counts per node include nested groups, the selection and filters live in the URL, groups are dragged onto other groups to nest them (with a confirmation), and right-click / Shift+F10 / long-press opens a group's menu — Run Script, Schedule Script, View Devices, New Group Here, Edit, Duplicate, Move to Top Level, Delete. Deleting a group moves its nested groups up to its parent and drops it from the targets of schedules that aimed at it, disabling any left with no target (with the reason recorded); a group that limits a role's device scope cannot be deleted until it is removed from that role, because dropping it would widen the role to every device.
Rules are one or more condition blocks. Conditions inside a block combine with AND or OR, the blocks themselves combine with AND or OR, and both conditions and blocks have an independent NOT.
Operators: equals, notEquals, contains, notContains, startsWith,
endsWith, regex, in, notIn, >, >=, <, <=, exists,
notExists, inCidr, notInCidr. The CIDR operators evaluate IP fields
against comma-separated ranges (10.20.0.0/16, 192.168.1.0/24) using the
BCL System.Net.IPNetwork — IPv4 and IPv6, bare IPs mean equality, and host
bits in the base address are normalized. The rule builder offers only the
operators that fit the chosen field.
Fields come from hardware inventory, tags, hostname/identity, and live status —
the full catalogue is served by GET /api/groups/fields, so the rule builder
always matches what the server can evaluate:
| Category | Examples |
|---|---|
| Identity | hostname, clientId, status, tags, agentVersion, domain |
| Hardware | manufacturer, model, serialNumber, cpu.cores, memory.totalGb |
| Operating system | os.platform (windows/linux/macos), os.caption, os.version, os.build |
| Storage | disk.count, disk.totalGb, volume.freeGb |
| Network | network.ipv4, network.mac, network.dns, network.interface |
Every deployment starts with the default platform groups — Windows,
Windows Servers, Windows Workstations, Windows PE, Linux, Linux Servers,
Linux Workstations, macOS — driven by os.platform, os.caption and, for
the Linux split, os.edition (the unix agent reports Workstation when the
device boots to a graphical session, Server otherwise). Seeded only while no
groups exist, so edits and deletions stick.
Windows PE holds devices whose agent runs in the pre-imaging environment
(it reports the caption Windows PE; the same device reports its installed OS
once it enrolls from there). Windows holds every Windows device, Windows PE
included; Windows Workstations and Windows Servers hold installed
Windows only. Exclude Windows PE from a schedule or event trigger (below) so a
device being provisioned gets nothing until it leaves Windows PE. An install
that predates the group gets it once at startup (unless a group already has the
name), and an unedited Windows Workstations moves to the rule that leaves
Windows PE out; a marker (groups.windowsPeSeeded) keeps a deliberately
deleted Windows PE group deleted and an edited Workstations rule as it is.
Multi-valued fields (tags, IPs, MACs, DNS) match when any value satisfies a positive operator, and require all values for the negative ones. A missing field satisfies only the negative operators. Invalid or runaway regex never matches and never throws.
The group editor previews candidate rules against live devices as you type. Membership is evaluated once per request for every group, so the group list, device list and fan-out stay cheap at fleet scale.
Schedules run a script (or a sequence) automatically. A schedule is what and where — the script, its arguments, its targets and exclusions, stagger, enabled — and a list of triggers that say when. Targets are all devices, or any mix of devices and groups (members, nested groups included, resolved at fire time); a firing reaches the de-duplicated union, so a device in several targets runs once.
Exclude takes devices and groups out of what the targets reach — All Devices included — and wins over them: what runs is the targets minus the exclusions, both read when the run happens, so rule groups stay dynamic. An event trigger checks the exclusions for the device that fired it: with Windows PE excluded, a device enrolling or getting ready in Windows PE gets no On Enrollment / On Agent Ready run, and since no run was recorded it gets its once-per-device run when it reports in from the installed OS.
| Trigger (console) | API type |
Fires when |
|---|---|---|
| Recurring | scheduled + cronExpression (+ timeZoneId, UTC by default) |
The cron comes due |
| Once | scheduled + runOnceUtc |
That time comes |
| On Enrollment | onRegistration |
A device completes enrollment |
| On Agent Ready | onAgentReady |
The agent is connected and its durable command consumer is bound — genuinely ready for jobs |
| At Logon | atLogon (+ delaySeconds) |
An interactive user signs in on the device (see below) |
| On Demand | onDemand |
Never by itself: the device starts it (see below) |
A schedule holds 1 to 20 triggers in any mix (one On Demand at most), so one schedule can run nightly, at every logon and on demand. Event triggers (On Enrollment, On Agent Ready, At Logon) each have a repeat: every time, once per device, or — At Logon only — once per user per device; On Enrollment and On Agent Ready default to once per device, At Logon to every logon. What has fired is recorded durably per trigger (and per user), claimed before the job is created, so an event delivered twice starts one job. Each trigger keeps its own next and last run. Triggered runs use the normal job pipeline, so they carry the script's Functions prelude, typed parameters and the schedule's captured arguments, and appear alongside manual runs.
A script started by an event or by the device learns how through $Trigger
(PowerShell: Kind, User, SessionId, OccurredUtc, ScheduleId) or, for
Windows PowerShell 5.1 and Bash, the EXECUTER_TRIGGER_KIND, _USER,
_SESSION_ID, _OCCURRED_UTC and _SCHEDULE_ID environment variables. Kind
is enrollment, agent-ready, logon or device-cli.
Script groups
A script decides whether its device belongs in a group, on the device, and the console follows: every script has the built-ins below (no credentials: the agent carries the answer with the job's final state), the device joins or leaves the named group when the job ends, and the group is created (top level, kind Script) the first time a device joins it. Each run decides again, so a scheduled script keeps the group current.
# Member when the value is $true, above 0, a non-empty collection, or text other than false/0/no/off.
Get-Package -Name 'Java*' -ErrorAction SilentlyContinue | Set-ExecuteRGroupMembership 'Has Java'
Set-ExecuteRGroupMembership -Name 'Low Disk' -Value ((Get-PSDrive C).Free -lt 10GB)
Add-ExecuteRGroupMembership 'Pilot Ring'
Remove-ExecuteRGroupMembership 'Pilot Ring'
executer_group "Has Java" "$(pgrep -c java)" # true/false, a number (above 0) or text; default true
- The job's output shows each answer as a line (
Script group “Has Java”: this device is a member.); the built-ins' own marker lines never reach the log. - Names are matched without regard to case; the last answer per group in a job wins; a job reports on at most 25 groups.
- Only script groups change. A name that belongs to a static, dynamic or folder group is ignored (logged on the server), so a device can never put itself into a group an operator curates; a device only ever changes its own membership.
- Script groups can be renamed, moved into folders, targeted, scheduled and used in role scopes like any group; their members cannot be listed by hand. Saving one as dynamic or a folder drops its reported devices. Not being a member of a group that does not exist yet creates nothing.
- Joins, leaves and the group's creation are audited (actor
script:<name>) and show in the activity feed.
At Logon
The agent watches interactive sign-ins and reports each one with the user
(DOMAIN\user), the session id and the logon's own timestamp:
- Windows: the service receives session-change notifications
(
WTS_SESSION_LOGON); the logon time, user and station come fromWTSQuerySessionInformation. A foreground agent polls the sessions instead. The same session watcher drives Remote View's reaction to console switches. Users who signed in before the agent started (a sign-in can beat the service at boot) are reported when it starts; reported logons are kept in%ProgramData%\ExecuteR\logons.json, so a restart reports nothing twice. - Linux:
loginctl(systemd-logind) user sessions, polled every 10 s. Without logind nothing is reported. - macOS: not supported (logged once). Windows PE: no logons, nothing is watched — so a device being provisioned gets no At Logon runs.
Logons that happen while the agent is offline are queued (100 at most, none older than 24 hours) and sent when it reconnects.
Delay After Logon (delaySeconds, up to 24 hours) starts the script that
long after the logon's timestamp, not after the server heard of it. The server
sends the job at once with a start time on the device's own clock
(notBeforeUtc = logon time + delay) and the agent waits it out: no clock
skew between server and device, no dependence on how quickly the event crossed
a slow link, and a short disconnect during the wait changes nothing because the
job is already on the device. If the event arrives later than the delay, the
script starts at once. While it waits, the job shows as Dispatched. (An agent
older than this release ignores the start time and runs at once.)
On Demand and the device CLI
An On Demand trigger makes the schedule's script available to its targets
minus its exclusions — read at the moment of the request, so a device in an
excluded Windows PE group has nothing available — without running it. The
device then starts it itself, choosing the moment (task sequences, Windows PE,
a user-facing tool), and the run is still a normal job: job history, run pages
and the dashboards count it (source Device CLI in the Jobs tab's Runs by
source), the schedule shows it as its last run, and it is audited
(automation / device-run) with the device as actor (device:<hostname>) and
the local user.
ExecuteR-Agent run <name|id> [--param Name=Value ...] [--wait] [--timeout <s>]
ExecuteR-Agent run --list
<name|id>is the schedule's name, the script's name (any case), the schedule's id or the script's id. A name that matches several schedules with different scripts or saved values is refused with the candidates and their ids;--listshows everything available to the device, with parameters.--param/-p Name=Value(repeatable, split at the first=) is checked against the script's parameters exactly as the console checks a run: names ignore case, numbers and booleans are parsed, a list is JSON ([1,2]) or comma-separated, a hashtable is a JSON object. Values given here go on top of the values saved on the schedule.--wait/-wstreams the output to the console and exits with the script's exit code;--timeout/-tbounds the wait.- A schedule that runs a sequence makes it available the same
way (listed with "(sequence)"):
runstarts it and returns at once, also with--wait, since it carries on across restarts;--paramis refused. - Exit codes:
0started (or, with--wait, the script's own code; a failed run that reports none exits1),1refused, not found, ambiguous or bad input,2the agent service is unreachable or not connected to the server,124--waittimed out (the job keeps running). - A bare
run(no further arguments) is still how systemd, launchd and the MSI start the service.
The CLI talks to the running agent (service or foreground, Windows PE included) over a local channel, and the agent asks the server:
- Windows: named pipe
\\.\pipe\ExecuteR.Agent, whose ACL grants only Administrators and SYSTEM (so an unelevated prompt cannot connect). The agent checks each caller's token (impersonating it) and logs its process id; the CLI checks that the pipe is owned by SYSTEM or Administrators before it sends anything. - Linux/macOS: Unix socket
/run/executer/agent.sock(/var/run/executer/agent.sockon macOS) in a root-only directory, mode 0600; on Linux the caller must also be uid 0 (SO_PEERCRED).
Example: a ConfigMgr or MDT task sequence step (it runs as SYSTEM) that runs a script made available by an On Demand schedule targeting the Windows PE group, waits for it and fails the step with the script's exit code:
"X:\Program Files\ExecuteR\Agent\ExecuteR-Agent.exe" run "Stage Drivers" --param Model=%Model% --param Wipe=true --wait --timeout 1800
After imaging, the same schedule (if it targets the installed OS too) can be
run from a later step with "%ProgramFiles%\ExecuteR\Agent\ExecuteR-Agent.exe" run "Stage Drivers" --wait.
Group runs and schedules
Run now works from anywhere a target is in view: a device row's … menu, the bulk Actions of chosen devices, a group in the tree, the device and group pages, and the script editor. One dialog picks the script, any mix of devices and groups, devices and groups to Exclude, and typed arguments (starting from each parameter's default). Before you confirm it shows the reach — how many devices, how many excluded, how many online, and orphaned ones that will be skipped — and Only Devices Online Now skips offline devices instead of queueing for their return (by default offline members receive their job durably when they reconnect). Every target of one run shares one execution, which the result links to.
POST /api/jobs accepts the same mix: clientId (the original single-device
call, answering with the job), clientIds, groupId, groupIds,
excludeClientIds, excludeGroupIds and onlineOnly, deduplicated,
exclusions taken out and scope-filtered into one runId.
Stagger spreads a run's starts so a large fleet does not hit one share or
service at once: Spread Over (staggerSeconds, up to 24 hours) and
Devices at a Time (staggerBatchSize, default 1), on the Review tab and on
schedules. Devices fall into ceil(targets ÷ batch) batches evenly spaced over
the spread: the first starts at once, the last when the spread ends, in an order
shuffled per run so the same device is not always last. With one batch or no
spread the run dispatches as it always has. What it guarantees:
- It is durable. Each job keeps its fixed start time and a worker on the
SCHEDULE_WORKERnode sends it when it is due, so a backend restart loses nothing and starting a run returns at once for any number of devices. - Every device runs the script as it was when the run started, with its arguments and prelude, from a snapshot sealed with Data Protection and cleared when nothing is left to send. Secrets and presigned URLs are resolved when each batch is sent and never stored.
- Only Devices Online Now is checked again at a device's start: offline by then, it becomes skipped.
- A deleted script fails the jobs still waiting. Cancel Waiting
(
POST /api/executions/{runId}/cancel-waiting, Run Jobs, audited, within the caller's device scope) cancels what has not been sent. - A job whose publish fails is retried by the same worker, with or without a stagger, for up to 24 hours before it fails; a vault or S3 failure at send time is retried for 5 minutes.
Watching a run (Jobs › a run): while devices wait, a strip counts down to the
next and the last start, corrected for the browser's clock, and each waiting
device counts down in its row. Above the devices, updating live: a tile per
state, an outcome ring, exit codes, errors grouped by exception type and first
line with sample devices, and completions over time; tiles, exit codes and errors
filter the table. GET /api/executions/{runId}/breakdown serves the charts,
limited to the caller's device scope.
Schedules (the Schedules page, plus a Schedules tab on scripts, devices
and groups): when — a list of triggers, added with Add Trigger (Recurring,
Once, On Enrollment, On Agent Ready, At Logon, On Demand; see the table above)
and shown in the table as chips with the detail on hover — targets (any mix
of devices and groups whose members resolve at fire time — at least one — or
All Devices alone), devices and groups to Exclude, an optional name, and
the arguments to run with. Under the pickers the
editor shows today's effective reach ("Windows · 240 devices, 12 excluded").
Each can be edited in place, duplicated, paused, or run now without
disturbing its cadence. The API takes clientIds, groupIds, allDevices,
excludeClientIds, excludeGroupIds and triggers on POST/PUT /api/triggers; a schedule names at most 1,000 entries, included and excluded
together. Each item of triggers is { type, id?, cronExpression?, runOnceUtc?, timeZoneId?, delaySeconds?, repeat? }; sending an existing trigger's id
keeps it (and what it has fired), the others are replaced. A request without
triggers is the single trigger its older triggerType / cronExpression /
runOnceUtc / timeZoneId fields describe, and the list still returns those
fields from the first trigger (with the earliest nextRunUtc).
The cadence builder leads with friendly selectors — every N minutes/hours,
daily/weekly/monthly at a time with weekday chips, once — and compiles them
to cron; a raw cron field exists only under Advanced, and a saved cron
reopens in its friendly form when it has one. The next runs are computed by
the server (POST /api/triggers/preview) in the schedule's time zone, so what
you see is what will fire.
Semantics worth knowing:
- Expressions (and a one-shot's date and time) are read in the schedule's time zone — UTC unless another is picked — so "daily at 01:00" in a zone with DST tracks it; storage and comparison are UTC.
- A device or group that no longer exists when a schedule fires is skipped and noted in the last result; the rest still run. Removing a device or deleting a group drops it from schedules' targets and exclusions.
- Exclusions only take devices away: a device-scoped role may exclude any group, and any device it can see.
- An unknown time zone, a never-firing cron, or an enabled one-shot in the past is refused when saving.
- The worker sweeps regularly; recurrence advances from now after each firing, so server downtime causes at most one late firing, never a storm. Several triggers of one schedule due in the same sweep fire it once, and each of them advances.
- A schedule whose triggers are all one-shots disables itself once they have fired.
- A schedule's Stagger applies to each firing; event triggers run on one device at a time and have none.
- Each schedule records its last result (jobs queued, or the error — e.g.
a vault failure) and the execution it created; scheduled jobs are attributed
to
schedule, run-now firings to the operator. - A device-scoped role can only aim schedules inside its scope: a device it can see, or a group whose members it can all see — never all devices.
- Deleting a script removes its schedules with it; schedule changes are
audited under the
automationcategory. - Arguments captured on the schedule are used for every firing; secret bindings resolve fresh server-side at each fire time.
Database providers
The Compose stack runs on Postgres by default: the bundled postgres
service (see Docker Compose), with these in .env
(deploy.sh writes them, the password generated):
DATABASE_PROVIDER=postgres
DATABASE_CONNECTION_STRING="Host=postgres;Port=5432;Database=executer;Username=executer"
DATABASE_PASSWORD=<generated>
COMPOSE_PROFILES=postgres
The standalone server and the server installer default to SQLite, which needs no configuration, as does a Compose stack that already ran on it. Every deployment selects its provider the same way:
DATABASE_PROVIDER=sqlite # or: postgres | sqlserver
DATABASE_PATH=/data/app.db # sqlite only
DATABASE_BACKUP_PATH=/data/backups # backups (Settings › Database), SQLite and Postgres
DATABASE_PROVIDER=postgres
DATABASE_CONNECTION_STRING=Host=db;Port=5432;Database=executer;Username=executer;Password=...
DATABASE_PROVIDER=sqlserver
DATABASE_CONNECTION_STRING=Server=db;Database=executer;User Id=sa;Password=...;TrustServerCertificate=True
DATABASE_PASSWORD=... # optional: the password apart from the connection string
In a Compose .env, quote a connection string ("…;…": deploy.sh reads
.env as a shell would) and keep $ out of passwords, or double it ($$),
since Compose expands it. Your own Postgres or SQL Server instead of the bundled
one: set its connection string; deploy.sh then leaves the postgres profile
off.
DATABASE_PASSWORD, when set, becomes the connection string's password, so the
string itself can be read and edited without it. The server
installer writes it protected (dpapi: and a Windows DPAPI
blob in the machine's scope), which only that computer can read back.
Each provider carries its own EF Core migration set, applied automatically at
startup. SQLite stores timestamps as UTC ticks (it cannot order
DateTimeOffset natively); Postgres and SQL Server use native timestamp
columns.
Adding a migration touches all three:
dotnet ef migrations add <Name> --project src/Backend --context SqliteAppDbContext --output-dir Data/Migrations/Sqlite
dotnet ef migrations add <Name> --project src/Backend --context PostgresAppDbContext --output-dir Data/Migrations/Postgres
dotnet ef migrations add <Name> --project src/Backend --context SqlServerAppDbContext --output-dir Data/Migrations/SqlServer
Settings › Database: insight, maintenance and backups
Settings › Database (Manage Settings) shows the provider and version, the
database's size, its free space, every table's rows (and size, where the
provider can tell), and the last and next maintenance and backup. Only one
database task (a backup or maintenance) runs at a time, across every replica;
it runs in the background with its step shown, and starting, finishing,
downloading and deleting are all in the audit trail (category settings,
actions database-*).
| SQLite | Postgres | SQL Server | |
|---|---|---|---|
| Size | The database file with its -wal and -shm |
pg_database_size |
Data and log files (sys.database_files) |
| Free | Free pages (freelist_count × page_size) |
Dead rows (pg_stat_user_tables) |
Unallocated space in the data files |
| Tables | Row counts; sizes when SQLite has dbstat (the bundled build does not) |
Estimated rows, total size, dead rows | Rows and reserved size (sys.dm_db_partition_stats, needs VIEW DATABASE STATE) |
| Maintenance | wal_checkpoint(TRUNCATE), VACUUM, checkpoint, PRAGMA optimize |
VACUUM (ANALYZE) |
ALTER INDEX … REORGANIZE on every rowstore index, sp_updatestats; never shrinks |
| Backups | Online copy (SQLite backup API), quick_check, gzip |
pg_dump --format=custom, read back with pg_restore --list |
BACKUP DATABASE … COPY_ONLY, CHECKSUM to a folder on the SQL Server host |
SQLite VACUUM writes a whole new copy of the database before swapping it in:
it needs free disk about the size of the database (it refuses to start
without), and writes wait until it finishes.
Backups and periodic maintenance are both off by default; each has its
own cron schedule in a time zone (UTC unless chosen). A run missed while the
server was down happens once when it is back; saving the settings starts both
schedules over from then. Schedules fire on the node with SCHEDULE_WORKER
on.
- SQLite backups are
executer-sqlite-<yyyyMMdd-HHmmss-fff>.db.gz, a self-contained database (journal mode DELETE) checked withquick_checkbefore it is compressed. They go to the server folder,DATABASE_BACKUP_PATH(defaultbackups/inDATA_PATH, else beside the database:/data/backupsin the container, inside the/databind mount), to the S3 store chosen in Settings › Storage (built-in or external) underexecuter/backups/, or both. The copy is staged uncompressed in the folder first, so it needs free disk about the size of the database. After every backup each destination keeps the newest Keep backups; only files named like a backup are ever deleted. Downloading one needs a fresh step-up (it is the whole database) and is audited. - SQL Server backups are written by SQL Server itself, into the folder
set as SQL Server Backup Folder (a path on the SQL Server host, e.g.
/var/opt/mssql/backuporD:\Backups; the server's login needsdb_backupoperatorordb_owner). They areCOPY_ONLY, so your own backup chain is untouched. Files areexecuter-sqlserver-01.bak…-NN.bakfor Keep = NN, each new backup overwriting the oldest (INIT, FORMAT); lowering Keep leaves the higher-numbered files on the host. The console lists them but cannot download or delete them: copy them from the host. - Postgres backups are
executer-postgres-<yyyyMMdd-HHmmss-fff>.dump, apg_dumpcustom-format archive (compressed bypg_dumpitself, so not gzipped again) of the server's database over its own connection, read back withpg_restore --listbefore it is kept. They go to the same destinations as SQLite's (server folder, S3 store, or both), with the same Keep and step-up download. Retention prunes only Postgres backups: SQLite backups from before a move to Postgres stay listed until you delete them. The backend image carries the PostgreSQL 18 client (PG_DUMP_PATH), the bundled server's major;pg_dumpmust be the server's major or newer, so a newer external server needs a newer client. Elsewhere (the standalone server, the MSI)pg_dumpis found onPATHor atPG_DUMP_PATH; without one the console says backups are not available here.
Restoring a backup (manual)
Restoring is deliberately not a button. Stop the backend first in every case.
SQLite:
docker compose -f IaC/compose/docker-compose.yml stop backend
cd "$STACK_BINDMOUNTROOT/$STACK_NAME/API/Data" # the backend's /data
mv app.db app.db.before-restore
rm -f app.db-wal app.db-shm # stale journal of the old database
gunzip -c backups/executer-sqlite-20261106-020000-000.db.gz > app.db
chown 1000:1000 app.db # PUID:PGID of the backend
docker compose -f IaC/compose/docker-compose.yml start backend
On a standalone server the database is DATABASE_PATH (by default
<data>/db/app.db) and the backups are in backups/ under DATA_PATH;
stop the service, do the same, and start it. A backup from an older version
is migrated forward when the server starts.
SQL Server, on the SQL Server host (the backend stopped):
RESTORE DATABASE [executer] FROM DISK = N'/var/opt/mssql/backup/executer-sqlserver-03.bak'
WITH REPLACE, CHECKSUM;
Postgres (the bundled one): the dump is in the backend's /data/backups, and
the backend image has pg_restore. Into the live database, replacing what is
there:
cd /opt/executer # the stack folder (holds .env)
docker compose --env-file .env -f IaC/compose/docker-compose.yml stop backend
docker compose --env-file .env -f IaC/compose/docker-compose.yml run --rm --no-deps \
--entrypoint sh backend -c 'PGPASSWORD="$DATABASE_PASSWORD" pg_restore --clean --if-exists --no-owner \
--single-transaction -h postgres -U executer -d executer /data/backups/executer-postgres-20261106-020000-000.dump'
docker compose --env-file .env -f IaC/compose/docker-compose.yml start backend
Your own Postgres: pg_restore --clean --if-exists --no-owner -d "<connection URL>" <file>.dump
with a client of the server's major or newer. pg_restore --list <file>.dump
shows what an archive holds without restoring it.
Restore with the same Data Protection keys the backup was made with (keys/
beside the database, /data/keys in the container, or DATAPROTECTION_PATH):
saved secrets (S3 keys, sign-in secrets, the built-in vault) are sealed
with them and cannot be opened otherwise.
Moving from SQLite to Postgres
An existing Compose install stays on SQLite until you move it. The server's
migrate-database verb copies every row of the SQLite database into an empty
Postgres database through EF Core (the Postgres migrations applied first, so
the schema is the same), table by table in foreign-key order, inside one
transaction: keys, identity values (the sequences continue after them),
concurrency stamps and timestamps as they were. It prints each table's rows
as it goes, then a SQLite / Postgres count for every table, and commits only
when every count matches; otherwise no rows are written. The SQLite file is
only read.
From the stack folder (/opt/executer when bootstrapped, else the checkout):
C="docker compose --env-file .env -f IaC/compose/docker-compose.yml"
# 1. Choose Postgres: deploy.sh then writes the connection string, a generated
# DATABASE_PASSWORD and COMPOSE_PROFILES=postgres, and pulls the image.
sed -i 's/^DATABASE_PROVIDER=.*/DATABASE_PROVIDER=postgres/' .env
./scripts/deploy.sh --no-start # bootstrapped: curl … deploy.sh | bash -s -- --no-start
# 2. Stop the backend (nothing writes the SQLite file from here on).
$C stop backend
# 3. Start the empty database and copy into it.
$C up -d --wait postgres
$C run --rm --no-deps backend migrate-database
# 4. Start everything on Postgres.
./scripts/deploy.sh
migrate-database reads /data/app.db (--from <file> for another) and
writes to the database the container is configured for, which must be
Postgres. It refuses (exit 2, nothing changed) when the target already has
rows (a backend already started on it: --overwrite empties it first), when
app.db-wal is not empty (a server may still be writing: stop it, or
--force), or when the SQLite database is from another version (start that
version on it once, then copy). The Data Protection keys in /data/keys are
not in the database and stay where they are; the new server uses them.
Keep app.db until you are satisfied; going back is
DATABASE_PROVIDER=sqlite in .env and ./scripts/deploy.sh (whatever was
written on Postgres in between is not carried back).
Logging
All services share one Serilog pipeline (Shared.Infrastructure/Logging):
console plus a daily rolling file with a size cap and retention.
Rotation defaults are set centrally per role in LogDefaults, because
endpoints are numerous and disk-constrained while the server is neither:
| Role | Roll at | Keep | Ceiling |
|---|---|---|---|
| Agent | 5 MB | 3 files | ~15 MB |
| Backend | 10 MB | 7 files | ~70 MB |
LOG_LEVEL=Information # Verbose|Debug|Information|Warning|Error|Fatal
LOG_JSON=0 # 1 = compact JSON (for log shippers)
LOG_DIRECTORY=/data/logs # empty disables file logging
LOG_RETAIN_FILES=7 # server default; agent default is 3
LOG_MAX_BYTES=10485760 # server default 10 MB; agent default 5 MB
Files also roll daily, so the size cap is an upper bound rather than the usual trigger.
Framework noise is pinned to Warning regardless of LOG_LEVEL, and health
probes log at Verbose so they do not flood the file. Requests are logged once
each with the effective (proxy-aware) client IP and the authenticated user.
Correlation fields (CorrelationId, ClientId, JobId, ShellSessionId,
BrowserSessionId, RemoteIp) flow through as structured properties.
The agent takes its level from its own configuration precedence
(GPO > Agent Settings profile > registry > default; a profile change applies at
the next agent restart) and writes to <install>\Logs (next to the
watchdog's log). A bad log path degrades to console logging rather than failing
startup.
Secrets are never logged: tokens, passwords, client secrets, NKey seeds, JWTs,
cookies and authorization headers. A structured property with one of those names
({Password}, {Jwt}, … see Redaction.NeverLog) is masked as [redacted]
before any sink sees it, live views included.
Log line format
Every text line any ExecuteR process writes (server, agent, watchdog, MSI and removal runners, screen host) has one shape:
[2026-11-16T17:53:40.653Z] - [LeafRouter] - [INFO] - The site's leaf answers again; moving back to it from the hub leaf=wss://172.18.16.104:9001
[2026-11-16T17:53:40.687Z] - [EventBus] - [WARN] - The site's leaf could not be reached; the bus goes through the server meanwhile reason="TLS: certificate expired"
[2026-11-16T17:54:40.701Z] - [EventBus] - [WARN] - The site's leaf could not be reached; the bus goes through the server meanwhile reason="TLS: certificate expired" repeated=37 window=60s
- Time: UTC, ISO 8601, milliseconds,
Z. - Category: a short component name: the logging type without its namespace
or generic arguments (
Agent.Screen.ScreenSessions→ScreenSessions, a nestedOuter+Inner→Outer.Inner);AgentorServerfor a line with no type;Watchdog,MsiRunner,RemovalRunnerfor the watchdog's;ScreenHost(or a dependency's crate,ironrdp_server) for the screen host's. - Level:
TRACE,DEBUG,INFO,WARN,ERROR,FATAL. - Message: rendered with strings bare, then every property the message did
not use as
key=value(correlation fields such asCorrelationId,ClientId,JobIdincluded;SourceContext,MachineName,Application,EventIdand the framework'sRequestId/ConnectionId/ActionIdleft out). A value with whitespace,=or"is double-quoted with\"escaped; a missing value isnull. An exception follows on the next lines.
LOG_JSON=1 writes compact JSON instead, unchanged. The live views carry the
same message text. Log files from earlier versions
([2026-11-06 12:00:00.000 INF] Source: message, the watchdog's
2026-11-06 12:00:00.000Z [INF] message) are still read by the watchdog's live
view (LogLineParser).
Repeats are bounded. A warning, error or fatal is the same as another when
its level, category (full SourceContext) and message template match. The first
is written at once; the same one again within 60 s is only counted, and when the
window ends with any counted, one line is written: the last of them with
repeated=N window=60s. While it keeps repeating that summary comes once a
minute; a minute without it forgets it, so the next one is written at once. At
most 1,000 distinct events are tracked (the oldest goes first, with its count
written), and stopping the process writes every count still open. Information
and below are never held back. The screen host does the same for its own
warnings and errors.
Live logs and log files in the console
Every process keeps its last 2,000 log lines in memory (a Serilog sink feeding a
ring buffer, LiveLog), so the console can follow a log as it is written without
reading files. Both views share one viewer: monospace lines with the level in
colour, newest at the bottom while following; scrolling up stops following and
Follow resumes it. Pause/Resume, level filters, search, copy and
clear; a restart or lines dropped while paused show as markers.
| Server Logs (Administration) | A device's Logs tab | |
|---|---|---|
| Live | The server node serving you | The agent, or the watchdog (followed from its file while the tab is open) |
| Files | *.log directly in LOG_DIRECTORY |
*.log directly in the agent's and the watchdog's log folders (MSI and removal runs included) |
| Permission | logs.view (Admin) |
devices.logs (Admin, Operator, Help Desk), in device scope |
A live view long-polls: GET …/tail?instance=&after=&wait= answers with the lines
after its cursor as soon as there is one, or empty after wait seconds (at most
25). A device's tail, file list and download go to its agent the way the file
browser does (Core NATS request from whichever node holds the browser's request),
so there is no new subject or permission on the bus. They name no path, only a
log source or a bare file name the agent finds in its own log folders, and they
answer even where AllowFileAccess is off. devices.logs is separate from
files.browse for that reason: it reads the agent's own diagnostics and nothing
else on the device, so a role can be given one without the other.
Log files are only the *.log files directly in those folders: no subfolders,
no links, and a name that is not one of them is not found. A file still being
written downloads as long as it was when the download started. Downloads are
plain GETs and go on the audit trail (category files, server-log-downloaded
or log-downloaded); the polls are kept out of the request log.
| Endpoint | Permission |
|---|---|
GET /api/logs/server/tail, GET /api/logs/server/files, GET /api/logs/server/files/{name} |
logs.view |
GET /api/devices/{clientId}/logs/tail?source=agent|watchdog, GET …/logs/files, GET …/logs/files/{name} |
devices.logs |
Agents from before live logs answer that they need an upgrade.
Device lifecycle: reconnect or orphan
A device silent for longer than the orphan window is orphaned. The window
is centrally defaulted to 30 days (ProtocolDefaults.DefaultOrphanAfterDays)
and controlled with one setting:
DEVICE_ORPHAN_AFTER_DAYS=30 # default when unset
DEVICE_ORPHAN_AFTER_DAYS=0 # disable orphaning entirely
With orphaning disabled, a device that stops checking in just ages through Online → Stale → Offline, keeps its credentials, and reconnects entirely on its own whenever it comes back — nothing to do.
An orphaned device is refused credential refresh and job dispatch, and is not resurrected merely by reappearing — presence from it is logged and ignored. Recovery is deliberate:
flowchart LR
O["Silent past the window"] --> M["Backend marks device orphaned"]
M --> R["Refuses credential refresh and job dispatch"]
R --> T["Admin pushes a new bootstrap token (GPO, MSI, URL install)"]
T --> E["Agent sees the token and re-enrolls"]
E --> B["Same device record, orphan flag cleared, back in service"]
The agent side needs no special mode: a bootstrap token is erased after every successful enrollment, so the presence of one is by definition a deliberate instruction. When an already-enrolled agent finds a token, it discards its stored credentials and re-enrolls. Enrollment is idempotent by client id, so the device keeps its history, groups and tags.
Removing devices
Remove Agent… on a device (row menu, bulk Actions, device page) or Remove
Agents… on a group or folder (nested groups included) takes the device out of
the system at once and uninstalls its agent now, or whenever it next comes back.
It needs the devices.remove permission, which Admin has and Operator and Viewer
do not. Scoped roles reach only the devices in their scope.
The device row goes in the same transaction as its group memberships and trigger runs; schedules aimed at that device alone are disabled and jobs that never started are cancelled. Finished jobs, their output and the device's history stay, and old runs keep its name. What stands in for the row is a removal, kept forever as the history.
flowchart TD
R["Remove Agent: device row deleted, removal waiting"] --> S{"Seen online?"}
S -- "No, however long" --> S
S -- "Yes, agent 1.1.0 or later" --> C["Remove command sent (at most every 5 min)"]
S -- "Yes, older agent" --> O["Agent too old: stays open, stays blocked"]
C --> U["Agent reports uninstalling"]
C -- "It failed" --> F["Couldn't Uninstall: asked again"]
C -- "No answer for 30 min" --> S
F --> S
U -- "Silent for 15 min" --> D["Removed: consumer deleted, commands purged"]
U -- "Still reporting after 15 min" --> S
D -- "Reports again" --> S
Online. The next scheduler pass (every 15 seconds, on the node with
SCHEDULE_WORKER on) sends the command. Its enrollment id must match what the
agent holds, so a stale command can never uninstall a device enrolled again since.
After a successful uninstall nobody is left to report success, so 15 minutes of
silence after "uninstalling" counts as gone.
Offline. A removal waits for as long as the device stays away. Presence, inventory and ready notices from a client id with no device row only update the removal; they never bring the row back.
Credentials. Agents from 1.1.0 on hold a NATS credential that lasts 24 hours,
renewed over HTTPS at half life and at every start. A renewal for a removed device
answers 410 with problem type urn:problem:device-removed, and the agent
uninstalls itself, so a device that slips past the command is still cut off within
a day. Only the holder of the enrolled key learns this: a bad signature gets the
same plain 401 as an id nobody knows. Older agents never renew and could not
survive an expiring credential, so enrollment still gives them one that never
expires. To keep that true an agent on 1.1.0 or later is never upgraded or rolled
back to anything older (it is left out as credential-downgrade); exactly 1.1.0
is fine.
Tokens. A bootstrap token created at or before the removal no longer enrolls
that device, whatever its other limits say, so the install it has and a GPO still
pushing an old token cannot bring it back. The response is the plain 401 of any
refused token, with the reason in the audit trail. A token created after the
removal enrolls it on a fresh device row: an open removal closes as removed, and
its old command consumer and commands are cleared first, so nothing old replays.
In the Devices list. A removal shows in the list for 7 days after its last
change: dimmed, with its state, not selectable and not counted in the totals. After
that the list stays uncluttered, and the Removals option of the Status filter
shows every removal whatever its age, with who asked, when, and what happened.
Clicking a removal opens the device's history. GET /api/device-removals takes
state, clientId and limit (default 200). Scoped roles see the removals of
devices that were in one of their scope groups when they were removed; a device
that was in none is visible to unscoped roles only.
Stop Trying. POST /api/device-removals/{id}/stop on an open removal ends the
chase: the device stays blocked, its pending command is purged and its agent stays
installed, cut off when its credential expires (a renewal gets a plain 401, not
410, because 410 would uninstall it after all). Enrolling it again needs a new
token.
Agents too old. An agent below 1.1.0 cannot take the command or renew. Its removal stays open marked Uninstall It by Hand or Upgrade It First, and since its credential never expires the server cannot cut it off from NATS: it can keep connecting, but the server ignores everything it reports. Once such an agent reports 1.1.0 or later the command goes out as usual.
The audit trail keeps device-removal-requested, device-removed and
device-removal-stopped. The project wiki is updated separately.
On the device
Credentials. The agent's NATS credential lives 24 hours. A small background
service renews it over HTTPS (POST /api/enrollment/credential, signed with the
enrolled NKey, TLS as for enrollment) at every start and at half life, whether
or not NATS is connected, so an expired credential recovers by itself as soon as
the server can be reached, and a credential from before 1.1 that never expires
is replaced at the first start. The old credential stays until the new one is
stored; the NATS connection takes the new one at its next reconnect, at the
latest when the server ends the connection as the old one expires.
| The server answers | The agent |
|---|---|
| a new credential | stores it, atomically, and looks again at half its life |
| network error, 5xx, anything unexpected | keeps what it has and tries again after 30 s, doubling to 15 minutes |
| 401 (orphaned, or the clock is off) | keeps what it has and tries again hourly; a configured bootstrap token enrolls it again (Device lifecycle) |
410 urn:problem:device-removed |
uninstalls itself, as below. Not with TlsSkipVerify on or over plain http: an unverified server must not be able to uninstall an agent, so that only logs a warning |
While an upgrade could still roll back (handover.json, journal.json,
msi.json), the stored credential is left alone: a version before 1.1 cannot
renew and would strand on a 24-hour one. It renews when the upgrade is kept. The
one exception is a credential within an hour of expiring, which would strand
either way and would keep the new version from reporting healthy. For the same
reason an agent on 1.1 or later refuses an upgrade to a version before 1.1
(failed / unsupported).
The remove command. command.agent.remove may be old, since it waits in its
stream, so the agent acts only when its enrollment ID is the one the agent holds
(else failed / stale-enrollment). A foreground or development run answers
failed / unsupported, an upgrade in progress failed / busy (the server
asks again). Otherwise the agent reports uninstalling, writes
upgrade/removal.json and leaves the rest to the watchdog. A device where no
watchdog can take it (none installed, or it has not taken it within 2 minutes)
runs the same runner from a copy of the agent's own binary. The watchdog starts
no upgrade while removal.json exists and a removal waits for an upgrade under
way; it does not supervise the agent during a removal.
The runner. The watchdog copies itself out of both folders it is about to
wipe, into %SystemRoot%\Temp\ExecuteR-<id>-<random>\ (closed to SYSTEM and
Administrators), or /var/lib/executer-removal-<random>/ on Linux and macOS, and
starts the copy apart from its service: detached on Windows, as a transient
systemd-run unit on Linux, as a one-shot launchd daemon on macOS, since the
service manager would otherwise end it with the service. The runner:
- stops the agent;
- uninstalls: an MSI install in process through Windows Installer
(
MsiConfigureProductExW, no UI,REBOOT=ReallySuppress, never msiexec), which removes both services; 1618 is waited out for up to 10 minutes. A portable install loses both services through the service manager (the runner refuses to wipe a folder that holds no agent binary, or a shared one such asC:\Program Files); - verifies and finishes the purge, whatever the MSI's own purge managed.
Three attempts, 5 minutes apart, 30 minutes at most each. A failed attempt starts
both services again. After the third, removal.json says failed with the
reason, the agent reports failed / msi or failed / uninstall, deletes the
file and carries on; the server asks again. After a success nobody is left to
report it.
| Wiped | Left |
|---|---|
credentials.dat and the whole data folder (%ProgramData%\ExecuteR, /var/lib/executer) |
the policy key HKLM\SOFTWARE\Policies\ExecuteR (and the policy section of agent.json): it is group policy's |
HKLM\SOFTWARE\ExecuteR with Runtime, ServerURL, the token, proxy and TLS values (/etc/executer/agent.json, the /usr/local/bin link) |
a server CA the agent did not itself add to the trust store. That includes every CA installed before 1.1, which kept no record of it |
the install folder, Logs included |
the runner's folder on Windows, until the next restart |
both services; the server CA the agent added (managed-ca.txt) |
A file still locked after a minute is deleted at the next restart. A failed
removal keeps its logs as <install>\Logs\agent-removal-<id>-*.log.
Agent installer delivery
The installer ships inside the backend image — no manual seeding. The CI
Windows job runs Package-Agent.ps1, uploads the result as an artifact, and
the Linux image job stages it into the backend image at /opt/executer/agent
before docker build. A stock deployment can therefore serve
/api/enrollment/install immediately.
The backend resolves the package in this order:
AGENT_PACKAGE_PATH— compose defaults it to/data/agent, which is a host bind mount (…/API/AgentPackage). Dropping a newAgent.msi/Agent.zip(plus an optionalVERSIONmarker) there delivers an out-of-band agent update instantly — it wins over the baked package, with no new backend image or restart./opt/executer/agent— baked in by CI/data/agent— fallback whenAGENT_PACKAGE_PATHpoints elsewhere
If agent offload is enabled, /api/enrollment/agent-package returns a 302 to a
short-lived presigned URL (Link Lifetime, 300 s by default, 30–3600) instead of
streaming the file, keeping multi-megabyte downloads off the control plane. With
the built-in store the link is on this server (PUBLIC_SERVER_URL, otherwise the
forwarded host); with an external store it is the provider's own. If the file is
not in the store, or presigning fails, it falls back to local delivery rather
than breaking installs. The Linux/macOS install script keeps its pinned CA only
for links on this server and checks an external store's link against the
system's trust.
Agent downloads and stable links
Each package has a stable link that always serves the newest build, so a mirror, an imaging pipeline or a WinPE build can fetch the same URL after every release:
| Link | Package |
|---|---|
/api/downloads/agent/Agent.msi |
Windows MSI |
/api/downloads/agent/Agent.zip |
Windows portable ZIP (also Windows PE) |
/api/downloads/agent/Agent-linux-x64.zip, Agent-linux-arm64.zip |
Linux |
/api/downloads/agent/Agent-osx-x64.zip, Agent-osx-arm64.zip |
macOS |
GET /api/downloads/agent lists them as JSON (type, newest version, SHA-256,
size, link). GET and HEAD both work, and every package response names its
build in X-Agent-Version. With agent offload on, a link answers with a 302 to a
fresh short-lived link in the object store. S3 presigned links cannot be
permanent (SigV4 allows 7 days at most), so the stable link is this server's
route, not a bucket URL.
Public Downloads (Settings → Enrollment Tokens → Agent Downloads, off by
default) decides who gets through. On: anyone. Off: the install
scripts, whose package URLs carry their bootstrap token (any token that is not
revoked or expired; uses are not counted), and signed-in users with
devices.view. Upgrades by content hash (/api/agent-packages/{sha256}) are
not affected.
The Windows install command needs no package choice: the script installs the MSI, or the portable ZIP when the device runs Windows PE.
Settings → Agent installer delivery shows which source is live, the file
size, version and SHA-256, and Upload Now runs the offload sync on demand.
Agent files are stored by version, on disk and in the store alike:
agent-packages/<version>/<file> under the data folder and
executer/agent/<version>/<file> in the bucket (e.g. 1.4.0/Agent.msi).
For a local build without CI:
./scripts/Package-Agent.ps1 # writes artifacts/ExecuteR-Agent-<version>.msi
# then mount that directory at /data/agent, or set AGENT_PACKAGE_PATH
Agent upgrades from the server
How upgrades are started, paced and rolled back. What happens on the device is in Agent upgrades and the watchdog.
On the server
Versions arrive with each server release. The agent packages that ship in
the backend image (or are dropped into AGENT_PACKAGE_PATH, with their
VERSION marker) are imported into the server's version catalog at
startup and every five minutes: the MSI (listed as Windows (MSI)), the
portable Windows zip and the Linux/macOS builds. Each device gets the package
of how its agent was installed: an agent the MSI installed upgrades through
the MSI, with the MSI of the version it runs now in the command for a
rollback when the catalog holds it; a portable one swaps files from the zip.
Each package is copied to <DATA_PATH>/agent-packages/<version>/, so a
device can still be rolled back after the image moves on. A development build
(0.0.0.0) or a package without a version is not catalogued.
The catalog keeps the newest KeepVersions versions (default 5). It never drops the newest version, a version an open upgrade goes to, or a version some device's last upgrade came from (its rollback target); removing a version by hand is refused with the same reason (409).
Agents download from GET /api/agent-packages/{sha256} — anonymous like the
install package, with range support, and not rate-limited per address (a
fleet behind one NAT upgrades through it). With agent offload on, the catalog
sync (every 5 minutes) uploads each version's folder to the store, and the route
answers with a 302 to a fresh short-lived link. Upgrade commands always carry the
server path, so a link never expires while a command waits; agents follow the
redirect and still check the size and SHA-256.
| Route | Permission | |
|---|---|---|
GET /api/agent-versions |
devices.view | Versions newest first: packages, devices on it, why it cannot be removed |
DELETE /api/agent-versions/{version} |
settings.manage | Remove a version (409 while needed) |
POST /api/agent-upgrades |
devices.manage | Upgrade devices and groups (nested included) to version, or the newest per platform, optionally over staggerSeconds, staggerBatchSize at a time |
POST /api/agent-upgrades/rollback |
devices.manage | Back to the version each device's last upgrade came from |
POST /api/agent-upgrades/{id}/cancel |
devices.manage | Cancel an upgrade not yet sent |
POST /api/agent-upgrades/cancel-waiting |
devices.manage | Cancel every upgrade still waiting for its turn in a spread |
GET /api/agent-upgrades?clientId=&open=true&limit= |
devices.view | Upgrade attempts, newest first |
GET/PUT /api/settings/agent-upgrades |
devices.view / settings.manage | Settings › Agent Upgrades |
A start or roll back returns what was queued and who was left out: already
(on the target), busy (an upgrade is open), no-package, unsupported (no
build for its platform), orphaned, or no-previous for a roll back. The
package comes from the runtime the agent reports; older agents are matched by
their inventory's OS and architecture. Offline devices are queued and start
when they come back (a request waits up to 7 days, then expires).
Upgrades start in paced batches so a large fleet never downloads at once:
every 15 seconds the next batch of queued, online devices is sent, sized so
each starts within StartWithinMinutes (default 3) of being ready — at least
10 a batch — and each agent waits a random 0–15 seconds before downloading.
A batch's commands are sealed and published side by side (JOB_DISPATCH_PARALLELISM,
default 16, as a run's), its rows marked sent 500 per statement and only from
queued, so no row goes out twice; a device whose command did not go out goes back
to the queue alone and is sent by a later pass.
Only downloads are paced; a device installing has finished its download. A
device that goes quiet is failed no-report (30 minutes without an event
while downloading, or the health deadline plus 15 minutes while installing);
a late outcome still counts. When a device's presence already shows the target
version, its upgrade is closed as succeeded.
Stagger spreads an upgrade of several devices over longer than that, when the
fleet or its network needs it: Spread Over (staggerSeconds, up to 24 hours)
and Devices at a Time (staggerBatchSize, default 1) on Upgrade Agents…, off
by default. It plans as a run's Stagger does: batches evenly
spaced over the spread, the first at once, the last when it ends, in a shuffled order,
over the devices actually queued, so those left out don't leave gaps.
- Each upgrade keeps its earliest start in the database, so a restart loses nothing. A batch goes together when it is due, whatever its size; each agent still waits its random 0–15 seconds.
- A device offline at its turn upgrades when it returns, through the paced batches, so a crowd coming back never starts at once. The 7 days before a queued upgrade expires still count from the request.
- A device waiting counts as having an open upgrade, and the upgrades table shows
when it starts. Cancel stops one. Cancel Waiting under Settings → Agent
Upgrades (
POST /api/agent-upgrades/cancel-waiting, devices.manage, audited, within the caller's device scope) stops all that have not been sent. - Roll backs and Automatic Upgrades don't spread: a roll back is usually wanted now, and Automatic Upgrades use the paced batches.
Automatic Upgrades (off by default) keep online devices outside the excluded groups on the newest version held for their platform, through the same paced batches. They never go to an older version and never retry a version that already failed or rolled back on that device.
| Setting | Default | Range |
|---|---|---|
| AutomaticUpgrades | off | |
| StartWithinMinutes | 3 | 1–30 |
| HealthDeadlineMinutes | 10 | 2–60 (the watchdog keeps the new version only when it reports healthy in time) |
| ExcludedGroupIds | none | existing groups; nested members are excluded too |
| KeepVersions | 5 | 2–50 |
Device History shows agent-upgraded (1.4.0 → 1.5.0),
agent-rolled-back (an operator's roll back, or the watchdog undoing an
upgrade, with its reason) and agent-upgrade-failed (with the reason).
With several replicas, the upgrade scheduler runs where the schedules do
(SCHEDULE_WORKER=1), and every replica keeps its own catalog copies. Without
a shared data volume, a replica only serves versions it has itself carried, so
turn on S3 agent offload (or share DATA_PATH) to keep older versions
reachable. AGENT_CATALOG_SYNC=0 turns the catalog import off.
Device files
A device's Files tab browses its disk live, like Explorer in the browser:
drives, folders, a typed path (%TEMP% and other variables expand on the
device), and a filter on the folder's names. It needs the device online. S3 plays
no part (beyond Send from S3 and Upload to S3): files go straight between
the browser and the device, and nothing stays on the server.
| Action | Notes |
|---|---|
| Open | Text files up to 5 MB open in the editor; anything else offers Download. |
| Edit and Save | A save writes back the encoding and line endings the file had, unless you pick others. A file changed on the device since it was opened is not overwritten: Reload or Overwrite. |
| New File, New Folder, Rename | Never over something already there. |
| Upload | Files, or a whole folder with its structure, from the menu or by dropping them on the list. What is already there asks Replace or Skip. An upload lands only once all of it arrived; cancelled or broken, it leaves nothing. |
| Download | One file as itself; a folder or several chosen entries as a zip named HOST.Folder.yyyy.MM.dd.HHmmss.zip (UTC). The browser saves it straight to disk, so size isn't limited by memory. A locked file doesn't end a zip: it is listed in ExecuteR.Skipped.txt inside. |
| Delete | Each entry on its own, saying which failed and why. A folder goes with everything in it, and a folder or several entries ask for the device's name typed. A drive's root is refused. Links are removed, never followed. |
| Upload to S3 | The agent sends the chosen files and folders up to S3 under uploads/devices/<hostname>/, to keep them; Uploads opens that folder. See Device uploads to S3. |
Permissions. files.browse lists, opens and downloads. files.manage changes
things. Admin and Operator hold both; Viewer neither. Device scope applies.
Send from S3 on the same tab needs files.send, as before.
Audit. Opening, downloading and every change go on the audit trail (category
files) with who, the path and, for uploads and saves, the SHA-256. Lists aren't
audited, and a file's text never is.
On the device. Everything runs as the agent's service account. AllowFileAccess
(policy, registry or the ALLOWFILEACCESS MSI property; on by default) refuses it
all locally, whatever the server asks. Script file delivery isn't affected.
How bytes move. Core NATS, from whichever server node holds the browser's request, so it works across replicas without shared storage and needs nothing new from the agent's connection. A transfer goes in 256 KB frames with at most 2 MB unacknowledged: a slow browser slows the device down, and nothing queues on the bus. Silence for 2 minutes ends a transfer. The agent moves 4 files at once and answers busy beyond that.
Agents below 1.2.0 don't know about this: the tab says the device did not answer. Upgrade the agent.
Reverse proxies. Uploads have no size limit on the server, so a proxy's limit
is the one that applies, and nginx's request buffering holds an upload back until
all of it reached the proxy. The nginx sample turns both off for
device routes. Check client_max_body_size or its equivalent on your own edge.
Device registry
A Windows device's Registry tab edits its registry live, like regedit in the
browser: a key tree on the left (loaded as you open it), the key's values on the
right (sortable by name, type and data), a path box with a breadcrumb above, and a
64-Bit / 32-Bit switch (32-bit is what 32-bit programs see, WOW6432Node). The
tab shows on Windows devices only (Windows PE included) and needs the device online.
| Action | Notes |
|---|---|
| New Key, Rename, Delete | A new key is never made over one already there; a key's parents are created with it. Delete takes the key with everything below it, and asks for the device's name typed when it has subkeys. A hive can't be deleted or renamed. |
| New Value, Edit, Rename, Delete | REG_SZ and REG_EXPAND_SZ as text (variables stay unexpanded), REG_MULTI_SZ one string per line, REG_DWORD and REG_QWORD in decimal or hex, REG_BINARY as hex bytes. REG_NONE and the rarer types (REG_LINK, REG_RESOURCE_LIST, …) show as hex, read-only; they rename and delete like any other. A rename never overwrites a value already there. |
| Export | The key and everything below it as a regedit .reg file (version 5.00, UTF-16 LE), named HOST.Key.yyyy.MM.dd.HHmmss.reg (UTC). A subkey the agent may not read is noted as a comment, so the file still imports. |
| Import | A .reg file or pasted text. The server reads it first and shows what it would do (keys created and deleted, values set and deleted, and the lines it can't read) before anything is applied; the device then applies it in order and reports each line that failed. |
Paths. The path box (and every API route) takes a key in any of the forms people
paste, and turns it into one: HKEY_LOCAL_MACHINE\SOFTWARE\Contoso.
| You type | It means |
|---|---|
HKLM\SOFTWARE\Contoso, hklm\software\contoso |
Short hive names (HKLM, HKCU, HKU, HKCR, HKCC), any case |
HKEY_LOCAL_MACHINE\SOFTWARE\Contoso |
Long hive names |
HKLM:\SOFTWARE\Contoso, HKCU:, HKLM:SOFTWARE |
PowerShell drives |
Registry::HKEY_LOCAL_MACHINE\SOFTWARE, Microsoft.PowerShell.Core\Registry::HKLM\SOFTWARE |
PowerShell provider paths |
Computer\HKEY_LOCAL_MACHINE\SOFTWARE |
regedit's address bar |
HKLM/SOFTWARE/Contoso |
Forward slashes, when the path has no backslash at all (with one, a slash belongs to a key name, as in HKCR\MIME\Database\Content Type\text/html) |
"HKLM\SOFTWARE\Contoso\", [HKLM\SOFTWARE] |
Quotes, brackets, and leading, trailing or doubled backslashes are dropped |
HKEY_CURRENT_USER is the hive of the person signed in at the device's console
(HKEY_USERS\<their SID>, found from the active console session), never the agent's
own: the agent runs as LocalSystem, whose HKCU nobody means. With nobody signed in,
HKCU says so and the other hives work as usual. The tab names whose hive it is.
HKEY_CLASSES_ROOT is the machine's merged view as LocalSystem sees it.
Import format. Windows Registry Editor Version 5.00 (regedit's UTF-16 LE with a
byte order mark, or UTF-8) and REGEDIT4 (ANSI; its hex(2) and hex(7) bytes are
converted to Unicode). Read: [key] (created when missing), [-key] (deleted with
everything below it), "name"="string", @= (the default value), "name"=- (deleted),
dword:, hex:, hex(0) to hex(b) and any other type number (hex(2) expand
string, hex(7) multi-string, hex(b) QWORD), hex continued over lines ending in
\, \\ and \" in quoted strings, and ; comments. A file without the header is
refused whole; a line that can't be read is listed with its number and skipped, and
values under it wait for the next good [key]. Keys in a file take every path form
above. Up to 16 MB at once.
Permissions. registry.view browses and exports; registry.edit changes,
renames, deletes and imports (the preview included). Admin and Operator hold both,
Help Desk registry.view, Viewer neither. Device scope applies. Neither is file
access: files.* grants nothing here, and the other way round.
Audit. Every change goes on the audit trail (category registry) with who, the
key, the 64- or 32-bit view, the value name, its type and the data before and after
(each cut at 400 characters; nothing is masked). An import writes a summary row and
one row per change it made, with its line. Exports are audited; browsing isn't.
On the device. Everything runs as the agent's service account (LocalSystem), so
access denied means LocalSystem may not, and says so. AllowRegistryAccess (policy,
an Agent Settings profile to switch it in bulk,
registry or the ALLOWREGISTRYACCESS MSI property; on by default; see the
ADMX) refuses it all locally, whatever the server asks.
Linux and macOS agents answer that the registry is Windows only.
How it travels. The registry's requests ride the file browser's request path (Core NATS, any server node, the same agent subscription), so there is no new subject or permission on the agent's connection. A listing pages subkeys 1,000 at a time and carries each value's first 2 KB; editing a longer value fetches it whole (up to 512 KB). Export and import stream like file transfers.
Agents from before the registry editor answer Unsupported, Requires a newer agent. Upgrade the agent.
Remote View
Remote View on a device's page shows its live screen in the browser, with keyboard and mouse (Control) or without (View Only). It works at the sign-in, lock and UAC screens, when nobody is signed in, and in Windows PE.
How it works. Input, cursor and clipboard are RDP; the picture is H.264
video where the device can encode it (below), RDP bitmaps otherwise. The console runs Devolutions'
IronRDP web client (@devolutions/iron-remote-desktop with the
@devolutions/iron-remote-desktop-rdp WASM backend, loaded only on this page),
which connects over a WebSocket using RDCleanPath. On the device the agent
starts the screen host, ExecuteR-Screen.exe (beside the agent; the RDP
server, written in Rust), and pipes its stdin/stdout to the server over the
agent's existing NATS connection. Nothing new is opened on the device: no RDP
port, no listener.
browser (IronRDP, WASM) ─wss─► server /api/devices/<id>/screen/<session>/socket
─NATS (agent.<id>.command.screen.*, agent.<id>.screen.<stream>)─► agent
─stdin/stdout─► ExecuteR-Screen serve --stdio [--view-only] [--monitor n]
- Remote View asks the server for a session (
POST /api/devices/{id}/screen): permission, device scope, the device online and its agent reporting Remote View. The answer carries a one-time ticket: 60 seconds, this user, this session, spent on first use. - The client opens the session's socket with the console's sign-in cookie and the ticket. The ticket never reaches the device; the client's RDCleanPath auth token is just the session id.
- The server asks the agent to open a stream. The agent settles consent (below), starts the screen host and answers; only then do bytes flow.
- Bytes travel in chunks of at most 64 KB, each direction with a window of unacknowledged bytes (1 MB screen to browser, 256 KB the other way): a slow browser slows the screen host down, and memory stays bounded on every hop. Both ends acknowledge every 15 seconds and give up after 60 seconds of silence; the server pings the WebSocket every 20 seconds.
- A dropped connection reconnects with a new ticket (the console retries a few times); picking another monitor does the same. Neither asks the user again. A session nobody reconnects to ends after 90 seconds; any session after 8 hours.
Permissions. screen.view opens View Only; screen.control opens Control
(and View Only). Admin, Operator and Help Desk hold both; Viewer and Script
Author neither. Device scope applies. View Only is enforced by the screen host
(--view-only): RDP is opaque to the server, so input is not filtered there.
A device runs at most two sessions at once.
Device policy (GPO, an Agent Settings profile, registry, or the MSI properties; a profile change applies at once, the banner after a restart):
| Policy | Registry value | Default |
|---|---|---|
| Allow Remote View | AllowRemoteView |
on |
| Notify the signed-in user | RemoteViewNotify |
on |
| Ask the signed-in user first | RemoteViewAskFirst |
off |
| Time to answer (10–120 s) | RemoteViewAskTimeout |
30 |
| Allow when nobody is signed in | RemoteViewAllowUnattended |
on |
| Show the Being Viewed banner | RemoteViewBanner |
off |
- Someone signed in at the console: Ask First shows a Yes/No message naming the operator (no answer is No, and a locked session can't answer); otherwise Notify tells them a session is starting; otherwise nothing.
- Nobody signed in (the sign-in screen): allowed only with unattended.
- Windows PE: always allowed, never asks (nobody signs in there).
- Linux/macOS: no prompt yet, so Ask First refuses there; unattended applies.
The defaults suit a managed fleet's break-fix work: the user is told, sessions at
the sign-in screen work, and every session is audited. Turn Ask First on for
devices people work at, or AllowRemoteView off where nobody may look.
Audit (category screen): started (who, device, mode=control|view-only,
consent=accepted|notified|silent|unattended|winpe, monitor), refused (declined,
timed out, policy, unavailable) and ended (duration, reason; reason=Stopped by the user at the device. when the banner's Stop ended it). The device page shows
Being Viewed while a session is open.
Agents. The agent probes the screen host at start (ExecuteR-Screen probe) and
reports it in the inventory; an older agent shows Unsupported (Requires a newer
agent), a device without the screen host or where capture fails shows why.
Windows notes.
- Ctrl+Alt+Del goes as the RDP key sequence; the screen host turns it into
SendSAS. Windows only accepts a SAS from a service when the Software Secure Attention Sequence policy allows it: Computer Configuration › Administrative Templates › Windows Components › Windows Logon Options › Disable or enable software Secure Attention Sequence = Services (or Services and Ease of Access applications); registryHKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\SoftwareSASGeneration= 1 or 3. - Remote View shows the physical console session. A fast user switch or an RDP connection that takes the console ends the session ("The console session changed."); reconnect to follow it.
- When the host can't open the input desktop, the console shows Secure Screen and keeps the session open.
- Clipboard (Windows, control sessions): copy text on either side and paste on the other, up to 1 MiB; no files or images. The browser asks once for clipboard access (Chromium; HTTPS only). View-only sessions have no clipboard.
- Windows PE: the portable package carries the screen host; the agent's service starts it in the console session, like on full Windows.
- Video. On Windows with Media Foundation the screen goes as H.264: the GPU's encoder when there is one (NVIDIA, Intel, AMD), else Microsoft's software encoder; the browser decodes it with WebCodecs (in hardware where it can). The toolbar shows H.264 or H.264 GPU (hover for the encoder). Only changes are sent, at up to 30 fps and about 0.1 bit per pixel per frame (about 6 Mbit/s at most for a busy 1080p screen, next to nothing for a still one). It travels in the same socket, so nothing else is opened. Windows PE and Server Core have no encoder, browsers without WebCodecs (or over plain HTTP) can't decode it, and older agents don't offer it: those sessions use RDP bitmaps (RemoteFX) at up to 30 fps, as does any session whose encoder or decoder fails.
Security.
- Consent stays in the service. Ask First and Notify are
WTSSendMessagecalls from the agent service itself: no helper in the user's session, no IPC. The only helper there is the optional Being Viewed banner, which runs as the user and can only ask to stop a session it shows. - Only the installed binary runs. The screen host is started by full path from
the agent's own folder (
lpApplicationName, never a search path, never a temp or profile copy). When it will run as SYSTEM, the agent refuses a folder or file that ordinary users (Users, Authenticated Users, Everyone, Interactive) may write to; the MSI installs it under Program Files. - Three pipes, nothing else. stdin/stdout/stderr are anonymous pipes, and
PROC_THREAD_ATTRIBUTE_HANDLE_LISTlimits inheritance to exactly those three handles. No named pipes, no sockets. - It never outlives the agent. The host runs in a Job object with
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSEandJOB_OBJECT_LIMIT_DIE_ON_UNHANDLED_EXCEPTION; the agent also closes it on session end, idle, console switch and shutdown. - No secrets on its command line. The one-time ticket is checked by the server before any byte reaches the agent; the screen host never sees it.
- Console switches. A session is refused when the active console session changes between consent and launch, and ended when it changes later.
- Session 0 to the console. From the LocalSystem service the host starts as
SYSTEM in the active console session (
DuplicateTokenEx,SetTokenInformation(TokenSessionId),CreateProcessAsUser,winsta0\default, no window), so it can show and drive the sign-in and UAC screens. - The socket. Sign-in cookie and one-time ticket together, and a browser
Originmust name this site, so another site can't open it with the cookie alone.
Reverse proxies. The socket lives under /api/devices/, so a proxy route for
that prefix carries it: it needs the WebSocket upgrade headers and a read timeout
above the 20-second pings (the nginx sample's ^~ /api/devices/
with proxy_read_timeout 300s does). On your own nginx, make sure that location
(or /api/) forwards Upgrade and Connection:
location ^~ /api/devices/ {
proxy_pass http://executer_api;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 300s;
proxy_buffering off;
proxy_request_buffering off;
}
(With proxy_set_header inside a location, repeat the Host and X-Forwarded-*
headers there too; see the note in the sample.) Sessions live on the server node
holding the socket, like remote shells.
Packaging. scripts/Package-Agent.ps1 builds src/ScreenHost with
cargo build --release --target x86_64-pc-windows-msvc (scripts/Build-ScreenHost.ps1)
and puts ExecuteR-Screen.exe in the win-x64 zip (which Windows PE and agent
upgrades use) and the MSI; CI installs Rust first (scripts/Install-Rust.ps1).
Without src/ScreenHost or cargo it packages without it. win-arm64, Linux and
macOS screen hosts are not packaged yet: those devices report Remote View as
unavailable. It also publishes the Being Viewed banner (src/Agent.Banner,
ExecuteR-Banner.exe: plain Win32 published with Native AOT, one native exe of
about 1.6 MB with no .NET runtime, icon assets/icons/banner.ico) into every
Windows zip and the MSI. Native AOT links with MSVC: Visual Studio Build Tools,
Desktop development with C++, plus the ARM64 build tools for win-arm64 (which
cross-compiles on x64). The CI windows-host runner needs them installed. For
an architecture without them the script warns and packages a trimmed
self-contained single file (about 11 MB, slower to start) instead.
Being Viewed banner
Optional, off by default (RemoteViewBanner: GPO Remote View: show the Being
Viewed banner, registry, or MSI REMOTEVIEWBANNER=1; read at service start). While
a Remote View session is open on a Windows device with someone signed in at the
console, that person sees a small banner at the top centre of their screen:
Being Viewed by operator · View Only or · Control, and Stop.
- Behaviour. Always on top, never takes focus (a tool window that does not activate), can be dragged anywhere, follows the monitor's DPI and the user's light/dark app theme (high contrast too). One row per session (a device runs at most two). The operator is the console user's display name. Stop is a real button, named for its session ("Stop Ann's Remote View"), so screen readers and other assistive technology can find and press it without the banner taking focus. Plain Win32 and Native AOT: it is on screen within about 0.1 s of starting.
- Stop ends that session for good: the agent stops its streams, tells the server
the session is over, and refuses a reconnect of it. The server ends the session
with its own wording (
Stopped by the user at the device.), auditsendedwith that reason, and the console shows it. - When it runs. The agent starts the banner when a session opens (the first
stream is up), keeps it while the session reconnects (15 s), and ends it when the
session ends, the user signs out or locks into another session, the console
session switches (fast user switching, RDP taking the console), or the policy is
off. A user who signs in during a session gets their own. A banner that goes away
by itself (ended in Task Manager) is started again after 30 s. Never at the
sign-in screen (nobody signed in), never in Windows PE (the portable install
removes
ExecuteR-Banner.exethere), never on Linux/macOS, never for an agent run in the foreground. - Console. The Remote View page shows Banner On when the device will show it (policy on and the banner present).
Security model (the banner is the only Remote View piece in the user's session, so it is treated as untrusted):
- The user's own token, never SYSTEM. The service starts
ExecuteR-Banner.exewithWTSQueryUserTokenfor the console session: under UAC that is the filtered, non-elevated token; the linked (elevated) token is never asked for. The manifest isasInvoker. It runs on the user's own desktop (winsta0\default, never Winlogon), with the user's environment block (never the service's), no inherited handles, image-load mitigations (no remote or low-label images, System32 first), in a kill-on-close job, and by full path from the agent's folder, which (like the file) must not be writable by ordinary users, or the banner is not used. - DLL loading. The banner's first act is
SetDefaultDllDirectories(System32 | application folder)andSetDllDirectory(""); its P/Invokes search System32 only. - One pipe, per launch. Before starting the banner the service creates
\\.\pipe\ExecuteR-Banner-<32 hex>, a new random nonce each launch passed on the banner's command line (it avoids squatting; it is not a secret from that user), as the first and only instance, owned by SYSTEM, with a protected ACL: SYSTEM full, the session user's SID read/write (no new instances, no ACL changes), network logons denied. - The kernel says who connected. The service accepts the client only when
GetNamedPipeClientProcessIdis the process it just started andGetNamedPipeClientSessionIdits console session; anything else is dropped and the banner killed. The banner, in turn, talks only to a pipe owned by SYSTEM and served from session 0, and connects at Identification level (the service cannot act as the user). - Display data out, one request in. The service sends only the sessions to show
(session id, operator display name cleaned of control and bidi characters, mode).
The banner may send exactly
stop <session id>, lines of at most 64 bytes; it is honoured only for a session the banner is showing, open in that banner's console session. Anything else (another verb, an overlong line, invalid UTF-8) ends the banner.
S3 file delivery
S3 works out of the box: the server runs a built-in store, on by default, with nothing to fill in. Put files in from S3 Files, bind them to scripts, and send them from Send from S3 on a device's Files tab. Settings → Storage switches to an external S3-compatible store (AWS S3, MinIO, Backblaze B2) instead. Credentials stay on the server either way — a device only ever sees a short-lived URL.
Built-in store. Silo, the community-maintained fork of MinIO, run by the server as a separate process.
- It listens on
127.0.0.1only (S3_EMBEDDED_PORT, 9199; a free port when that one is taken), with its web console off. Nothing but the server can reach it. - The server generates its credentials once and keeps them encrypted in the database. They are never shown or logged, and reach the store through its environment, which otherwise holds none of the server's own settings.
- Its one bucket,
executer, is created when it first starts. Its files are inobject-storebeside the database (S3_EMBEDDED_DATA):/data/object-storein the container,<data>/db/object-storein the standalone server. Back this folder up with the database, with the server stopped: a copy taken while it runs can catch a file half written. - It is watched and restarted, with a delay growing from 2 seconds to 5 minutes while it keeps failing, and ends with the server. A store left behind by a server that was killed is ended by the next start. A store that can't run is a status on Settings → Storage and a 503 from S3's routes, never a reason for the server to stop.
S3_EMBEDDED=0removes it altogether, andS3_EMBEDDED_PROGRAMnames your own build. The packages and the backend image carry it inobject-store/beside the server, pinned inbuild/object-store.jsonand checked against that SHA-256 when built; it adds about 100 MB. It is AGPL-3.0 and is not linked into ExecuteR: see the notices. Each release carries its exact source.
Where presigned URLs lead. Devices always get an S3 presigned URL, signed with
credentials they never see, and the store itself checks it. An external store's lead
straight to that store, wherever it is: with Wasabi, for example, they are
https://s3.wasabisys.com/… and devices download from Wasabi, never through this
server, so devices need to reach that address. The presigned download step of
Test Connection only proves the server can.
Only the server can reach the built-in store, so its URLs lead through the server, which passes on one object of its one bucket, GET only, with the rest left to the store:
/api/s3/store/executer/<key>?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Signature=…
The address follows the same rule as everything else the server hands out:
PUBLIC_SERVER_URL when set. Otherwise the URL is only the path, and the agent resolves
it against the server URL it already reaches this server on, so no configuration is
needed behind a reverse proxy, and a scheduled job, with no request to derive an address
from, works the same. A presigned URL is bound to a host, so these are signed for one
fixed name that the server gives the store whatever address the request arrived on,
which keeps them valid through any proxy. Anyone holding one can GET that one object
until it ends, with no sign-in, and nothing else; through the server it always downloads,
and never renders on the console's origin. Agents below 1.2.0 don't resolve paths: set
PUBLIC_SERVER_URL, or upgrade them.
Which store. A server already set up for an external store keeps it on upgrade:
S3_ENABLED=1, or a bucket saved from the console. Anything else gets the built-in
store. Switching keeps both stores' files, and each shows only its own. Nothing is
copied between them. Agent offload works with either store; with the built-in one the
links stay on this server.
Replicas. Each replica running its own store would hold different files, so the
Swarm and Kubernetes stacks run one store as a service on the
internal network and name it to every backend: S3_EMBEDDED_URL,
S3_EMBEDDED_ACCESS_KEY and S3_EMBEDDED_SECRET_KEY (both required: generate them).
Links still lead to whichever replica takes the request. That service is one replica
on one volume, so for redundancy use an external store.
S3 Files. Upload files or whole folders, from the menu or by dropping them on the
list; create folders; download; and delete, a folder with everything in it. It works
the same on an external store, through the server. What is already there asks
Replace or Skip, and a broken upload stores nothing. Parts of 16 MB go straight
to the store, so size isn't limited by the server's memory. Changing the bucket needs
scripts.manage and goes on the audit trail (category files).
Browse and search. S3 Files, and the Browse S3 button on a script's file
bindings and on Send from S3: walk the bucket level by level, or search names at any
depth under the current prefix. S3 can only list, so a search reads up to 10,000 keys at
a time, and Keep Searching reads on from there. Browsing needs scripts.manage or
files.send.
Script file bindings download S3 files and folders to the device before a
script runs, with progress in the job output, and hand them to the script as
$Files and $FilesRoot: see Script file bindings.
Configured and tested from the UI. An external store's settings saved in the
browser are stored in the database (the secret key encrypted at rest with Data
Protection) and override the S3_* environment variables, which remain the bootstrap
defaults. The Test Connection button runs a real round-trip on either store and
reports each step separately, so a partial failure is obvious:
| Step | What it proves |
|---|---|
| bucket | Credentials valid and the bucket reachable |
| write | The key has PutObject |
| read | Content round-trips intact |
| presigned download | The signed URL is fetchable — this is the mechanism agents use, and the step that catches an endpoint reachable from the backend but not from devices |
| delete | The key can clean up after itself |
A probe object is written under executer-connectivity-check/ and deleted
again. Only a fully passing test of an external store records lastTestUtc, and
agent offload to an external store cannot be enabled until one has passed.
sequenceDiagram
participant U as "Operator"
participant API as "Backend"
participant S3 as "S3 store"
participant N as "NATS / JetStream"
participant A as "Agent"
U->>API: "POST /api/devices/{id}/files (objectKey, destination, sha256?)"
API->>S3: "presign GET (expires in S3_PRESIGN_EXPIRY_SECONDS)"
S3-->>API: "signed URL"
API->>N: "durable file command (URL, destination, hash)"
N->>A: "command.file"
A->>A: "already have it? (hash, then ETag)"
A->>S3: "GET signed URL (If-None-Match when cached)"
S3-->>A: "200 body, or 304 Not Modified"
A->>N: "progress, then Succeeded"
N->>API: "persist, relay to browser"
Downloads are skipped when nothing changed, in two escalating steps:
- Hash match, no request at all. If the destination already exists and the
caller supplied
sha256, the agent hashes the local file; if it matches, the job succeeds immediately with "Already up to date". - Let S3 decide. Otherwise the agent sends the ETag it stored last time as
If-None-Match. An unchanged object returns 304 Not Modified and costs no transfer; a changed object returns the new body.
The agent keeps a small local cache (destination path → ETag, SHA-256, size) in its SQLite store, so this survives restarts. Every completed download is hashed regardless — verifying the transfer when an expected hash was given, and seeding the cache when it was not. Writes are atomic (temp file, then move), so a failed or interrupted download never leaves a half-written file in place.
Configuration of an external store (the built-in one needs none):
S3_ENABLED=1
S3_ENDPOINT=https://s3.example.com # blank for AWS
S3_REGION=us-east-1
S3_BUCKET=executer-payloads
S3_ACCESS_KEY=...
S3_SECRET_KEY=...
S3_FORCE_PATH_STYLE=1 # 1 for MinIO and most self-hosted
S3_PRESIGN_EXPIRY_SECONDS=900
Script file bindings
A script can have files and folders from S3 downloaded to the device before it runs, and hand them to the script ready to use. They are set on the script's Files tab.
Choosing. Add From S3 opens the S3 browser with a tick on every file and
folder: tick as many as you like across folders and searches (breadcrumb and search
work as on S3 Files), then Add. A folder downloads recursively and keeps its
structure. Each selection gets a Name, from the file or folder name made into a
PowerShell / Bash identifier (setup-v2.msi → setupV2, 7zip/ → _7zip), numbered
when taken, and editable; names are unique, ignoring case. Add Manually adds a row
to type a key into. A run can use other files: Run Script › Review › Files › Change
for This Run picks them with the same browser, keeping the script's Download To and
Clean Up Downloads (it needs scripts.manage or files.send, and the script itself is
not changed).
Where they land. Everything goes under the script's Download To folder, default
$ExecuteRJobDir\Files (a Files folder in the job folder). Each selection lands at
its Path inside it: empty is its own name ($ExecuteRJobDir\Files\setup.msi), a
relative path is a sub-path (installers\setup.msi), and an absolute path (or one
starting with a variable that expands to one) is used as is, which is how bindings made
before Download To existed keep working. Download To and paths expand on the device:
| Form | Example |
|---|---|
| ExecuteR's variables | $ExecuteRJobDir, $ExecuteRAgentDir, $ExecuteRAgentPath (also ${…}, and their environment names EXECUTER_JOB_DIR, EXECUTER_AGENT_DIR, EXECUTER_AGENT_PATH in any form below) |
| Environment variables | %ProgramData%, $env:ProgramData, ${env:ProgramData}; on Linux and macOS also $HOME, ${HOME} |
| PowerShell | $(…) and PowerShell's own variables, evaluated in a short-lived runspace that has ExecuteR's variables |
A variable the device does not define fails the job before the script runs (it never
becomes an empty string or a folder named %FOO%). On Linux and macOS \ becomes /,
so the default works there too. Download To must be absolute (or start with a variable),
and neither it nor a path may contain ..; a relative path, and every file of a folder,
must stay inside where it goes. Missing folders are created; they inherit their parent's
permissions, so inside the job folder they are locked down like it. The console shows
the variables on hover.
Progress in the job output. The download is visible in the job's output while it runs (Information lines, and the job's progress bar):
Downloading 1 file, 1 folder (214 objects, 412.0 MB) to C:\Windows\SystemTemp\ExecuteR\3f2c…\Files
Downloading 12/214: 41.3 MB / 412.0 MB (10%), 10.4 MB/s — setup.msi (+3)
…
Downloaded Installer: setup.msi (380.2 MB) → C:\Windows\SystemTemp\ExecuteR\3f2c…\Files\setup.msi
Downloaded Tools: 213 files (31.8 MB) → C:\Windows\SystemTemp\ExecuteR\3f2c…\Files\Tools
Downloaded 1 file, 1 folder, 412.0 MB in 38 s (10.8 MB/s).
A progress line comes at each 10% and at least every 5 seconds while it runs, never more than one a second; the progress bar moves at most once a second. Retries show as warnings.
How it downloads. The server lists and presigns exactly the selected keys (a folder:
everything under its prefix, at most 2,000 objects, more is refused rather than cut
short) when the job is sent, so agents never hold S3 credentials; with the built-in
store the links lead through the server, as above. Four files download at once,
streamed to a temporary file beside the target and moved into place when complete.
Each is checked against the size the store listed and, when the store's ETag is a plain
MD5 (a single-part upload, not KMS-encrypted), against it. A server error, a dropped
connection or a mismatch is retried (3 attempts); a 403 or 404 is not. The job's
timeout and cancellation apply to the download. A failure fails the job before the
script runs, with the file named in the message, unless the selection has Continue
on Failure (a warning, and the script still runs: check $Files.Name.Exists). A
destination that is a variable or path the device can't use counts as a failure of that
selection.
In the script.
| Engine | Files | Download To |
|---|---|---|
| PowerShell 7 and PowerShell 5 | $Files.Name or $Files['Name']: a System.IO.FileInfo for a file, a System.IO.DirectoryInfo for a folder, in an ordered, case-insensitive dictionary |
$FilesRoot (a DirectoryInfo) |
| Bash | $Name (as before) and $EXECUTER_FILE_NAME (upper case): the path |
$EXECUTER_FILES_ROOT |
Start-Process msiexec -ArgumentList '/i', $Files.Installer.FullName, '/qn' -Wait
Get-ChildItem $Files.Tools -Recurse | Measure-Object Length -Sum
Clean Up Downloads (on by default) removes what the job downloaded when the run ends, whether it succeeded, failed, timed out or was cancelled, including a download that stopped half way. Only what this job wrote goes: files it created, then the folders it created once they are empty. Anything already in a chosen Download To stays, as does a file it replaced, and anything the script itself wrote. When everything is inside the job folder, Clean Up After Run removes it with the folder anyway. Scripts saved before Download To existed keep their downloads, as they did.
Agents older than this release take only absolute destinations: give them an absolute Path, or upgrade them.
Device uploads to S3
The other direction: a device sends files up to the chosen store (built-in or external), to grab logs, dumps or anything else, or to archive a folder. The file browser already reads files live; this keeps them.
ExecuteR-Agent upload <path|mask> [<path|mask> ...] [--recurse] [--flatten | --preserve]
[--dest <subfolder>] [--zip [name.zip]] [--overwrite] [--quiet]
<path|mask>: one or more files, folders, or masks in the last part of a path (C:\Logs\*.log,/var/log/app*.log).%VAR%expands everywhere ($VAR,${VAR}and~too on Linux and macOS, for a quoted argument); relative paths are from the current folder. A file named twice goes once.--recurse/-r: a folder or mask takes in every folder below it (a folder without it: only the files directly in it). Folders that are links are not followed.--preserve/-p(the default): names keep their path below the mask's folder, or below a folder's parent (C:\Logsuploads asLogs/…).--flatten/-f: file names only. A name already taken gets-2,-3… before its extension; every rename is reported (so are clashes between two inputs with--preserve).--dest/-d <subfolder>: the folder under the device's own; one or more segments, cleaned like every name. Default: when the server took the upload,yyyyMMdd-HHmmss(UTC).--zip/-z [name.zip]: everything into one zip first (names as above), and upload that: the archive use case. The name is the next argument when it is a bare file name ending in.zip(or--zip=name); otherwise<host>-<yyyyMMdd-HHmmss>.zip. The zip is made in a temporary folder and deleted after.--overwrite/-o: replace what is already there; without it a file whose key exists is skipped and reported.--quiet/-q: no progress or per-file lines; problems still go to stderr. Without it the console shows the files, bytes and a running total.- Exit codes:
0all uploaded,1refused (turned off, no store, over a limit, not an elevated administrator) or nothing uploaded,2the agent service is unreachable or not connected to the server,3some uploaded (others failed, were skipped as already there, or a path or mask found nothing).
Examples:
:: Grab the logs, folders kept, into a named folder.
"%ProgramFiles%\ExecuteR\Agent\ExecuteR-Agent.exe" upload "C:\ProgramData\MyApp\Logs\*.log" --recurse --dest ticket-4711
:: Archive a whole folder as one zip.
"%ProgramFiles%\ExecuteR\Agent\ExecuteR-Agent.exe" upload "C:\Windows\Panther" --recurse --zip panther.zip
sudo executer-agent upload /var/log/syslog '/var/log/app*.log' --flatten
From a script, use $ExecuteRAgentPath / EXECUTER_AGENT_PATH (see
Where scripts run).
Where it goes. uploads/devices/<hostname>/<dest or yyyyMMdd-HHmmss>/<names>.
The hostname is lower case, letters, digits, -, _ and . only (anything else
becomes -), at most 63 characters, the client id when nothing is left. The
server builds every key from the device's identity, never from the command
line: a name with .., ., a control character or a drive is refused, a
leading / or \ is dropped, and a device can write nowhere but below its
own folder. S3 opens a device's folder as /s3?prefix=uploads/devices/<hostname>/,
which Uploads on the device's Files tab does.
How. The CLI works out the paths and masks where it runs, then hands the
list to the running agent over the same local channel as run (the same
caller check: an elevated administrator, SYSTEM or root). The agent reads the
files as itself (sharing with whoever writes or deletes them, so a log being
written is read as it stands) and asks the server over its own NATS identity,
on the same request path as run (sealed and signed both ways for a device
that seals; the replies carry the presigned URLs):
- begin names every file and its size. The server checks the setting and
the limits, decides each key, checks which are already there (unless
--overwrite), audits the request (files/device-upload: device, source, local user, the job when the CLI runs in a PowerShell 5 or Bash job, every key and size) and answers with a grant sealed by the server, naming the device, the upload and its folder. - presign, per file, just before it is sent: a presigned
PUTfor exactly that key, valid forS3_PRESIGN_EXPIRY_SECONDS. Above 64 MB a file is a multipart upload in parts of 16 MB (larger when that would take more than 10,000 parts): the server starts it and hands out presignedUploadPartURLs eight at a time. - The agent
PUTs the bytes straight to an external store, or through the server's address to the built-in one (/api/s3/store/…, which takes a signedPUTof one object or one part and nothing else), over HTTPS and not over NATS. A part that fails is tried again twice. - complete: the server completes a multipart upload and checks the object's size against the size declared; anything else is removed.
- finish audits the outcome (
device-upload-finished: uploaded, failed, skipped, bytes, problems).
A file that can't be read, changes size while it is sent, or is refused is reported and skipped; the rest carry on. Presigned URLs are never logged, by the agent or the server. Every later step must carry the begin's grant and stay in its folder, so neither another device's grant nor a made-up key gets a URL.
From the console. Upload to S3 in the Actions menu of the device's
Files tab (files.browse, and the device's AllowFileAccess) sends the chosen
files and folders (folders with everything in them, paths kept); Upload Logs to
S3 on its Logs tab (devices.logs) zips the agent's and the watchdog's log
files and sends that. Both take the same path as the CLI, answer once the server
has taken the upload (with Open in S3), and carry on in the background; the
console's request is audited too (files / upload-to-s3).
Settings and limits (Settings → Storage → Device Uploads, checked by the server for every upload):
| Setting | Default | |
|---|---|---|
| Allow Device Uploads | on | Off refuses every upload, and one under way gets no more links |
| Files per Upload | 1,000 | At most 5,000 (one request names them all); zip more with --zip |
| One File | 5 GB | Up to 5 TB, S3's own limit; a larger file is refused, the rest still go |
| One Upload | 20 GB | The total of one upload; above it the whole upload is refused |
With no store configured or running the CLI exits 1 with the reason (No S3 store to upload to: S3 is not configured.).
CI/CD and GITEA_* variables
Images are published to Gitea's own container registry, which lives on the
Gitea host itself — <gitea-host>/<owner>/executer-backend and
…/executer-webui. No registry configuration is required: Gitea Actions
injects a GITEA_TOKEN per run that the registry accepts as the triggering
actor's password, and the host is derived from the instance URL.
Seed the remaining repository secrets and variables once (idempotent; never prints values):
$env:GITEA_URL='https://prod.git.gracesolution.info'; $env:GITEA_API_TOKEN='<token>'
./scripts/Initialize-GiteaSecrets.ps1
It derives owner/repo from the git remote, reads values from .env and
secrets/nats, and writes the NATS signing seed, admin password and OIDC/S3
secrets, plus REGISTRY and SERVER_URL variables. The token needs
repository admin scope.
To publish somewhere other than this Gitea instance, add -ExternalRegistry
(with -RegistryUsername/-RegistryPassword); CI then uses those credentials
instead of the built-in token.
Two Gitea API quirks worth knowing if you script against it yourself: the
secrets endpoint takes {"data": …} while variables take {"value": …}, and
secret names may not begin with GITEA_ or GITHUB_.
Pulling images on a deployment host only needs credentials when the repository
is private — set REGISTRY_USERNAME and REGISTRY_TOKEN in .env and
deploy.sh logs in before pulling.
Gitea Actions workflows live in .gitea/workflows:
- Pull request to
main— restore, build, unit + integration tests, WebUI check. No image push, no release. - Push to
dev— build + test, agent binaries for every platform (win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64) + MSI, the standalone server (win-x64 + MSI, linux-x64), backend/webui images taggeddevand<version>-dev(X.Y.Z.N-dev). All binaries upload as thebinariesrun artifact. - Push to
main— the same set, images tagged<version>(X.Y.Z.N) andlatest. When the commits since the last release call for one (a fix, feat or breaking change),release.ymlreleases it instead: every binary asX.Y.Z, the tagvX.Y.Z, a Gitea release with the notes, every agent ZIP, both MSIs, the Server ZIPs and checksums, and the images taggedX.Y.Zandlatest(see Versioning).
Scripts discover context from optional environment variables and fall back gracefully when run locally:
GITEA_URL GITEA_TOKEN GITEA_OWNER GITEA_REPOSITORY GITEA_SHA GITEA_REF
GITEA_REF_NAME GITEA_RUN_NUMBER GITEA_ACTOR GITEA_CONTAINER_REGISTRY
GITEA_CONTAINER_REGISTRY_USERNAME GITEA_CONTAINER_REGISTRY_PASSWORD
Token values are never printed. dev is not merged into main automatically.
Versioning
Semantic versions from git tags. Every artifact of a build shares one version —
the agent, the watchdog, the server, both MSIs, the images and the console
footer — computed once (scripts/Get-Version.ps1) and handed to every step.
| Build | Version | Example |
|---|---|---|
| A release | X.Y.Z, from its tag vX.Y.Z |
1.4.0 |
| Any other build | X.Y.Z.N: N commits after release X.Y.Z |
1.4.0.7 |
| Before the first release tag | 0.0.0.N (commits in the history) |
0.0.0.253 |
| No version handed in and no git | 0.0.0.0, the development version |
Numbers only, no -dev or -rc labels, so the same version is a valid
assembly, file and MSI version. A build stops when the major or minor is over
255, another field over 65535, or the major is 2000 or more (a calendar
version). Binaries carry 1.4.0.7+1a2b3c4 (the short commit, .dirty for a
local build with changes) as their informational version; the version they
report drops the +….
One order everywhere. AgentVersions (Shared.Contracts) compares field by
field, a missing fourth field is 0 and +metadata is ignored. The calendar-era
versions before 1.0.0 (2026.10.10.0140) are older than every semantic
version; 0.0.0.0 and anything unparseable are oldest. The server's catalog
and upgrades, the agent, the watchdog, the console, agentVersion group rules
(>, <; 1.4 means 1.4.0) and the MSIs all use it.
Releases come from conventional commits. On a push to main,
release.yml runs semantic-release in dry-run mode
(scripts/Get-NextRelease.ps1, pinned in build/release) over the commits
since the last release tag: fix/perf bump the patch, feat the minor, a
BREAKING CHANGE: footer or type!: the major. Only docs, test, chore,
refactor, ci, build… release nothing; CI's X.Y.Z.N build stands. When a
release is due, the run builds every binary as X.Y.Z,
scripts/Publish-Release.ps1 tags the commit vX.Y.Z and creates the Gitea
release "ExecuteR X.Y.Z" with the generated notes and the artifacts, and the
images are pushed as X.Y.Z and latest. CI builds that commit as X.Y.Z
too (the same dry run) and leaves its images to the release. A re-run of a
released commit publishes the same version again; a version never names a
second commit.
./scripts/Get-Version.ps1 # this tree: 1.4.0.7
./scripts/Get-Version.ps1 -Format FileVersion # four fields: 1.4.0.7, or 1.4.0.0 for 1.4.0
./scripts/Get-NextRelease.ps1 # what main would release now (main, node)
./scripts/tests/Test-Versioning.ps1 # the rules and the numbering, in a scratch repository
Seeding (once). The calendar tags (v2026.10.10.0140) never count: release
tags have a 1–3 digit major. Before the first semantic release:
- Tag the last calendar-era release commit on
mainv0.1.0and push the tag (git tag v0.1.0 <commit>,git push origin v0.1.0). - The switch-over commit (
build(version)!: semantic versions from release tags) carriesBREAKING CHANGE:, so the first release after the seed is 1.0.0 (semantic-release takes 0.x plus a breaking change to 1.0.0). If the change is squash-merged, keep the footer in the squashed message.
Until the seed tag exists, builds are 0.0.0.N, release runs refuse ("No
release tag … is reachable") and CI warns. Seed before images built this way
reach a server: 0.0.0.N already sorts after every calendar version.
MSIs. The ProductVersion is the four-field version (1.4.0.0 for 1.4.0,
1.4.0.7 between releases); Programs and Features shows it, the comments show
ExecuteR Agent 1.4.0. Windows Installer compares only three fields and the
calendar-era MSIs carry 26.x, so each MSI removes every installed version and
its FindNewerRelease custom action first refuses a newer one, all four fields
and the era considered: A newer version of ExecuteR Agent, 1.5.0.0, is already
installed. ALLOWDOWNGRADE=1 installs an older version deliberately (an MSI
upgrade's rollback passes it); credentials and data stay either way. Upgrades
and repairs lay every file down (REINSTALLMODE=amus), because calendar-era
binaries carry file versions 2026.x. The agent MSI keeps a copy of itself
under %ProgramData%\ExecuteR\packages\<sha256>\ (the 3 most recently
installed, writable only by SYSTEM and Administrators) for that rollback.
Branding
Every Windows executable ExecuteR ships carries the product icon (Explorer,
Task Manager, Services) and a version resource (description, product,
company, copyright, the build's version); both MSIs show the icon in
Programs and Features (ARPPRODUCTICON).
| What | Where |
|---|---|
| Icon | assets/icons/app.ico (committed; 16–128 px and a PNG 256 px), from assets/icon-source.png |
| .NET executables | Directory.Build.targets: every Exe/WinExe project under src/ gets ApplicationIcon; company and copyright come from Directory.Build.props, the description from AssemblyTitle |
ExecuteR-Screen.exe |
src/ScreenHost/build.rs (winresource): the same icon, company and copyright, the build's version |
| MSIs | src/Installer*/…wixproj (AppIconPath) |
| Server MSI wizard | assets/installer/banner.bmp (493×58, every page's banner) and dialog.bmp (493×312, Welcome and Finish), drawn from the icon; WixUIBannerBmp / WixUIDialogBmp in src/Installer.Server |
A new Windows executable under src/ needs nothing: set OutputType and
an AssemblyTitle (its description) and the icon follows. To change the
icon, replace assets/icon-source.png (square, 256 px or more), then:
./scripts/Generate-Icons.ps1 # rewrites assets/icons/app.ico and assets/installer/*.bmp (System.Drawing, no installs)
./scripts/tests/Test-Branding.ps1 artifacts/agent/<version>/win-x64/*.exe # icon + version info per exe
Troubleshooting
| Symptom | Check |
|---|---|
| Device never appears | Agent log: bootstrap HTTP status; token not expired/consumed; ServerURL scheme is http/https (agent derives ws/wss) |
/api/ready returns 503 |
Database reachable, NATS connected, NATS_ACCOUNT_SIGNING_SEED loaded |
Backend exits: DATABASE_PROVIDER=Postgres requires DATABASE_CONNECTION_STRING |
.env names no database (Compose defaults to Postgres): run ./scripts/deploy.sh, which keeps an existing SQLite database or sets up the bundled Postgres |
EXECUTER-DB-00001 restarts: "superuser password is not specified" |
DATABASE_PASSWORD is empty in .env; deploy.sh generates one for a new database |
| Browser shows "Offline" | POST /api/messaging/credential succeeds; proxy preserves the WebSocket upgrade on /messaging/browser |
| Agent will not connect to NATS | resolver.conf account matches NATS_ACCOUNT_*; WSS path reachable through the proxy |
| Remote shell disabled | AllowRemoteShell=1 (policy or registry) and the agent is online |
| Script "disabled by policy" | AllowScriptExecution not set to 0 by GPO/registry |
| Job shows Restart Refused | AllowRestart set to 0 by GPO, an Agent Settings profile or the registry |
| Job stays Restarting | The device has not reported a newer boot time yet; Restart Cancelled follows when it is still up 3 minutes after the delay (someone ran shutdown /a or shutdown -c) |
| CSRF 403 | The SPA sends X-CSRF-Token; ensure the csrf_token cookie is present |
| File delivery 503 | Settings → Storage: the built-in store's status and last error, or the external store's credentials and bucket |
| A device can't download from the built-in store | Agent below 1.2.0 (set PUBLIC_SERVER_URL or upgrade it); or a proxy not passing /api/s3/ |
| Job creation returns 409 | Device is orphaned — push a new bootstrap token so the agent re-enrolls |
| Download "skipped" unexpectedly | Local file already matches the supplied sha256, or S3 returned 304 for the stored ETag. Change the object (new ETag) or pass the new hash |
docker compose pull fails |
Set REGISTRY in .env and run scripts/Initialize-GiteaSecrets.ps1 so CI has published images; deploy.sh falls back to building from source |
Screenshots
Built to prove one idea cleanly: secure HTTPS enrollment, scoped NATS over WebSocket through one proxy edge, durable work, in-process PowerShell, and a secured terminal — with a browser that updates in real time over NATS, no SignalR or SSE.
Licence
ExecuteR is proprietary software of Endexa Solutions, provided under licence only; see LICENSE. It includes third-party components under their own licences, and its web console is built on the commercially licensed Mantis Pro template — see THIRD-PARTY-NOTICES.md.


























