A runtime agent is a headless Nodlyn package that runs your workflow on a target machine — factory PC, edge gateway, or server — without Studio UI. You design and validate in Studio, then export an Active workflow as a self-contained ZIP.
When to use
- On-prem protocols: Modbus, serial, GPIO, local filesystem, Matter, Zigbee.
- Air-gapped or low-latency sites where cloud execution is not acceptable.
- Same validated workflow deployed to many edge nodes.
- ERP, MES, or custom apps triggering workflows via HTTP/MQTT/file ingress.
How to export
- Move the workflow through the lifecycle until it is Active.
- Open the canvas toolbar menu → Export Runtime (or right-click canvas → Export as Runtime).
- Configure the export modal (see below) and download the ZIP.
- Install on the target machine as an OS service (Windows Service, systemd, or launchd).
- Monitor the agent in the Agents tab or on the agent’s built-in dashboard — see Runtime Monitoring.
Requires Operator, Supervisor, or Admin role. Sub-workflows referenced by SubWorkflow nodes must also be Active (embedded automatically in the package).
Export modal options
| Setting | Description |
|---|---|
| Runtime name | Service display name and ZIP filename prefix. |
| Package contents | This workflow — one agent, one workflow. Multiple workflows — one agent, up to 10 Active workflows (bundle). |
| Target operating system | Windows, Linux, or macOS (Apple Silicon / Intel for Mac). |
| Runtime dashboard port | Local status UI and event ingress API (default 9090). |
| Webhook listener port | Single-workflow export with a Webhook trigger only. |
| Agent monitoring | This on-prem studio or Nodlyn Cloud (remote) — where heartbeats appear. See Runtime Monitoring. |
| Approval suspend alerts | Teams/Slack webhook when a run pauses for operator approval — pre-filled in the ZIP from Studio settings or export dialog. See Approvals Explained. |
| External events | HTTP / MQTT / file-watch routes for external consumers. See Event Ingress. |
What is inside the ZIP
bin/— self-containedNodlyn.Runtime(includes .NET — no separate runtime install).runtime-manifest.nodpkgorruntime-bundle-manifest.nodpkg— encrypted workflow graph, schedules, variables, ingress routes, agent token.install/— service installers (Setup.bat,install.sh, systemd/launchd units).plugins/custom/— custom component DLLs included in the export. See Custom Components.README-quickstart.txt— install steps, agent token, dashboard port.
Multi-workflow bundles
Select Package contents → Multiple workflows to ship up to 10 Active workflows in one agent:
- Shared agent token and one runtime process.
- Webhook paths use
/webhook/{workflowId}instead of separate ports. - Global variables are deduplicated across workflows.
- Ingress-only workflows in a bundle need explicit
workflowIdortyperouting — see Event Ingress.
Install
| OS | Steps |
|---|---|
| Windows | Extract ZIP → run install\Setup.bat as administrator. |
| Linux | Extract → sudo bash install/install.sh |
| macOS | Extract → sudo bash install/install.sh (launchd daemon) |
After install, pair the agent at /pair when cloud or on-prem monitoring is enabled. The Agents tab shows Waiting for agent to connect… until the first check-in.
Before first export
On the Studio / API server, set Runtime:ControlPlaneUrl in Nodlyn.Api/appsettings.json to your LAN address (e.g. http://192.168.1.10:5010) so agents can heartbeat. Export fills the rest automatically.
Approvals: use Activity → Jobs → Approvals in Studio (login + roles). On exported agents, sign in at the dashboard with the same control-plane account when Runtime:DashboardAuthEnabled is set (automatic when a control plane URL is present at export). Dangerous steps pause until an Operator+ approves; Arm requires Supervisor+. Enable Operator approval support at export for legacy LAN token fallback.
Configuration: at export, Nodlyn builds a dashboard config schema from non-secret operational node settings (text, number, select, toggle) and ships it in the manifest. Operators edit values at /settings on the agent; overrides are stored locally and merged into the graph before each run. Mark connector fields with RuntimeConfigurable to force inclusion, or rely on the default heuristic (secrets and device/workflow pickers are excluded).
Schedule: when a workflow is exported with an active schedule, operators can view and edit it at /schedule on the agent (GET/PUT /api/schedule). Changes are stored in the agent SQLite database; the background scheduler uses the updated cron and next-run time. Requires Supervisor+ when dashboard login is enabled.
Details: Approvals Explained.
See also
- Runtime Monitoring — dashboard, Agents tab, on-prem vs cloud, mobile.
- Event Ingress — HTTP, MQTT, file watch, external consumer sample.
- Approval vs Event Ingress — integrators: ingress is not blocked by approval suspend.
- Share Workflow & QR Code — mobile view and trigger links.
- Global Variables — seeded in the agent manifest at startup.
- Workflow Lifecycle