Executors
Executors are the worker processes that actually run your workflows and scripts. Each executor is a Docker container that continuously polls the Runner API for pending runs, picks them up, executes the workflow or script inside an isolated sub-container, and reports the result back. You can run multiple executors side by side to handle concurrent schedules.
All authenticated users can view the executor list. Managing executors — editing, pausing, and deleting — requires the global Admin role. See Members & Roles for how global roles relate to project access.
Your executors
The executor list shows all registered executors. Each row displays the executor's current status, its description, the CPU architectures it supports, any tags it has, the executor version, how many runs it has executed in total, and when it was last seen.
You can sort by description, last seen date, or run count, and search by description.
Each executor can be in one of three statuses:
| Status | Meaning |
|---|---|
| ready | Online and idle; waiting for a run to be assigned |
| executing | Online and currently executing a run |
| offline | Has not contacted the API in the last 60 seconds |
An executor marked as paused will not pick up new runs regardless of its online status. In-flight runs already assigned to it are not affected.
Each executor has two actions:
- Pause / Resume — toggle whether the executor accepts new runs. Requires Admin.
- Delete — see Deleting an executor.
Adding an executor
Executors are not added through the UI directly. Click Add Executor to see the instructions, or run the following command on the Runner host to scale the number of executor containers:
docker compose scale executor=2Replace 2 with the number of executor instances you want. You can scale up or down at any time. A new executor registers itself with the API on startup and appears in the list within a minute.
The initial description and tags of a new executor instance can be set via environment variables in docker-compose.yml before starting the container:
INITIAL_DESCRIPTION— sets the display name, e.g.INITIAL_DESCRIPTION: GPU ExecutorINITIAL_TAGS— sets the initial tags as a comma-separated list, e.g.INITIAL_TAGS: large,gpu
These values are only applied when the executor first registers. Changing them after the executor is running has no effect — use the edit form instead.
Editing an executor
Click any executor row to open its detail page. Two fields are editable:
Description — the display name shown in the executor list and on run detail pages.
Tags — used to route runs to specific executors. See How runs are dispatched for the full matching rules. Use tags to direct resource-intensive runs to larger machines — for example, tag one executor gpu and configure the relevant environments to require it.
The remaining fields are read-only statistics:
Version — the version of the executor container. The API and Web versions are shown in Settings. Keep all three in sync — running mismatched versions is not supported.
Architectures — the CPU architectures this executor supports, detected automatically at startup (e.g. x64, arm64). Runs are dispatched to an executor that matches the architecture required by their environment.
Status — the executor's current status and paused state, as shown in the list.
Created At — when this executor first registered with Runner. Scaling up or pulling a newer executor image typically creates a new executor entry.
Last Seen At — when the executor last polled the API. Online executors contact the API approximately once per minute. If this timestamp is stale and the executor shows as offline, check the executor container's logs for errors.
Number of Runs Done — the total number of runs this executor has executed. Click the link to see all runs from this executor across the projects you have access to.
How runs are dispatched
When a run becomes pending, Runner looks for an executor that satisfies three criteria simultaneously:
Available — the executor is online and not paused.
Architecture — the executor supports one of the CPU architectures allowed by the environment's Executor Architecture setting, or any environment that leaves the setting empty. KNIME environments always require x64. Executors report their supported architectures automatically at startup. See Environments for how to restrict an environment to specific architectures.
Tags — the run carries a combined set of tags: environment tags and schedule tags are always merged together. If the schedule has no tags, only the environment's tags apply; if neither has tags, the run is tagless. How the executor's own tags determine eligibility:
- Executor has no tags — it only picks up runs that also have no tags.
- Executor has tags — it picks up any run where at least one of the run's tags appears in the executor's tag set, plus any tagless runs.
This means a gpu executor picks up both untagged runs and runs tagged gpu, but not runs tagged exclusively large. A gpu,large executor picks up runs tagged gpu, runs tagged large, and tagless runs.
If no executor satisfies all three criteria, the run stays pending until one becomes available — or until the Cancel Pending Runs After timeout in Settings fires. The executor list is visible to all users, so anyone can check which executors are online and what tags they carry.
Pausing and resuming
Pausing an executor prevents it from picking up any new runs. It remains registered and visible in the list. Use this when you need to take an executor offline for maintenance without removing it entirely — for example, to update the Docker image or perform host maintenance.
To pause, click the Pause button on the list row or the executor detail page. Click Resume to make it available again. Both actions require Admin.
Deleting an executor
An executor can only be deleted when it is offline and has no run records associated with it. An executor with any run history — even completed runs — cannot be deleted. This protects the audit trail: run detail pages link back to the executor that handled them.
If you need to remove an executor with run history, stop the container and leave the executor registered. It will appear as offline but its historical data remains intact.
Deleting requires Admin.