Skip to content

helix run

Run one or more Helix flow definitions in the foreground. This is the workhorse subcommand: it loads YAML/JSON from a single file or every file in a directory, reifies each workflow, starts the engine, and blocks until you Ctrl+C. Everything else that "runs the engine" (start, restart, debug, mcp serve) ultimately funnels through this code path.

Usage

helix run [--watch|-w] [--debug-port=N|--debug] [--log-file=PATH] <file|directory>

The target may be a single .yaml / .yml / .json file or a directory. When given a directory, every file with one of those extensions is loaded and merged. A bare helix <file> (with no subcommand) is treated as helix run <file> when the argument is an existing path.

Flags

Flag Default Description
--watch, -w off Watch the target file (or directory) and hot-reload workflows when they change. Uses a 2-second debounce.
--debug-port=N off Install the step-by-step debug controller and HTTP server on the given port (/events SSE, /cmd, /breakpoints, /trigger). The first incoming exchange blocks at processor 1.
--debug off Shorthand for --debug-port=9999.
--log-file=PATH unset Persist logs to PATH (with rotation). Overrides helix.logging.file from YAML.

Behavior notes

  • Requires $HELIX_LICENSE. The license is verified at process start; an invalid or missing license exits with code 2 before any workflow loads.
  • Automatically loads .env from the current working directory (or up to five ancestor directories). Existing environment variables win.
  • Loads helix.yaml from the working directory if present; flow-file helix: blocks are merged over those defaults.
  • Runs the full startup sequence: connectors, agents/skills/error handlers, REST blocks, hot-reload watcher, cluster manager, session store, OCR config, metrics + audit + tenant interceptors, OpenTelemetry tracing, SLA + online-eval samplers, Prometheus + OTLP exporters, health checks, management API, MCP/A2A/AG-UI/A2UI protocol servers.
  • Workflow reification runs in two passes: tool:// workflows first (so agents can resolve tool_id references), then everything else.
  • Hot reload (--watch) watches the absolute path of the target and re-reifies changed files in place.
  • Receives SIGINT/SIGTERM and shuts down gracefully via the engine's drain-timeout (configurable as helix.shutdown.drain_timeout).

Examples

Run a single flow:

helix run flow.yaml

Run every flow in the current directory with hot reload:

helix run -w .

Run with the step-debugger HTTP server on port 9999:

helix run --debug flow.yaml
curl http://localhost:9999/events  # SSE stream of debugger events

Persist logs while still streaming to stderr:

helix run --log-file=./logs/helix.log app.yaml

Source

cmd/helix/main.go lines 393-1216 (cmdRun)

See also