Heliox IDE

This page is the terse reference. For the reasoning and workflows behind each of these, see Cross-Runtime SDKs and Serve & Deploy.

The `.flow.json` format

Exporting a flow produces a HelioxFlowExport document, format version "1" (HELIOX_FLOW_FORMAT_VERSION).

Top-level fields

Field	Type	Notes
`version`	`string`	Wire format version — currently `"1"`.
`id`	`string`	Flow identifier.
`name`	`string`	Human-readable flow name.
`rootStepId`	`string`	Id of the first step (no dependencies).
`steps`	`HelioxFlowStep[]`	Deterministic topological order — dependency-free first, ties broken by id ascending.
`loops`	`HelioxFlowLoop[]` (optional)	Bounded loop-back edges. Omitted entirely when the flow has none.
`meta`	`object` (optional)	`{ description?, tags?, author?, version? }` — human-facing only, omitted entirely when the flow declares none of the four. Distinct from the top-level `version` (that one’s the wire-format version).

Step fields (`HelioxFlowStep`)

Field	Type	Notes
`id`	`string`	Unique step id.
`type`	`string`	`llm_call` \| `tool_call` \| `router`.
`prompt`	`string`	The step’s prompt template.
`dependsOn`	`string[]`	Upstream step ids.
`systemPrompt`	`string` (optional)	Flattened from the step’s role(s), joined with `\n\n`. Omitted when the step has no role.
`tools`	`string[]`	Tool names available to the step (always present, may be empty).
`context`	`object` (optional)	Flattened mental-context map (id → text). Omitted when empty.
`contract`	`StepContract` (optional)	Carried opaquely — this format never interprets it.
`model`	`string` (optional)	Per-step model override, e.g. `"openai/gpt-4o-mini"` or `"conn:<connectionId>/<modelId>"`.
`description`	`string` (optional)	Human-facing only; never consulted by execution.

Loop fields (`HelioxFlowLoop`)

Field	Type	Notes
`id`	`string`	Loop identifier.
`sourceStepId`	`string`	Step after which control returns to `targetStepId`.
`targetStepId`	`string`	Upstream step the loop body restarts from.
`maxIterations`	`number`	Total passes, clamped to `[1, 50]` at export time.

Example


{
  "version": "1",
  "id": "hello-flow",
  "name": "Hello Flow",
  "rootStepId": "step-a",
  "steps": [
    {
      "id": "step-a",
      "type": "llm_call",
      "prompt": "Summarize the input text in one paragraph.",
      "dependsOn": [],
      "systemPrompt": "You are a technical writer.",
      "tools": []
    },
    {
      "id": "step-b",
      "type": "tool_call",
      "prompt": "Uppercase the summary produced by the previous step.",
      "dependsOn": ["step-a"],
      "tools": ["uppercase"],
      "model": "openai/gpt-4o-mini"
    }
  ],
  "meta": {
    "description": "A minimal two-step example flow.",
    "tags": ["example"],
    "version": "1.0.0"
  }
}

Round-trip fidelity is exact for everything execution-relevant (ids, dependsOn, prompts, flattened systemPrompt, tool names, contract, model, loops); role identity and mod details are intentionally flattened away, since neither the Java nor Python runtime has a concept of roles or mods as distinct entities — only the resulting systemPrompt string matters at execution time.

SDK entry points

Runtime	Entry point	Package
TypeScript	`heliox serve <flow.json>` (CLI) — or `importFlow` + the flow executor programmatically	built into `heliox-ide`
Java	`HelioxRuntime.builder()...build()`, then `.flow(name).executeAsync()`; or `FlowExecutor.execute` / `executeMultiSink` / `executeAllText` directly	`io.heliox:heliox-sdk-java` (`sdk/java`)
Python	`heliox_sdk.FlowExecutor` — `execute_all_text` / `execute_all_text_trace`	`heliox-sdk` (`sdk/python`)

See Cross-Runtime SDKs for usage examples and the conformance guarantees tying all three together.

Serve HTTP API

Route	Method	Auth	Response
`/health`	`GET`	none	`200 { ok: true }`
`/flow`	`GET`	Bearer	`200 { id, name, rootStepId, steps }`
`/run`	`POST`	Bearer	`200 { completedStepIds, stepOutputs, finalOutput }` (or an SSE stream when `Accept: text/event-stream`)

Auth is Authorization: Bearer <token> on /run and /flow; /health is open. Binds 127.0.0.1 by default — see Serve & Deploy for the full CLI flags, webhook/cron triggers, and the MCP transport (--mcp), which exposes the same flow as a single MCP tool over stdio instead of HTTP.

The .flow.json format