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.
When to use
Section titled “When to use”- 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).
Configuration
Section titled “Configuration”| Field | Description |
|---|---|
script_runtime | "python" or "node". Selects the interpreter the minion will spawn. |
script_source | Inline 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.
I/O protocol
Section titled “I/O protocol”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 variableMINION_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 becomesoutput_dataand — once HQ records the node as completed — flows to the next node as itsinput_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 arrives on stdin
Section titled “What arrives on stdin”What input_data looks like depends on what comes before the script:
| Before the script | input_data |
|---|---|
| Nothing | {} |
| One node | That 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 conditional | Its own input, with _chosen_branch and _target_node added |
| A review | What 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.
Python — passing data to the next node
Section titled “Python — passing data to the next node”import sys, json
# 1. Receive input_data from the upstream nodedata = json.load(sys.stdin)
# 2. Do the workitems = [it for it in data["items"] if it["score"] >= 0.8]
# 3. Build the object to hand off downstreamoutput = { "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)Node.js — passing data to the next node
Section titled “Node.js — passing data to the next node”// 1. Read all of stdin at once, as UTF-8const data = JSON.parse(require('fs').readFileSync(0, 'utf8'))
// 2. Do the workconst items = data.items.filter(it => it.score >= 0.8)
// 3. Build the object to hand off downstreamconst output = { items, total: items.length, filtered_at: '2026-05-10',}
// 4. Emit it as JSON on stdout — and only thisprocess.stdout.write(JSON.stringify(output))How the next node sees the output
Section titled “How the next node sees the 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, anddata["items"]/data.totalare 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 Datasection, so the LLM seesitems/totalas 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 theitemsarray becomes theinput_dataof one child instance.
Fan-out hand-off — minimal example
Section titled “Fan-out hand-off — minimal example”# 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.
Pitfalls
Section titled “Pitfalls”- 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 intooutput_summaryand 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. UsereadFileSync(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.dumpandJSON.stringifyproduce no trailing newline; an extra one (e.g. viaprint(...)) 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.
Trying the script in the editor
Section titled “Trying the script in the editor”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.
Failure modes
Section titled “Failure modes”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.
| Cause | Failure kind | Retried |
|---|---|---|
| Non-zero exit code (end of stderr in the summary) | script_error | No |
| Neither stdout nor its last line is valid JSON, or the output file is not (its first 500 chars in the summary) | script_error | No |
| The output is JSON but not an object (array / number / string / null) | script_error | No |
Input or output too large, unsupported script_runtime | script_error | No |
| Wall-clock timeout exceeded (the script is killed) | timeout | Yes |
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_error | Yes |
| Output contract validation fails on outgoing edge | contract_violation | No |
Validation rules
Section titled “Validation rules”script_runtimemust be"python"or"node".script_sourcemust be non-empty.script_timeout_seconds(if set) must be a number in[1, 600].
Constraints
Section titled “Constraints”- No package installs in the initial release. Only the standard library / built-in modules of the installed runtime are available.
pip installandnpm installare 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.
Example
Section titled “Example”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.