Runners

Ordyn Runners execute centrally managed work on dedicated Windows or Linux computers. They are useful for tasks that need infrastructure access, dedicated build tools, or an operating system that differs from the managed endpoint.

Open Administration > Services > Runners. Use the Runners and Pools tabs to manage the services.

Initial Runner workloads include:

• saved PowerShell scripts on Windows
• saved Bash and POSIX shell scripts on Linux
• inline PowerShell, Bash, and POSIX shell scripts in infrastructure jobs
• saved and inline Linux shell scripts in Docker containers
• Runner collectors
• Windows PE image builds on Windows Runners with the Windows ADK
• Microsoft offline update catalog and approved update content downloads
• Intel ODCA trust and revocation refreshes

A Runner connects outbound through its assigned Edge service. Each Runner belongs to one Runner pool, and each pool uses one Cache Node for required task files and generated artifacts.

Requirements

Before creating a Runner, prepare:

• an Edge service that the Runner can reach over HTTPS
• a Cache Node that the Runner computer can reach over HTTPS
• a supported Windows or Debian-based Linux computer

Every Ordyn installation includes two Runner slots. Creating more than two configured Runners requires active Runner capacity for the additional slots. Disabled, offline, and unenrolled Runners also use a slot.

Windows Runners use Windows PowerShell. Linux Runners use Bash or POSIX sh.

Create A Runner Pool

1. Open Administration > Services > Runners.
2. Select the Pools tab.
3. Select Add runner pool.
4. Enter a name and select the Cache Node.
5. Create the pool.

A pool can contain both Windows and Linux Runners. Platform and capability matching happens when work is assigned to an available Runner.

Manage Runner assignments from the tenant, folder, or endpoint for Endpoints jobs that also run tasks on a Runner.

Create And Enroll A Runner

1. Open Administration > Services > Runners and select the Runners tab.
2. Select Add runner.
3. Enter a name.
4. Select the Runner pool and Edge service.
5. Open Administration > Enrollment Tokens and select Add Enrollment Token.
6. Select Service client, select Runner, and then select the Runner's Edge service and the Runner.
7. Issue the token and copy it.

If all included and licensed Runner slots are in use, creating the Runner is blocked. Review Runner capacity on the Licenses page or delete an unused Runner before trying again.

Install On Windows

Run the Ordyn Runner MSI as an administrator. The MSI installs the Runner and Ordyn Runner Manager including its CLI tool.

Open Ordyn Runner Manager from the Start menu as an administrator and select Add. Enter:

• a unique instance name
• the Edge host
• the Runner ID shown by Ordyn
• the one-time enrollment token
• the managed workspace path shown by the form, or another empty absolute directory
• LocalSystem or User credentials as the service identity

For User credentials, enter an existing standard or administrator account as DOMAIN\user or .\user. The account must already have the Log on as a service right. The Manager validates the account and credentials, enrolls the instance, creates an independent OrdynRunner-<name> Windows service, and starts it.

Each instance uses private configuration, state, and workspace permissions for SYSTEM. Locations:

• configuration: %ProgramData%\OrdynRunner\instances\<name>\runner.conf
• instance metadata: %ProgramData%\OrdynRunner\instances\<name>\instance.json
• state: %ProgramData%\OrdynRunner\instances\<name>\data
• default workspace: C:\OrdynRunner\<name>

For unattended instance creation, install the MSI silently and then use ordyn-runnerctl.exe. Supply the enrollment token and service-account password through standard input rather than command-line arguments:

@('paste-token-here', 'service-account-password') |
  & 'C:\Program Files\OrdynRunner\ordyn-runnerctl.exe' add release-build `
    --edge-host 'edge.example.com' `
    --runner-id '<runner-id>' `
    --service-account 'DOMAIN\runner' `
    --token-stdin `
    --service-password-stdin

Install a newer MSI normally to upgrade the Runner. Setup stops active instance services before replacing the installed files and restarts the same services afterward. A full uninstall unregisters the instance services and preserves their data. Use the Manager's Remove action when the instance configuration and managed state should also be deleted; custom workspaces are retained.

Install On Debian

Install the package from the Ordyn release channel.

sudo apt install ./ordyn-runner_VERSION_ARCH.deb

Choose The Instance Scope

The scope determines which systemd manager owns the instance and which account controls it:

	System scope	User scope
Instance manager	System systemd manager	Enrolling account's systemd user manager
Enrollment	Run as root and use --scope system	Run as the intended account and use --scope user
Runner account	The account selected during enrollment	The account that enrolls the instance
Service control	sudo systemctl ...	systemctl --user ...
Runs after logout	Yes	Yes, when lingering is enabled for the account

Use system scope when administrators should manage the instance as a system service. Use user scope when one Linux account should own, manage, and run the instance through its own systemd user manager.

Enroll A Runner As Root

Create a system-scoped instance that runs as root. Pass the enrollment token as one line on standard input:

printf '%s\n' 'paste-token-here' | sudo /usr/bin/ordyn-runner instance add build-01 \
  --scope system \
  --run-as-user root \
  --edge-host edge.example.com \
  --runner-id <runner-id> \
  --token-stdin

Enroll A Runner As A Normal User

Create the normal Linux account and enable lingering so its user systemd service continues running after logout:

sudo useradd --create-home --shell /bin/bash runner-user
sudo loginctl enable-linger runner-user

Enroll the user-scoped instance as that account. XDG_RUNTIME_DIR and the D-Bus address connect systemctl --user to the account's systemd manager:

runner_uid="$(id -u runner-user)"
printf '%s\n' 'paste-token-here' | \
  sudo -iu runner-user env \
    XDG_RUNTIME_DIR="/run/user/${runner_uid}" \
    DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/${runner_uid}/bus" \
    /usr/bin/ordyn-runner instance add build-01 \
      --scope user \
      --edge-host edge.example.com \
      --runner-id <runner-id> \
      --token-stdin

A user-scoped instance is managed by the selected account's systemd user manager and runs as that account.

Configure A Custom Workspace

Both scopes support a custom workspace location. Add --workspace-root to the instance add command during enrollment:

--workspace-root /srv/ordyn-workspaces/build-01

The path must be absolute, must not be the filesystem root, and must be empty. It cannot traverse symbolic links, contain Runner configuration or state, or overlap another managed workspace. The account that runs the instance must be able to access the workspace and its parent directories.

For a user-scoped instance outside the account's home directory, create the directory and assign it to the account before enrollment:

sudo install -d -o runner-user -g runner-user -m 0700 /srv/ordyn-workspaces/build-01

The workspace location cannot be changed after enrollment. To use another location, remove and recreate the instance with the new --workspace-root value. Removing an instance does not delete a custom workspace.

System-scoped instance locations:

• configuration: /etc/ordyn-runner/instances/<name>/runner.conf
• instance metadata: /etc/ordyn-runner/instances/<name>/instance.json
• state: /var/lib/ordyn-runner/instances/<name>
• default workspace: /var/lib/ordyn-runner/instances/<name>/workspace
• systemd unit: /etc/systemd/system/ordyn-runner-<name>.service

User-scoped instance locations:

• configuration: ${XDG_CONFIG_HOME:-$HOME/.config}/ordyn-runner/instances/<name>/runner.conf
• instance metadata: ${XDG_CONFIG_HOME:-$HOME/.config}/ordyn-runner/instances/<name>/instance.json
• state: ${XDG_STATE_HOME:-$HOME/.local/state}/ordyn-runner/instances/<name>
• default workspace: the workspace directory below the state path
• systemd unit: ${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/ordyn-runner-<name>.service

Install a newer Debian package normally to upgrade the Runner. The package retains existing instances and restarts the instance services that were running before the upgrade.

Pool Assignments

Pool assignments let Runner work find an eligible pool. An infrastructure job selects its pool in the job overview.

For Endpoint related Runner work (Job step "Run script on Runner") open a tenant, folder, or endpoint action menu and select Service routing. Select the Runner pools tab, choose one or more pools for that scope, and save the tab.

Ordyn resolves the effective pool assignment in this order:

1. endpoint
2. nearest assigned folder
3. tenant

Only the highest matching level is used. When several pools are assigned at that level, all of them are eligible.

Runner Selection

The first Runner-backed step for a job target reserves one Runner that:

• belongs to an eligible pool
• is enabled, connected, and not draining
• has the Windows or Linux platform required by every Runner-backed step in the job
• advertises every Runner capability required by the job
• is not already executing another command
• is within the available Runner capacity

All Runner-backed steps for that target execute on the reserved Runner. For endpoint jobs, each endpoint target receives its own reservation. Infrastructure jobs have one target and therefore one reservation.

If compatible Runners exist only outside the available capacity, the job target fails with a licensing error. A target that already has a reserved Runner can finish all of its Runner-backed steps and workspace cleanup if capacity drops while it is running. The Runner cannot receive another reservation until it is within capacity.

Each Runner handles one reserved job target at a time. If every eligible Runner is busy or offline, the job waits for Runner capacity. Compatible jobs that have waited longer receive available capacity first. Waiting time is part of the job timeout.

Ordyn does not move a reserved target to a different Runner. If the Runner disconnects, the target waits for that Runner to reconnect until the target timeout expires. The selected Runner reports its current or completed command after reconnecting. Restarting the Runner service while a command is active ends that command as failed.

If the Runner and Ordyn cannot determine whether earlier work executed, the Runner remains connected but blocked and its detail page shows Recover command delivery. Recovery fails every command before command dispatch resumes.

Endpoint And Infrastructure Jobs

Endpoint Scope

Endpoint jobs create one job run per resolved endpoint. A Run Runner script task keeps the endpoint as the job target and uses that endpoint's effective pool assignment.

Runner-backed endpoint jobs can target agent endpoints, generic network endpoints, SNMP-managed switches and printers, and Telematik card terminals. The target does not need to run the Ordyn Agent because the selected Runner executes the script. If a job requires the endpoint to be connected, Ordyn uses the connection signal for that endpoint kind: the agent connection, a recent successful network probe, or the assigned SNMP or Telematik service client.

Infrastructure Scope

Infrastructure jobs run once without any endpoints. Select one Runner pool in the job overview. Every Runner-backed step in the job uses that pool and the same reserved Runner.

Use infrastructure scope for:

• build work such as Windows PE image creation
• privileged scripts which should run for a endpoint but not on a endpoint due to requiring credentials
• downloading Windows Updates

Infrastructure jobs also support completion and webhook automations, history, cancellation, and downloadable artifacts produced by tasks. See Infrastructure Jobs and Job Runs Reporting.

Runner Scripts

Create a saved script under Library > Scripts and set:

• platform Windows with interpreter PowerShell, or platform Linux with interpreter Bash or POSIX shell (sh)
• execution target Runner
• parameters as needed

Runner scripts always use blocking execution. Scripts executed on the host run as the Runner service identity. Docker tasks use the container user described below. All Runner-backed steps for the same job target share a managed workspace. Runner script tasks can select an existing workspace-relative working directory.

Files created by one Runner-backed step remain available to later Runner-backed steps through the ORDYN_WORKSPACE environment-variable path. Ordyn removes the shared workspace after the target reaches a terminal state.

Parameters And Endpoint Context

Parameters use the same command-line and ORDYN_PARAM_* environment-variable behavior as other saved scripts.

The Runner redacts known values from captured output and does not persist secret values.

Endpoint-scoped Runner scripts also receive:

• ORDYN_ENDPOINT_ID
• ORDYN_ENDPOINT_KIND
• ORDYN_ENDPOINT_HOSTNAME
• ORDYN_ENDPOINT_FQDN
• ORDYN_ENDPOINT_TENANT_ID
• ORDYN_ENDPOINT_PRIMARY_IP_ADDRESS

The primary address is taken from the endpoint's primary network interface. Optional values are exposed as empty strings when they are unavailable, so a missing FQDN or primary address does not prevent the script from starting.

Infrastructure-scoped scripts do not receive endpoint values.

Output, execution time, and workspace use are bounded. Cancellation or timeout terminates the managed script process tree.

The selected Linux interpreter must be available as bash or sh on the Runner service account's PATH. Ordyn does not fall back to another shell when the selected interpreter is unavailable.

Run Linux Runner Scripts In Docker

Linux Runner script tasks can execute on the host or in a Docker container. In the task editor, select Docker, enter an image reference, and choose a pull policy:

• If not present uses a local image when available and pulls it when missing.
• Always pulls before each execution.
• Never requires the image to exist locally.

Script launch runs the selected bash or sh interpreter. Executable launch starts the configured program directly with its literal argument list. The interpreter or executable is resolved from the image's PATH unless an explicit path is provided.

The Runner places the task script inside the transient container with permissions that allow the selected container user to read and execute it. Standard output and standard error are streamed while the script runs. The configured timeout and cancellation stop the script and its container. The Runner removes the container after the task reaches a terminal state.

The job workspace is mounted at the infrastructure job's configured container workspace path, which defaults to /workspace. The selected workspace-relative working directory is mapped below that container path. Files remain available to later Runner-backed steps and artifact collection. Job containers use the default Docker bridge network and the Docker daemon's normal capability and security defaults.

Container User And Permissions

Without a user override, Docker uses the USER configured by the image. Images without a configured user run the task as container root.

Set Container user when the image default is unsuitable. Enter a username, UID, user:group, or UID:GID, for example:

builder
1001
builder:staff
1001:1001

Use Bind mounts to mount an absolute host path at an absolute path inside the container. Each mount can be writable or read-only. Mounts cannot replace or overlap the configured workspace path or the Runner-managed paths below /run/ordyn.

Every job environment variable is passed to the container automatically. Use Container environment overrides to add a variable or replace its value for the container. Environment overrides always require an explicit value and do not read variables from the Runner service environment.

Container users, mount paths, and environment values support Ordyn runtime templates. Environment variable names are literal.

The image/default user or configured user must be able to enter and use the configured workspace path and any additional bind mounts. Ordyn guarantees access to the generated task script, but it does not change permissions on additional mounts. On a rootful Docker host with stable account IDs, configuring the Runner account's numeric UID:GID runs the script with that ownership when the account can access the image and mounted paths.

Container root on a rootless Docker daemon maps to the account that owns the daemon. This normally allows an image without USER to access a workspace owned by the user-scoped Runner. An explicit container UID maps through the daemon's subordinate user namespace; configure it only when that mapped identity has the required workspace permissions.

Workspace Ownership

By default, after every started Docker task, the Runner restores the managed workspace to the Runner service account. Restoration runs after success, script failure, cancellation, and timeout. Additional bind mounts are not changed.

An ownership-restoration failure is included in the task diagnostics. It fails an otherwise completed task; cancelled and timed-out tasks keep their cancellation or timeout status. The script's exit code and captured output remain available in the task result.

Ownership restoration uses a small helper image. The default is busybox:latest. The Runner uses a local copy when present and otherwise pulls the image anonymously. Job-specific container-registry credentials are not used for this helper image. Pre-pull a private helper image or configure a public/internal mirror that permits anonymous pulls:

[container_execution]
enabled = true
restore_workspace_ownership = true
ownership_helper_image = "registry.example.test/mirror/busybox:1.37"

Set restore_workspace_ownership to false when the Docker filesystem does not permit ownership changes:

[container_execution]
enabled = true
restore_workspace_ownership = false

When disabled, the Runner does not use the ownership helper. Files created by mapped container users retain their container-assigned ownership. Later host steps, artifact collection, or workspace cleanup may be unable to access those files.

Docker execution is disabled for each new instance. The Runner advertises runner.container.docker only while Docker execution is enabled and the configured endpoint passes the Docker ping, version, and information checks. Docker API 1.41 or newer is required. Jobs with Docker Runner tasks wait for a Linux Runner in the selected pool that advertises this capability.

Stop the instance, edit its runner.conf, and restart the service. Enable a system Docker socket with:

[container_execution]
enabled = true
restore_workspace_ownership = true
ownership_helper_image = "busybox:latest"

[docker]
socket_path = "/var/run/docker.sock"

For a dedicated local or rootless Docker daemon, set its absolute socket path:

[container_execution]
enabled = true

[docker]
socket_path = "/run/user/1000/docker-build.sock"

For a Docker endpoint with mutual TLS, configure the endpoint and absolute certificate paths:

[container_execution]
enabled = true

[docker]
host = "tcp://docker-build.example.com:2376"
ca_bundle_path = "/etc/ordyn-runner/docker/ca.pem"
client_certificate_path = "/etc/ordyn-runner/docker/client-cert.pem"
client_key_path = "/etc/ordyn-runner/docker/client-key.pem"

docker.socket_path and docker.host are mutually exclusive. host accepts https:// or tcp://; tcp:// uses Docker TLS. The client certificate and key are required for a remote endpoint. The CA bundle is optional when the daemon certificate uses a system trust root. The instance account must be able to open the selected socket or read the TLS files.

A daemon must see the Runner workspace at the same absolute path because Docker resolves bind-mount source paths on the daemon host.

To disable Docker execution, set container_execution.enabled to false and restart the service.

For authenticated image pulls:

1. Configure an active registry under Administration > Services > Container Registries.
2. Select the registry in the infrastructure job's Features tab.

Ordyn matches the rendered image host exactly. Image references without an explicit registry host use docker.io. A job without a Docker registry feature pulls anonymously. Ordyn rejects a job when more than one selected active registry matches the same image host.

Runner Collectors

A collector can use a Runner-targeted script. Runner collectors keep the endpoint as their target and use the endpoint's effective pool assignment. The script receives endpoint context, and the returned structured values are stored in the normal collector history.

Bind the collector's script parameters in the collector definition. String bindings can use runtime templates such as {{ endpoint.hostname }} or {{ endpoint.primary_ip_address }} and are resolved separately for each endpoint. Secret bindings select a secret variable definition. Required parameters without a binding or script default are rejected.

Build A Windows PE Image

Install these Microsoft components on a Windows Runner:

• Windows Assessment and Deployment Kit deployment tools
• Windows PE add-on for the same ADK version

The Runner overview reports whether the required tools were detected and advertises the WinPE build capability only when they are available.

Create an infrastructure job, select a Runner pool in the job overview, and add Build WinPE boot image. Configure:

• the wimboot image
• the Ordyn Agent release
• the output name and version
• optional driver profiles

The pool Cache Node supplies the build inputs and receives the generated WinPE assets. A successful run creates the boot image in Ordyn and shows its generated files in the infrastructure run details.

Windows Update Offline

Windows update infrastructure tasks can run on either Windows or Linux Runners.

Use:

• Download offline Windows update catalog to download the current Windows Update offlien catalog from Microsoft.
• Download approved Windows updates to download approved Windows updates from Microsoft and import them into Ordyn.

See Windows Updates for the complete endpoint inventory and installation workflow.

Refresh Intel ODCA Trust

The Refresh Intel ODCA trust infrastructure task can run on either a Windows or Linux Runner.

It requires outbound HTTPS access to tsci.intel.com.

Create an infrastructure job, select the Runner pool, and add the task.

See Intel AMT Infrastructure for validation, status, provenance, and offline import.

Runner Status And Lifecycle

When configured Runner usage exceeds current capacity, Ordyn entitles the earliest-created Runners first. Runners outside capacity remain visible and configurable but cannot receive a new job reservation.

Disabling a busy Runner puts it into Draining. The active command may finish, but the Runner receives no new work. It becomes disabled after the active command reaches a terminal state.

Revoking a certificate disconnects the Runner. Issue a new Runner enrollment token and run enrollment again with the same Runner ID to restore it.

Windows Runner logs are written to Event Viewer under Applications and Services Logs > Ordyn Runner > Operational and Audit.

Each Windows instance also keeps a fallback JSON-lines log at:

C:\ProgramData\OrdynRunner\instances\<name>\data\logs\runner-fallback.log

Linux Runner logs remain in journald. Inspect them with:

journalctl -u ordyn-runner.service
journalctl SYSLOG_IDENTIFIER=ordyn-runner-operational
journalctl SYSLOG_IDENTIFIER=ordyn-runner-audit

The operational log records when Runner work is received, started, and finished.