Skip to content

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
  • script-based alert checks for approved endpoints
  • Windows PE image builds on Windows Runners with the Windows ADK
  • Microsoft offline update catalog, approved update content, and Defender intelligence 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 computer or DEB-based Linux distribution

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 ​

Create a pool under Administration > Services > Runners and assign its Cache Node. A pool can contain Windows and Linux Runners; include the platforms and tools required by its jobs.

For endpoint jobs that use Runner tasks, assign pools through the tenant, folder, or endpoint's Service routing. Infrastructure jobs select a pool directly.

Create And Enroll A Runner ​

Create a Runner under Administration > Services > Runners, selecting its pool and Edge service. Issue a service-client enrollment token for that Runner and Edge, then install it on the chosen host.

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.

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. Each instance runs as a separate OrdynRunner-<name> Windows service.

Instance configuration and retained data are under %ProgramData%\OrdynRunner\instances\<name>. The default workspace is C:\OrdynRunner\<name>.

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.

Adopt A Preserved Windows Instance ​

An MSI uninstall removes the Windows services and retains instance enrollment, configuration, state, and workspaces. Install the Runner MSI and open Ordyn Runner Manager as an administrator.

  1. Select the preserved instance.
  2. If its status is Orphaned and Adopt is available, select Adopt.
  3. For a custom service account, enter that account's password. The account must resolve to the same Windows identity and have the Log on as a service right.
  4. Confirm that the service starts and the same Runner reconnects in Ordyn.

Adoption retains the Runner ID, enrollment certificates, task progress, configuration, and workspace. It does not require an enrollment token.

Recover A Preserved Windows Instance ​

If Manager shows Recovery required, an administrator must select the original Windows service account before the service can be recreated. Use your administrative records to identify that account. Do not select a different account to bypass an error.

  1. Select the instance and choose Recover.
  2. Explicitly select Original account: LocalSystem or Original account: User credentials.
  3. For a custom account, enter its name and password. The account needs the Log on as a service right.
  4. Select Recover and verify that the same Runner reconnects in Ordyn.

Recovery protects the retained configuration and enrollment, then recreates the service. Manager uses the selected account to recreate the service and cannot verify which account ran it before. If you cannot establish the original account, retain the instance data and investigate before continuing.

Resolve Adoption And Recovery Errors ​

Review the Manager's Diagnostic and Windows Event Viewer under Applications and Services Logs > Ordyn Runner > Operational. Allow shutdown to finish before retrying adoption, and correct reported account, workspace, or configuration problems while retaining instance data.

Do not use Remove to repair adoption: removal deletes the instance configuration and enrollment state.

Install On DEB-Based Distributions ​

Download the DEB package for your architecture from the Ordyn release channel. See system requirements.

bash
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 scopeUser scope
Instance managerSystem systemd managerEnrolling account's systemd user manager
EnrollmentRun as root and use --scope systemRun as the intended account and use --scope user
Runner accountThe account selected during enrollmentThe account that enrolls the instance
Service controlsudo systemctl ...systemctl --user ...
Runs after logoutYesYes, 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:

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

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

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

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

bash
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 DEB package to upgrade the Runner. The package retains existing instances and restarts the instance services that were running before the upgrade.

Isolated Builds On Linux ​

To make Isolated build available on a Linux Runner, install the distribution's bubblewrap package (version 0.8.0 or later), allow unprivileged user namespaces, and restart the Runner. Availability is detected automatically. Enable the feature on the jobs or collectors that need it.

Optional settings in the instance's runner.conf control local policy and additional toolchains:

toml
[isolation]
allow_host_network = true
# Optional additional toolchain roots, mounted read-only at the same path:
# read_only_path = "/opt/toolchains/node"

Restart the Runner service after configuration changes and check Isolated builds on its overview.

Set allow_host_network = false when isolated workloads on that Runner must disable networking.

Builds can use system tools under /usr. For additional tools, add a read_only_path for each installation directory; its bin directory joins the build search path. Use canonical absolute directories outside Runner state and workspaces. Install required tools centrally because isolated builds have their own private home.

Pool Assignments ​

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

For endpoint jobs and Runner alert checks, 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 ​

A job target uses one compatible Runner for all its Runner tasks. Each Runner handles one target at a time, so jobs wait when suitable Runners are busy or offline. Waiting counts toward the job timeout.

Ensure the selected pool contains a Runner with the required platform and tools. All Runner steps for a target must work on the same Runner. Runner licensing also limits which Runners can accept new work.

If a reserved Runner disconnects, the target waits for that Runner until its timeout; it does not move to another host. Restarting the service fails an active command.

If the detail page offers Recover command delivery, inspect the affected work before using it. Recovery fails outstanding commands so the Runner can accept work again.

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 the job requires connectivity, check what connected and active mean for the target endpoint kind.

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, webhook, and Git changes automations, history, cancellation, and downloadable artifacts produced by tasks. See Infrastructure Jobs and Job Runs Reporting.

Use a Git source to build a repository branch or pull request. A separate checkout pool can prepare the files for build Runners without repository access; see Choose where checkout runs for requirements.

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.

Avoid printing secrets in script output. See Scripts for parameter and output guidance.

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 workspace is available inside the container at the job's configured path, /workspace by default. Use a workspace-relative working directory to share files with later steps and artifact collection. Cancellation or timeout stops the container task.

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:

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

With ownership handling enabled, the Runner prepares the managed workspace for the image default or configured user and checks access before starting the task. Additional bind mounts must already allow that user to access them; the Runner does not change those mounts.

The Docker daemon must have access to the managed workspace. The Runner and a rootless daemon can use different accounts when their mappings and filesystem permissions permit workspace preparation and restoration. Rootful Docker with user-namespace remapping requires the daemon to allow an ownership helper in the host user namespace.

Workspace Ownership ​

By default, the Runner prepares the managed workspace for the selected container user before starting a Docker task. It restores ownership and access to the Runner service account after success, failure, cancellation, timeout, or an unsuccessful start. This allows later host steps and artifact collection to use the files. Only the managed work area is changed; additional bind mounts and retained input files outside it are unaffected. Executable files retain their executable permissions.

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.

Workspace preparation and restoration use a helper image. The default is busybox:latest. A custom helper needs a Unix shell and standard identity, file, and permission utilities. Executable task images do not need a shell. The helper and task images can use different architectures supported by the Docker daemon.

The Runner uses a local helper image when present and otherwise pulls it anonymously. Job-specific container-registry credentials are not used for this image. Pre-pull it for offline use or private registries, or configure a mirror that permits anonymous pulls:

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

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

toml
[container_execution]
enabled = true
restore_workspace_ownership = false

When disabled, the Runner does not use the ownership helper or change workspace permissions. Configure access so the selected user can traverse its working directory, read inputs, and write outputs. Files retain their container-assigned ownership, which can prevent later host steps, artifact collection, or workspace cleanup from accessing them.

If cleanup cannot finish, only the affected workspace remains pending. The Runner retries recovery before reuse or removal, including after a restart. Restore access to the configured Docker endpoint and helper image before retrying the job or cleanup. Preparation and restoration require a filesystem that permits ownership and permission changes; unsupported mappings or filesystem restrictions are reported in the task diagnostics.

Enable Docker execution for each instance that needs it. Docker API 1.41 or newer is required. Jobs with Docker tasks wait for a Linux Runner in the selected pool with a working Docker connection.

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

toml
[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:

toml
[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:

toml
[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.

Registry Credentials In Job Steps ​

Select the required connections in the infrastructure job's Docker registries build feature. Registry authentication is checked before user tasks start. The selected credentials are available to host Docker commands, matching task-image pulls, and programs inside Docker execution containers. See Container Registries for connection setup and image-host matching.

Host scripts can use docker pull, docker build, and docker push without a separate login. Install the Docker CLI and ensure the Runner can reach its configured daemon.

Inside execution containers, tools that read Docker's DOCKER_CONFIG, such as Cosign, can use every selected registry, including registries different from the tooling image's registry. This applies to saved scripts, inline scripts, and executable steps, with either the image's default user or a configured container user. The required tools must be installed in the image, and the registry credentials must permit the requested operations. Credentials do not grant access to a Docker daemon inside the container.

The Runner supplies DOCKER_CONFIG for jobs with this feature, taking precedence over job variables and container environment overrides. Keep this value when running registry tools; no manual login or duplicate credential variables are required.

Credentials are scoped to the job and removed during cleanup. If a container cannot be removed, the Runner reports pending cleanup and retries during job cleanup, at restart, and before another authenticated step. Restore Docker connectivity and access when cleanup is pending; authenticated steps cannot start until it succeeds.

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

Confirm that the Runner overview reports the required WinPE build tools before running the job.

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

  • the wimboot image
  • the agent release mode: Latest approved release or Latest release
  • the output name and version
  • optional driver profiles

Latest approved release selects the highest approved Windows x64 Agent version. Latest release includes unapproved versions. Selection happens when build preparation begins and remains fixed for that execution. The selected version must have a matching WinPE executable.

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 offline catalog from Microsoft.
  • Download approved Windows updates to download approved Windows updates from Microsoft and import them into Ordyn.
  • Download Microsoft Defender updates to prepare intelligence packages for offline Windows endpoints.
  • Download Microsoft certificate updates to prepare verified certificate bundles for offline Windows endpoints.

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

Refresh Intel ODCA Trust ​

A Windows or Linux Runner with HTTPS access to tsci.intel.com can run the Refresh Intel ODCA trust infrastructure task. See Intel ODCA Trust to set up the job and understand what the imported bundle provides.

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:

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

Linux Runner logs remain in journald. Inspect them with:

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