Skip to main content
Skip to Content
DocsArchitecture

Heliox is a stack of independently-testable layers, each with a narrow job. This page maps them top to bottom, from where a flow is designed to where it eventually runs.

Canvas

The design surface. A flow is authored as a Frame node containing step nodes wired into a DAG, either drawn by hand or assembled by Text-to-Flow’s meta-agent compiler from a one-line description. The canvas is also where roles and mods get attached (dragged from the marketplace onto a step) and where checkpoints get browsed for time-travel. See Flow Design for the hands-on view of this layer.

Harness executor

The execution core. Given a flow, the harness executor:

  • Schedules the DAG — deterministic topological order (Kahn’s algorithm), dependency-free steps first, ties broken by step id ascending, so the same flow always executes the same way.
  • Expands loops — a bounded loop-back edge unrolls into per-iteration passes at schedule time; the body’s steps interleave pass-by-pass (b1@1, b2@1, b1@2, …) rather than exhausting one step’s passes before starting the next.
  • Builds context — assembles each step’s effective input (its role’s system prompt, stacked mods’ injected constraints, upstream steps’ outputs, and any mental-context notes) before invoking the model or tool.
  • Enforces contracts — after a step runs, the guardrail engine checks its StepContract against the workspace and, on failure, appends concrete corrective feedback for a bounded number of retries.
  • Routes models — resolves which model actually serves a step: a per-step override, a connection-backed BYOK selection, or the flow’s default, in that precedence.

Checkpoints and time-travel

After every step completes, the executor records an immutable checkpoint — inputs, output, model used, and progress-to-date — never mutated after the fact. This is the substrate for rewinding a run, inspecting exactly what a step saw and produced, and forking a new execution branch from any point without touching the original run. See Core Concepts.

Flow export (.flow.json)

A designed flow can be serialized to HelioxFlowExport — a vendor-neutral JSON document (dependsOn graph, flattened system prompts, tool names, opaque contract/model carry-through, bounded loops) decoupled entirely from the canvas’s internal representation. This is the seam between “designed in Heliox” and “runs anywhere.” See API Reference for the schema.

SDK runtimes

The same export runs unmodified on three independent runtimes — TypeScript (built into Heliox), Java (HelioxRuntime / FlowExecutor), and Python (heliox_sdk.FlowExecutor) — each implementing the same DAG-scheduling and loop-expansion semantics. A shared conformance suite proves they agree: identical DAG order, identical text output, the same typed-output opt-in rule, real tool invocation, contract/model round-trip, and (TS + Java) identical loop-expansion traces. See Cross-Runtime SDKs.

Serve and MCP

heliox serve loads an exported flow and exposes it two ways: an HTTP API (POST /run, GET /flow, GET /health, Bearer-token auth, loopback-by-default, optional SSE streaming) or, with --mcp, a single MCP tool over stdio that any MCP-compatible client can call. Webhook and cron/interval triggers sit on top, firing a served flow on external events instead of a direct request. See Serve & Deploy.

Signed market

Roles, mods, flows, and steps ship as a catalog of Markdown files concatenated verbatim into agent system prompts — a prompt-injection surface if left unguarded. Every file in market/ is hashed into a deterministic manifest and the manifest is signed with ed25519; the signature is verified before the catalog loads. See Roles & Mods.

Provider connections

BYOK credentials — DBeaver-style connection profiles (protocol, base URL, API token, per-model enable flags) — resolve to the actual model a step or a served flow executes against. Tokens are encrypted at rest via the OS’s secure storage and never cross into the renderer in plaintext. See Provider Connections.

Performance Frontier and Arena (supporting cast)

Two verification/benchmarking systems sit alongside the execution stack rather than inside it:

  • Performance Frontier actually runs what a flow produces — booting a real Express server, running the artifact’s own Vitest suite, checking accessibility with axe-core — and reports results with statistical confidence intervals rather than a single noisy sample, backed by a self-calibrating judge rather than a fixed, brittle rubric.
  • Arena Benchmarks models head-to-head on a leaderboard (score, cost, latency). A Benchmarked model is what heliox serve --select picks by strategy instead of a fixed id.

Neither is required to design or run a flow — they’re the tools you reach for when you need evidence a flow’s output is actually good, or evidence one model is a better fit than another.

Next steps

Last updated on
Provider ConnectionsAPI Reference