Running Workflows

NORA offers multiple ways to execute workflows — from running a single node interactively to scheduling fully automated background runs. This guide covers all execution modes.

Running a Single Node

Every Command Node has a Run button visible in Run Mode. Click it to execute that node’s command independently.

Inline Execution

Click Run on a node:
1. The node border turns blue with a pulsing animation
2. The command executes in the configured working directory
3. On completion, the border turns green (success) or red (error)
4. The output panel expands showing the command’s stdout/stderr

You can:
– Copy the output to your clipboard
– ✕ close the output panel
– Kill a running process (the red Kill button appears during execution)

Terminal Execution

Click Run in Terminal to open the command in a new operating system terminal window (CMD or PowerShell on Windows). Use this for:
– Interactive programs that need user input (prompts, confirmations)
– Long-running processes you want to monitor in a real terminal
– Commands that use terminal-specific features (colors, progress bars)

Edit Before Running

If the command references a script file, an ✎ Edit button appears. Click it to open the script in a Monaco code editor (syntax-highlighted, with the same editor used in VS Code). You can modify the script and optionally run the edited version immediately.

Running a Full Workflow

How Execution Order Works

When you click ▶ Run Full Workflow, NORA determines the execution order by following the connections (edges) between nodes:

1. Find starting nodes — nodes with no incoming connections (root nodes)
2. Execute root nodes — if multiple roots exist, they can run in parallel
3. Follow connections — after a node completes, follow its outgoing edges to determine what runs next
4. Evaluate conditions — condition nodes check their logic and follow the matching edge (based on edge labels)
5. AI routing — AI Router, AI Agent, and Custom Script Agent nodes use AI decisions or script results to pick which edge to follow
6. Loop edges — if a completed node has an outgoing edge labeled loop:N, the workflow loops back to the target node and re-executes the entire loop path (up to N times)
7. Continue until all reachable nodes have executed or an error stops execution

Running

1. Make sure you’re in Run Mode (not Edit Mode)
2. Click ▶ Run Full Workflow
3. The button changes to ⏳ Running…
4. Watch nodes light up as they execute: blue (running) → green (success) or red (error)
5. A green “Running” indicator shows the currently executing node name

Stopping a Run

• Click 🔄 Reset Run to stop a running workflow immediately
• All running processes are terminated
• Nodes that were running show their last status

After a Run

• Click ✓ Finish & Report to end the run and generate an execution report
• Click 🧹 Clear Visuals to reset all node colors back to idle (gray)
• Node outputs remain accessible — click any node to see its output

Loop Execution

Workflows with loop edges (labeled loop:N) automatically re-execute sections of the workflow multiple times. See Building Workflows — Loop Edges for how to create them.

What Happens During a Loop

1. The workflow runs normally until it reaches the source node of a loop edge
2. The engine checks the loop counter — if iterations remain, it resets all nodes in the loop path (clears statuses, outputs, and edge animations)
3. The target node and all downstream nodes re-execute from scratch
4. The loop edge label updates with a live counter: loop:3 ↺ 1/3 → loop:3 ↺ 2/3 → loop:3 ✓ 3/3
5. When all iterations complete, the workflow continues past the loop (or finishes)

Loop Visual Indicators

During a loop run, you’ll see:
– Purple edge: The loop edge animates purple when the loop fires
– Edge counter: The label shows current iteration (e.g., ↺ 2/3)
– Node badge: The target node displays a purple ↺ N/M badge
– Node reset: Intermediate nodes flash back to idle (gray) before re-executing

Loop Reporting

Loop iteration data is included in execution reports:
– Finish & Report: The execution summary includes loop iteration counts
– Email notifications: The Execution Summary section shows a “↺ Loop Iterations” line listing each looped node and how many iterations it completed
– Execution history: All iterations are logged individually — you can see each pass through the loop in the detailed logs

Partial Runs

You don’t have to run the entire workflow every time. Select a starting point and run from there.

Run from Selected

1. Click a node on the canvas to select it
2. The ▶ Run from Selected button activates, showing the selected node name
3. Click it — execution begins at that node and follows all downstream connections

This is useful when:
– You’ve already run the first few steps and want to continue from where you left off
– You want to test just one branch of a workflow
– A node failed and you want to re-run from that point after fixing the issue

Stop on Error

The Stop on Error setting controls what happens when a node fails during workflow execution.

Error-edge routing: If a failed node has an outgoing edge labeled error, the workflow follows that edge instead of stopping — even when Stop on Error is enabled. This lets you build explicit error-handling paths (e.g., send a notification, run a cleanup script) while still stopping on unhandled failures.

Continue Workflow: When the halt panel appears, clicking Continue will:
1. Execute the failed node’s direct successors (the nodes connected by outgoing edges)
2. Continue following the workflow from there as normal
3. Re-enable the “Running” indicator until execution completes

This means the failed node itself is skipped, but all downstream nodes still run.

Email notifications: When Stop on Error halts a workflow, the completion email reports the run as FAILED (not SUCCESS).

Tool Parameter Prompts

Some nodes have parameter definitions — variables that need values before the command runs. When you execute such a node, a Parameter Prompt Modal appears:

• Each parameter shows its name, type, and whether it’s required
• Text parameters: free-form text input
• Number parameters: numeric input
• Enum parameters: dropdown with predefined options

NORA caches your last-used values, so repeat runs pre-fill with previous inputs.

A command preview at the bottom shows exactly what will execute with your parameter values substituted in.

Retry on Failure

When a command fails, NORA can automatically retry it instead of immediately marking the node as failed. This is useful for commands that depend on network connections, external services, or any operation that may temporarily fail.

How to Enable

In the node’s settings (Edit Mode → click the node):

1. Check Enable Retry on Failure
2. Set Max Retry Attempts (1–10) — how many times to run the command total
3. Set Initial Retry Delay (seconds) — how long to wait before the first retry (default: 1s)
4. Choose a Backoff Strategy — how the delay changes between retries

Hard Timeout (Important)

The Hard Timeout field controls the maximum time each individual attempt is allowed to run.

• When you enable retry, NORA automatically fills the timeout to 1800 seconds (30 minutes) if you haven’t set one
• This timeout applies per attempt, not to the total retry sequence
• If an attempt exceeds the timeout, it’s terminated and counts as a failed attempt
• Why this matters: Without a timeout, a hung process (e.g., a network call that never responds) would block forever, preventing any retries from happening

You can set the timeout to whatever your command needs. If your script typically takes 5 minutes, set the timeout to something like 10 minutes (600 seconds) to give it headroom. The timeout is a ceiling — if the command fails in 10 seconds with a 10-minute timeout, the retry kicks in immediately after those 10 seconds. It does not wait the remaining time.

Backoff Strategies

The backoff strategy controls how the delay increases between retry attempts:

What Happens During Retry

1. The command runs (attempt 1)
2. If it succeeds, execution continues normally — no retries needed
3. If it fails (non-zero exit code, timeout, or network error):
4. NORA waits for the configured delay
5. The retry badge updates: ↻ 1/3 → ↻ 2/3
6. The command runs again
7. Steps 2–3 repeat until the command succeeds or all attempts are exhausted
8. If all attempts fail, the node is marked as error with a message showing the total attempts and last error

Retry Badge

Nodes with retry enabled display a badge on the node:

• At rest: ↻ 0/3 — amber badge, showing retry is configured (0 of 3 attempts used)
• During execution: ↻ 1/3 → ↻ 2/3 → ↻ 3/3 — red badge, updating live with each attempt
• After completion: Badge resets. The output panel shows whether it succeeded and on which attempt

Where Retry Works

Retry is supported in all execution modes:

Safety Layers

NORA uses multiple layers to prevent commands from getting stuck:

1. Server-side timeout — Node.js kills the child process when the hard timeout expires
2. Client-side abort — If the server doesn’t respond within the timeout + 30 seconds, the client aborts the request and treats it as a failure (triggering retry if attempts remain)
3. Process tree kill — When you click the Kill button, NORA terminates the entire process tree (the command and all child processes it spawned), not just the parent process

The client-side abort is a safety net for edge cases on Windows where a process’s child processes (e.g., a Python script launching a subprocess) can prevent the server from returning a response even after the main process exits.

Tips

• Always set a reasonable timeout when using retry. Even though NORA auto-fills 30 minutes, adjust it to match your command’s expected runtime + some buffer
• Use exponential backoff for API calls or network operations — it avoids hammering a struggling service
• Check the output panel after a retry sequence — it shows which attempt succeeded (e.g., “✓ Succeeded on attempt 2/3”)
• If you see the node stuck on “Executing Command” with no progress, use the Kill button — this terminates the process tree and unblocks execution

Background Execution

Run a workflow in the background without watching it on the canvas. The workflow executes on the server while you continue working.

Starting a Background Job

1. Load a saved workflow config (must be saved to a file)
2. Click 🔄 Run in Background
3. The workflow starts executing on the server
4. You can close the browser/app — the job continues running

Monitoring Background Jobs

Open Settings → Background Jobs tab to see:
– Active jobs — currently running workflows with status, start time, and duration
– Live logs — click a job to stream its execution logs in real time
– Stop — click to cancel a running job
– Completed jobs — finished workflows with final status

Background vs. Foreground

Note: Nodes marked as interactive (those that need a terminal window for user input) are either skipped or cause an error in background mode, since there’s no terminal to interact with.

Scheduled Workflows

Set up workflows to run automatically on a recurring schedule using cron expressions.

Creating a Schedule

1. Open Settings → Scheduler tab
2. Select a workflow config file
3. Enter a cron expression (see below)
4. NORA shows a human-readable description of the schedule
5. Click Create Schedule

Cron Expression Format

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-7, 0 and 7 = Sunday)
│ │ │ │ │
* * * * *

Common examples:

Managing Schedules

• View all active schedules in the Scheduler tab
• Remove a schedule to stop it from running
• Schedules persist across app restarts (saved to ~/.nora/config/schedules.json)

How Scheduled Runs Work

Scheduled runs execute as background jobs. You can view their results in:
– Settings → Background Jobs — see active and completed scheduled runs
– Settings → Execution History — historical log of all runs

Scheduler Notes

• Timezone: All schedules run in Eastern Time (America/New_York)
• No editing: To change a schedule, remove it and create a new one
• App must be running: Scheduled workflows only fire while NORA (desktop) is open. Combine with Start with Windows and Minimize to tray for 24/7 operation (see Settings — System)

Execution History

NORA keeps a record of all workflow executions (foreground and background).

Viewing History

Open Settings → Execution History tab:
– Each entry shows: workflow name, status (success/error), start time, duration, node count
– Click an entry to expand detailed results: per-node status, output, timing, and retry information
– AI cost tracking is included for workflows that used AI nodes

Log Retention

Execution logs are stored at ~/.nora/logs/. NORA auto-cleans logs older than the configured retention period (default: 30 days) on startup. You can change the retention period in Settings.

Process Monitor

The Process Monitor provides a real-time view of all active processes started by NORA.

What It Shows

The monitor overlay displays:
– Process groups — organized by workflow/job
– Per-process details: PID, duration, CPU usage, command, status

Actions

The monitor auto-refreshes every 2 seconds and verifies that tracked processes are still alive.

Email Notifications

NORA can send email notifications when workflows complete or fail. Email works in both desktop and browser/dev modes — the desktop app uses a background worker process to handle Gmail API calls safely.

What Notifications Include

Workflow notification emails are rich HTML messages containing:
– Per-node status — success/error icons for each step
– Execution timing — total duration and per-node timing
– Retry information — which nodes retried and how many attempts
– AI cost summary — token usage and estimated cost for AI nodes
– Detailed logs — full execution output

Setup

Email notifications require Gmail OAuth2 configuration. See Settings & Configuration → Gmail/Email for setup instructions.

Preferences

In Settings → Gmail tab, configure:
– Notify on: completion only, failure only, or both
– Recipient email: where to send notifications

Execution Tips

Testing Individual Steps

Run nodes individually before running the full workflow. This helps catch configuration errors (wrong paths, missing dependencies) one step at a time.

Using Wait Nodes for Rate Limiting

Insert Wait Nodes between API calls or external service calls to respect rate limits and avoid throttling.

Monitoring Long-Running Workflows

For workflows that take a long time, use Background Execution so you can close the app. Check progress in Settings → Background Jobs.

Debugging Failed Steps

When a node fails:
1. Click it to see the error output
2. Fix the issue (wrong path, missing file, script error)
3. Use ▶ Run from Selected to re-run just from that node instead of restarting the whole workflow

What’s Next?

• AI Features — Configure AI providers and use AI-powered nodes
• Settings & Configuration — Set up email notifications, scheduler, and more
• Tool Library — Create and manage reusable tool packages
• Reference — Troubleshooting execution issues, API endpoints, and glossary