Approvals on Runtime Agent

Duration: ~35 min · Level: Advanced · Topic: Runtime agent · Safety gates · Business approvals

Prerequisites: Export Runtime to Edge, Approvals Explained. An Active workflow with at least one Dangerous node or approval.requestApproval node.

When a workflow runs on an exported runtime agent (headless, no Studio UI on site), approvals work differently than in Studio. This tutorial walks through export, the agent dashboard, safety gates, and the business approvals inbox.

Two approval types on the agent

Type	When it fires	Where to decide
Safety gate	Dangerous or Armed Required node (Modbus write, shell, device command)	Agent dashboard `/` — Approve / Arm
Business approval	`approval.requestApproval` node	Agent dashboard `/approvals`

Studio login and roles do not apply on the agent. The agent uses a safety interlock (pause + operator name in audit log). See Approvals Explained for the full security model.

Step 1 — Prepare a workflow with approvals

Use any workflow that needs human decisions, for example:

Approved Device Command (#8) — safety gate before Z-Wave command.
Purchase Approval on Runtime Agent (#74) — business approval inbox.
Request, Poll & Branch (#237) — canonical approval loop.

Validate and move the workflow to Active.

Step 2 — Export with Operator approval support

Canvas → Export Runtime.
Set target OS, service mode, and dashboard port (default 9090).
Enable Operator approval support when the workflow contains Dangerous nodes or business-approval nodes (auto-checked when detected).
This pre-fills DashboardActionToken in the exported appsettings.json for remote Approve/Arm from LAN.
Download the ZIP and install on the edge host — see Export Runtime to Edge.

Step 3 — Open the agent dashboard

On the agent machine: http://localhost:9090.
From another PC on the LAN: http://<agent-ip>:9090 (Linux/macOS binds 0.0.0.0; restrict port 9090 with firewall).
When export included a control plane URL, sign in at /login with your on-prem Studio user or Nodlyn Cloud account (same API as /api/auth/login).
Edit operational node settings at /settings (Configuration) — values apply on the next run without re-exporting from Studio.
Legacy remote token (exports without dashboard login): open http://<agent-ip>:9090/?accessToken=<token-from-appsettings> once.

Windows agents listen on 127.0.0.1 by default — use RDP or SSH tunnel to the host for local dashboard access.

Step 4 — Safety gate: Approve and Arm

Trigger a run that hits a Dangerous node (webhook, cron, or manual trigger via API).
The run suspends — execution stops until confirmed.
On the dashboard home (/), find the suspended run.
Click Approve. When signed in, your account name is recorded automatically; otherwise enter operator name.
If the node requires Arm: a Supervisor/Admin (or second person when not using login) enters confirmation text (two-person rule).
After approval, execution continues to the dangerous action.

Important: External event ingress (/api/agent/event) is not blocked by approval suspend and cannot approve Dangerous steps. See Approval vs Event Ingress.

Step 5 — Business approval: /approvals inbox

When a run creates a business approval (approval.requestApproval), it is stored in the agent’s local database.
Open http://<agent>:9090/approvals (sign in if dashboard login is enabled).
Pending requests show title, description, and approver field.
When signed in, your Studio/Cloud identity is used — designated approver match or Supervisor/Admin applies.
Without login, enter approver email or name manually (legacy).
Click Approve or Reject.
Downstream approval.checkApproval nodes read the decision on the next poll cycle.

Business approvals on the agent do not appear in Studio Jobs → Approvals. Studio and agent use separate databases.

Step 6 — Verify the full loop

Start a run that requests approval, waits (Delay node), then checks status (Check Approval → Switch).
Decide in /approvals before the delay elapses (default 5 minutes in most templates).
Confirm the correct branch (approved vs rejected) in Jobs → History on the agent dashboard or Studio Agents tab.

Step 7 — Monitoring from Studio

Agents tab — heartbeat, online status, last run.
Agent dashboard — full run history, variables, schedules, logs.
No push notifications in v1 — operators open the dashboard when a run may need attention.

Security checklist (v1 pilot)

Treat the agent LAN as a trusted perimeter (factory network, VPN).
Firewall port 9090 on Linux gateways.
Store the export ZIP and DashboardActionToken like credentials.
For strong identity on business approvals, run workflows in Studio instead of the agent inbox.

What you learned

Export with Operator approval support and dashboard token.
Safety gates on / vs business inbox on /approvals.
Studio and runtime approval stores are separate.