Alphaeus Mote 59c06e33bb feat(shell): clipboard for the remote shell [skip ci]
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>
2026-11-18 19:51:08 -05:00

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.

Dashboard


Table of contents

  1. Architecture
  2. Component flow
  3. Agent-to-component flow
  4. Prerequisites
  5. Deploy to a server
  6. Local development
  7. Required secrets
  8. Generating local secrets
  9. Docker Compose
  10. Standalone server binary
  11. Server installer
  12. Networking and TLS
  13. Message security
  14. Reverse proxy routes
  15. Agent foreground mode and service lifecycle
  16. Agent upgrades and the watchdog
  17. MSI public properties
  18. Registry paths and GPO precedence
  19. Agent settings precedence and profiles
  20. Bootstrap and URL install
  21. Windows PE
  22. Sign-in
  23. Custom roles and permissions
  24. Typed script parameters and Functions
  25. Script engines
  26. Sequences
  27. Secrets providers and $Secrets
  28. Device groups and script triggers
  29. Group runs and schedules
  30. Database providers
  31. Logging
  32. Device lifecycle: reconnect or orphan
  33. Removing devices
  34. Agent installer delivery
  35. Agent upgrades from the server
  36. Device files
  37. Device registry
  38. Remote View
  39. S3 file delivery
  40. CI/CD and GITEA_* variables
  41. Versioning
  42. Branding
  43. Troubleshooting
  44. Screenshots
  45. 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 --version gives 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 CI windows-host runner 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.

First sign-in password 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, Caddy tls_insecure_skip_verify, HAProxy ssl 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.crt sits 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:

  1. 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.
  2. 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

  1. The agent takes the command.agent.upgrade command. 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.
  2. 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 to upgrade/staging/<version>-<id>/ (no agent binary inside: failed / package), makes sure the watchdog runs, writes upgrade/handover.json and reports installing. A hand-over the watchdog has not taken within 10 minutes fails as watchdog.
  3. 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.
  4. 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 .next and .previous go and the outcome is succeeded.
  5. Otherwise it is rolled back: the new files go to <install>/.failed/<id>/ (and are then deleted), .previous comes 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.
  6. The outcome is written to upgrade/outcome.json and 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.

  1. The agent downloads and checks the MSI (same jitter, size and SHA-256 as a zip) into upgrade/msi/ExecuteR-Agent-<version>.msi and confirms it is the agent's MSI of that version (its UpgradeCode and UNIFIEDVERSION). 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.
  2. The watchdog checks both MSIs again, writes upgrade/msi.json, copies its own binary to upgrade/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.
  3. The runner calls Windows Installer with no UI and a verbose log (/l*v) in <install>\Logs\agent-msi-<version>-<id>.log, with REBOOT=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).
  4. 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 with ALLOWDOWNGRADE=1 from the start.
  5. 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.request on 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 (the SOFTWARE/ExecuteR/Runtime section 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.

Add device


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-admin in a container; auth-reset is 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_MODE in the environment) become the OIDC tab.
  • Roles' claim values and the Admin/Operator/Viewer mappings become claim=value bindings.
  • 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.

Sign in


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.

Access control

Role editor


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.

Script editor

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.exe on 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 (jq friendly). The prelude is sourced first through BASH_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's Path.GetTempPath() as the agent's account, which for LocalSystem on current Windows is C:\Windows\SystemTemp\ExecuteR (older builds without SystemTemp: C:\Windows\Temp\ExecuteR); $TMPDIR/ExecuteR or /tmp/ExecuteR on linux/macOS. JobRoot (GPO > Agent Settings profile > registry > default; MSI JOBROOT; agent.json on 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 5 as 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, $Secrets and $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.X names 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.

Script execution flow

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.

  1. The run ends; its final state says Restart Requested (or Restart Refused when AllowRestart is off, and nothing restarts).
  2. 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.
  3. 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.
  4. When the delay ends, the agent reads AllowRestart again (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.
  5. 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.)
  6. 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.
  7. 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.

Secrets providers

Script parameters and secrets


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.

Group rule builder

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 from WTSQuerySessionInformation. 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; --list shows 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 / -w streams the output to the console and exits with the script's exit code; --timeout / -t bounds the wait.
  • A schedule that runs a sequence makes it available the same way (listed with "(sequence)"): run starts it and returns at once, also with --wait, since it carries on across restarts; --param is refused.
  • Exit codes: 0 started (or, with --wait, the script's own code; a failed run that reports none exits 1), 1 refused, not found, ambiguous or bad input, 2 the agent service is unreachable or not connected to the server, 124 --wait timed 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.sock on 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_WORKER node 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.

Scheduled trigger builder

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 automation category.
  • 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 with quick_check before it is compressed. They go to the server folder, DATABASE_BACKUP_PATH (default backups/ in DATA_PATH, else beside the database: /data/backups in the container, inside the /data bind mount), to the S3 store chosen in Settings › Storage (built-in or external) under executer/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/backup or D:\Backups; the server's login needs db_backupoperator or db_owner). They are COPY_ONLY, so your own backup chain is untouched. Files are executer-sqlserver-01.bak … -NN.bak for 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, a pg_dump custom-format archive (compressed by pg_dump itself, so not gzipped again) of the server's database over its own connection, read back with pg_restore --list before 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_dump must be the server's major or newer, so a newer external server needs a newer client. Elsewhere (the standalone server, the MSI) pg_dump is found on PATH or at PG_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 nested Outer+Inner → Outer.Inner); Agent or Server for a line with no type; Watchdog, MsiRunner, RemovalRunner for 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 as CorrelationId, ClientId, JobId included; SourceContext, MachineName, Application, EventId and the framework's RequestId/ConnectionId/ActionId left out). A value with whitespace, = or " is double-quoted with \" escaped; a missing value is null. 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:

  1. stops the agent;
  2. 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 as C:\Program Files);
  3. 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:

  1. AGENT_PACKAGE_PATH — compose defaults it to /data/agent, which is a host bind mount (…/API/AgentPackage). Dropping a new Agent.msi / Agent.zip (plus an optional VERSION marker) there delivers an out-of-band agent update instantly — it wins over the baked package, with no new backend image or restart.
  2. /opt/executer/agent — baked in by CI
  3. /data/agent — fallback when AGENT_PACKAGE_PATH points 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.

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.

A device's Files tab

Editing a file that changed on the device

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]
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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); registry HKLM\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 WTSSendMessage calls 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_LIST limits 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_CLOSE and JOB_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 Origin must 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.), audits ended with 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.exe there), 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.exe with WTSQueryUserToken for the console session: under UAC that is the filtered, non-elevated token; the linked (elevated) token is never asked for. The manifest is asInvoker. 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) and SetDllDirectory(""); 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 GetNamedPipeClientProcessId is the process it just started and GetNamedPipeClientSessionId its 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.1 only (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 in object-store beside the database (S3_EMBEDDED_DATA): /data/object-store in the container, <data>/db/object-store in 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=0 removes it altogether, and S3_EMBEDDED_PROGRAM names your own build. The packages and the backend image carry it in object-store/ beside the server, pinned in build/object-store.json and 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).

S3 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.

Searching a bucket

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:

  1. 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".
  2. 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:\Logs uploads as Logs/…).
  • --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: 0 all uploaded, 1 refused (turned off, no store, over a limit, not an elevated administrator) or nothing uploaded, 2 the agent service is unreachable or not connected to the server, 3 some 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):

  1. 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.
  2. presign, per file, just before it is sent: a presigned PUT for exactly that key, valid for S3_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 presigned UploadPart URLs eight at a time.
  3. 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 signed PUT of one object or one part and nothing else), over HTTPS and not over NATS. A part that fails is tried again twice.
  4. complete: the server completes a multipart upload and checks the object's size against the size declared; anything else is removed.
  5. 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 tagged dev and <version>-dev (X.Y.Z.N-dev). All binaries upload as the binaries run artifact.
  • Push to main — the same set, images tagged <version> (X.Y.Z.N) and latest. When the commits since the last release call for one (a fix, feat or breaking change), release.yml releases it instead: every binary as X.Y.Z, the tag vX.Y.Z, a Gitea release with the notes, every agent ZIP, both MSIs, the Server ZIPs and checksums, and the images tagged X.Y.Z and latest (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:

  1. Tag the last calendar-era release commit on main v0.1.0 and push the tag (git tag v0.1.0 <commit>, git push origin v0.1.0).
  2. The switch-over commit (build(version)!: semantic versions from release tags) carries BREAKING 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

Dashboard Dashboard Devices Devices
Device detail Device overview, tags and groups Hardware Hardware inventory
Network Network inventory Actions Device actions and file delivery
Groups Groups Static members Static group membership
Script editor Monaco editor with IntelliSense and pop-out Script Configuration Script Configuration: parameters, secrets, files, Functions
Jobs Jobs and stored output Functions Functions
Access Users and custom roles Role editor Role permissions and device scope
Settings Bootstrap token and install command Light theme Light theme

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.

S
Description
Secure Windows endpoint management
Readme 44 MiB
2026-11-19 01:10:04 +00:00
Languages
C# 71.5%
TypeScript 23.4%
Rust 3.1%
PowerShell 1.3%
Shell 0.5%
Other 0.1%