Process Lifecycle

Every process managed by Runix follows a well-defined lifecycle with hook points at each stage.

Lifecycle Stages

Start Sequence

When runix start api is executed:

1. Config validation — The ProcessConfig is validated (required fields, valid runtime, etc.)
2. Dependency resolution — If depends_on is set, wait for dependencies to reach running state
3. Runtime detection — Detect or confirm the runtime adapter (Go, Python, Node.js, Bun, Deno, Ruby, PHP)
4. pre_start hook — Execute the pre-start command (if configured). If this fails, the process enters errored state
5. Process creation — Build exec.Cmd with:
   • Setpgid: true for process group isolation
   • Stdout/stderr piped to log files via PrefixWriter
   • Environment variables merged from config
   • Working directory set from cwd
6. Start execution — cmd.Start() is called, acquiring a PID
7. post_start hook — Execute the post-start command (if configured)
8. Health checker — Started if health_check is configured
9. Metrics tracking — PID added to the metrics collector
10. Exit monitor — Goroutine started to watch for process exit

Stop Sequence

When runix stop api is executed:

1. State transition — running → stopping (atomic CAS)
2. pre_stop hook — Execute the pre-stop command (if configured)
3. Signal sent — SIGTERM to the process group (Kill(-pid, SIGTERM))
4. Wait — Wait up to stop_timeout for the process to exit
5. Force kill — If still running after timeout, send SIGKILL
6. post_stop hook — Execute the post-stop command (if configured)
7. State transition — stopping → stopped (or crashed if exit code ≠ 0)
8. Cleanup — Remove from metrics tracker, stop health checker, clean up cgroups

Restart Sequence

A restart is a stop followed by a start:

1. pre_stop → stop → post_stop
2. Calculate backoff delay (if auto-restart)
3. Wait for backoff period
4. pre_start → start → post_start

Reload Sequence

A reload is a graceful restart that re-reads configuration:

1. Reads the latest config for the process
2. Stops the current instance (with hooks)
3. Starts a new instance with the updated config (with hooks)

Error Handling

Scenario	Behavior
pre_start hook fails	Process enters errored state, does not start
cmd.Start() fails	Process enters errored state
post_start hook fails	Logged as warning, process continues running
pre_stop hook fails	Logged as warning, stop continues
Process exits with code 0	State becomes stopped
Process exits with code ≠ 0	State becomes crashed, restart may be triggered

Process Group Isolation

All processes run in their own process group (Setpgid: true). This ensures:

• SIGTERM/SIGKILL sent to the group (Kill(-pid, signal)) reaches all child processes
• Orphaned grandchildren are cleaned up
• No signal leakage between managed processes

What's Next

• Restart Policies — Configurable restart behavior
• Hooks — All 10 lifecycle hook points
• Process State Machine — The 7-state model