Skip to content

Script Node

The Script node executes an inline Python or Node.js script on a minion. Unlike Skill / Transform nodes, no LLM is involved: the minion runs the script directly with Python or Node.js. Use it for deterministic data processing where LLM tokens are wasteful or where the output shape must be exact.

The minion runs it with the Python / Node.js installed from its work environment tools (or, when none is installed there, python3 / node on its PATH). A minion that has neither does not take the node, so install the runtime on at least one minion of the project.

  • Reshaping data with rules an LLM might get wrong (filtering, sorting, math, regex extraction, JSON munging).
  • The output format must be byte-for-byte deterministic — for example, downstream code parses it as JSON.
  • The transform is short and obvious enough that prompting an LLM would be more work than writing the function.

Stick with Skill or Transform when the work needs fuzzy understanding (semantic dedup, summarization, classification, or natural language).

FieldDescription
script_runtime"python" or "node". Selects the interpreter the minion will spawn.
script_sourceInline source code (non-empty).
script_timeout_seconds (optional)Wall-clock timeout. Defaults to 60. Clamped to [1, 600]. Exceeding it kills the script (and any processes it started) and fails the node.

The output contract on the outgoing edge (if present) is enforced by HQ on node-complete — same path as Skill / Transform.

A Script node communicates with the rest of the graph through stdin and stdout:

  • Input: input_data (the JSON object propagated from incoming edges) is piped into the script’s stdin as a single JSON value. Read it once and parse it as JSON. The same JSON is also in the file named by the environment variable MINION_INPUT_FILE.
  • Output: the script prints a single JSON object on the last line of stdout — the lines before it are its log — or writes it to the file named by the environment variable MINION_OUTPUT_FILE, and then all of stdout is its log. That object becomes output_data and — once HQ records the node as completed — flows to the next node as its input_data.

Writing to the file suits a script that prints a lot or writes indented JSON:

import json, os
data = json.load(open(os.environ["MINION_INPUT_FILE"]))
print(f"read {len(data['items'])} items") # log, shown in the execution history
with open(os.environ["MINION_OUTPUT_FILE"], "w") as f:
json.dump({"total": len(data["items"])}, f, indent=2)

What input_data looks like depends on what comes before the script:

Before the scriptinput_data
Nothing{}
One nodeThat node’s output, as it is
Two or more nodes{ "<node id>": <that node's output>, ... }, one entry per upstream node
Nothing, inside a fan-out{ "_item": <one item>, "_index": 0, "_total": 3 }
A conditionalIts own input, with _chosen_branch and _target_node added
A reviewWhat was reviewed, as it is
A join (without a skill){ "_items": [...], "_sources": [...], "_total", "_completed", "_failed" } (with aggregation: merge, the upstream outputs merged, plus the counts)
A fan-out{ "_items": [...], "_total", "_completed", "_failed" }

The node’s panel in the editor shows this under Input (what arrives on stdin), with an example built from the edges’ contracts. If an upstream output has no contract, the panel warns you: its shape can change from run to run, and an LLM node may deliver only its whole answer in _raw. Set a contract on the edge so the script always gets the fields it reads.

import sys, json
# 1. Receive input_data from the upstream node
data = json.load(sys.stdin)
# 2. Do the work
items = [it for it in data["items"] if it["score"] >= 0.8]
# 3. Build the object to hand off downstream
output = {
"items": items,
"total": len(items),
"filtered_at": "2026-05-10",
}
# 4. Emit it as JSON on stdout (json.dump is safer than print —
# print appends a newline which is fine, but never emit anything
# other than this single JSON value)
json.dump(output, sys.stdout)
// 1. Read all of stdin at once, as UTF-8
const data = JSON.parse(require('fs').readFileSync(0, 'utf8'))
// 2. Do the work
const items = data.items.filter(it => it.score >= 0.8)
// 3. Build the object to hand off downstream
const output = {
items,
total: items.length,
filtered_at: '2026-05-10',
}
// 4. Emit it as JSON on stdout — and only this
process.stdout.write(JSON.stringify(output))

Each top-level key on the object you wrote to stdout shows up as a field on the next node’s input_data.

  • Next node is a Script node — same protocol in reverse. json.load(sys.stdin) / JSON.parse(require('fs').readFileSync(0, 'utf8')) returns the object, and data["items"] / data.total are the fields you set above.
  • Next node is a Skill or Transform node — the object is rendered into the minion’s prompt under an ## Input Data section, so the LLM sees items / total as named fields it can reason over.
  • Next node is a fan-out node — set fan_out_source: ".items" on the fan-out, and each element of the items array becomes the input_data of one child instance.
# stdin: { "raw_text": "apple\nbanana\ncherry" }
import sys, json
data = json.load(sys.stdin)
lines = [s.strip() for s in data["raw_text"].split("\n") if s.strip()]
# Fan-out expects an array on the field named in `fan_out_source`.
# Each element becomes one downstream instance's input_data, so wrap
# each value in an object with the fields the children expect.
json.dump({"items": [{"name": x} for x in lines]}, sys.stdout)

With fan_out_source: ".items" on the downstream fan-out, each child receives { "name": "apple" }, { "name": "banana" }, { "name": "cherry" } as its input_data.

  • Print the result last. Lines printed before the result are its log, but the result must be the last line that is not blank, as one line of JSON (indented JSON works only when it is all that stdout has; otherwise write it to MINION_OUTPUT_FILE). The ends of the log and of stderr (up to 2,000 characters each) are captured into output_summary and visible from the execution detail page.
  • In Node.js, read stdin whole. Appending process.stdin.on('data') chunks one by one breaks a multibyte character (Japanese, emoji) cut at a chunk boundary, which comes every 64 KB. Use readFileSync(0, 'utf8') as above.
  • Input and output are UTF-8. Python runs with PYTHONUTF8=1, so stdin and stdout are UTF-8 on Windows too.
  • Size limits. The input and the output (stdout, or the output file) are at most 640 KB each; larger ones fail the node. Pass the script only the fields it needs.
  • The top-level value must be a JSON object. Returning a bare array ([1, 2, 3]) or a primitive (42, "ok", null) fails the node. Wrap arrays in an object: {"items": [1, 2, 3]}.
  • Trailing newlines are fine. Both json.dump and JSON.stringify produce no trailing newline; an extra one (e.g. via print(...)) is trimmed during parsing.
  • If the outgoing edge declares a contract, HQ enforces it. The contract you set on the edge runs the same runtime validator used for Skill / Transform nodes. Missing required fields or wrong field types fail the node — even if your script otherwise succeeded. When no contract is set, the output object is passed downstream verbatim with no validation.

Open Try run in the node’s panel to run the script as it is in the editor on a minion of the project, without running the workflow. Pick the minion, edit the input (the node’s input from its last run, or an example built from the contracts) and click Run. You see what the node would report: its output, whether it matches the outgoing edge’s contract, and the log and stderr. A try stops after 50 seconds and is not added to the run history. Only project editors can try scripts, and only on minions of the new version that are online.

All failures result in status: failed, with a failure kind that says why. The end of stderr is captured into output_summary so you can debug from the execution detail page. When the workflow retries failed nodes (editor → Settings), only failures another attempt can fix are retried: a script that fails by itself would fail the same way again.

CauseFailure kindRetried
Non-zero exit code (end of stderr in the summary)script_errorNo
Neither stdout nor its last line is valid JSON, or the output file is not (its first 500 chars in the summary)script_errorNo
The output is JSON but not an object (array / number / string / null)script_errorNo
Input or output too large, unsupported script_runtimescript_errorNo
Wall-clock timeout exceeded (the script is killed)timeoutYes
The minion could not run the script (its worker was not running because the OS user minion was not signed in, or the connection to the worker dropped)run_errorYes
Output contract validation fails on outgoing edgecontract_violationNo
  • script_runtime must be "python" or "node".
  • script_source must be non-empty.
  • script_timeout_seconds (if set) must be a number in [1, 600].
  • No package installs in the initial release. Only the standard library / built-in modules of the installed runtime are available. pip install and npm install are not supported (yet) — keeping the security and supply-chain surface small.
  • The script runs in the minion’s worker, as the OS user minion (the same user its LLM runs use), in a temporary directory. There is no sandbox or filesystem isolation beyond that user’s rights. The trust boundary is identical to Skill execution: only project members can edit the graph, so anything they can write into a Skill they can write into a Script.
  • A minion runs at most 2 jobs at once, shared with its other work (Skill / Transform nodes, routines, board tasks).
  • No terminal session is created — Script nodes do not appear in the dashboard’s terminal list.
flowchart LR
Search["Skill: search"] -- SearchResults --> Script["Script: filter & rank"]
Script -- TopItems --> Report["Skill: write-report"]

The upstream Skill emits SearchResults with extra fields. A short Python script filters by score and keeps the top N — deterministic, no tokens, no LLM ambiguity. The downstream Skill then takes the cleaned TopItems and writes a human report.