Skip to content

helix start

Start Helix as a detached background daemon. Unlike helix run (which holds the terminal), start forks a child process, writes its PID to /tmp/helix.pid, redirects all output to /tmp/helix.log, and returns control to your shell. Use it for "leave it running" workflows in dev boxes and for production processes managed by systemd or Docker healthchecks.

Usage

helix start <file|directory>

Flags

This subcommand takes no flags. The target argument is required and is passed verbatim to the underlying helix run. Configure logging, ports, and debug options through the flow YAML's helix: block, not the CLI — those settings are read by the child process when it loads the flow.

Behavior notes

  • Requires $HELIX_LICENSE. The license check runs in the parent before the child is forked; an invalid license exits 2 immediately.
  • The child is fully detached (own process group, no controlling terminal). helix start returns once the child has been launched and the PID file written.
  • PID file: /tmp/helix.pid. If a previous instance is still running, start refuses to launch a second one with the message "helix is already running (PID N) — use 'helix restart' or 'helix stop' first".
  • Log file: /tmp/helix.log (truncated on every start). All stdout and stderr from the child go here.
  • The target path is resolved to an absolute path before launch so the daemon doesn't depend on the parent's cwd.
  • The parent sleeps for 2 seconds after launch. If the PID is gone by then, the last 10 lines of /tmp/helix.log are printed to stderr so you don't miss a crash-on-start.
  • The .env auto-load runs in the parent (before fork), so credentials end up in the child's environment.

Examples

Start a flow, then check on it:

helix start app.yaml
helix status
tail -f /tmp/helix.log

Restart cleanly after editing the flow:

helix restart app.yaml

Stop the daemon:

helix stop

Source

cmd/helix/main.go lines 1223-1298 (cmdStart)

See also