Arbex scripting

Arbex is sandboxed JavaScript run by the system-arbex-js node template on system-utils, the platform’s built-in runner hosted inside the Core API. You put a script in the node’s configuration. When the node runs, the script reads the parent node’s output and returns JSON, which becomes the node’s node output.

An Arbex node sits in a session template like any other node. It has parents, it has children, and its output is immutable. The difference is that its behaviour is your code rather than a fixed configuration schema. A typical Arbex node computes metrics from a parent’s data, builds a data service payload with the heat.dataservice helpers and, when needed, a suggested Layout with heat.layout, ready for heat-system-next-dimension to publish.

When to use it

Reach for a declarative node first. tabular-to-dataservice, tabular-query, json-template and heat-system-dataservice-envelope cover most reshaping without code and are easier to review. Use Arbex when the transform has logic a schema cannot express. Scoring rules, joins across several parent outputs and event detection over a series are typical cases. So is a layout that depends on what the data turned out to contain. Arbex is also the shortest path to a custom dashboard before a project decides whether it needs a runner of its own.

What it is not

Arbex is not a general server-side runtime. There is no require, fetch or file system, scripts run under a time limit, and a script cannot call the platform or the network. It is not a client for software outside the cluster either. External software uses the HEAT v2 API, documented under APIs. Arbex runs inside the platform, on data the platform already holds.

For node limits, the profiler output and host failures, see system-arbex-js. For a self-contained authoring corpus suited to an external editor or an AI assistant, see the Arbex RAG corpus at tools/arbex/rag/.

API reference

Your node configuration script must define async function run(ctx), which reads a parent node’s output and returns JSON-serializable data.

Types for offline editing: heat-arbex.d.ts with /// <reference path="heat-arbex.d.ts" />.

Entry contract

async function run(ctx) {
  // read ctx.inputs, transform, return plain JSON
  return { ok: true };
}

• Use async because input readers call the platform over a bridge (I/O).
• Return values must survive JSON.stringify (no functions, undefined, or circular refs).
• Thrown errors set envelope status: ERROR and fail the node.

Globals vs ctx

A common mistake is expecting heat.dataservice or heat.layout on ctx. They are not on the context object.

Standard builtins (Math, JSON, Array, Date, …) are available. There is no require, fetch, or fs.

Data flow (v2 Next dashboard)

1. run(ctx) reads parent data via ctx.inputs and may build $heat-dataservice with heat.dataservice.
2. Optional suggestedLayoutConfiguration from heat.layout binds channel ids to widgets.
3. With dataserviceOutput.persistence: dataservice-root, the stored output feeds heat-system-next-dimension, then the v2 API and ui/dashboard.

Pages in this reference

Related

• system-arbex-js (profiler, timeouts, security)
• Next data service
• heat-system-next-dimension
• SDK examples: core/api/Runner/Arbex/sdk/examples/

HEAT documentation team. Last updated 2 October 2026.