Runix Documentation

Runix is a modern process manager and application supervisor written in Go. It manages long-running processes with lifecycle control, restart policies, file watching, cron scheduling, health checks, and real-time observability — all through a unified CLI, TUI, Web UI, and MCP interface.

What Runix Does

Runix manages processes — any long-running application written in Go, Python, Node.js, Bun, Deno, Ruby, or PHP. It handles the full lifecycle from start to stop, with automatic restarts, rolling reloads, dependency ordering, and resource limits.

Key Capabilities

Capability	Description
Process Supervision	Start, stop, restart, and reload processes with configurable restart policies and exponential backoff
Runtime Detection	Automatically detects Go, Python, Node.js, Bun, Deno, Ruby, and PHP runtimes — or specify explicitly via --runtime
Daemon Mode	Background daemon with HTTP-over-Unix-socket IPC for managing processes across sessions
Lifecycle Hooks	10 hook points (pre_start, post_start, pre_stop, etc.) for custom shell commands
File Watching	Automatic restart on file changes using fsnotify with configurable debounce and ignore patterns
Cron Scheduling	Schedule recurring tasks with standard cron expressions (5 or 6 field)
Health Checks	HTTP, TCP, and command-based health monitoring with grace periods and retry thresholds
Rolling Reload	Batched concurrent reload with optional rollback on failure
Resource Limits	CPU and memory limits via Linux cgroups v2
Multi-Instance	Run N copies of a process with a single --instances flag
Metrics	Per-process CPU, memory, threads, and FDs via /proc with Prometheus exposition format
Event System	Pub/sub event bus with persistent store for process lifecycle events
Secret Management	Resolve secrets from environment variables, files, or (planned) HashiCorp Vault
Self-Update	One-command update with SHA256 checksum verification
System Service	Install as systemd or launchd service for boot-time startup

Interfaces

Runix provides four interfaces for process management:

• CLI — 28+ commands for complete process control
• TUI — Interactive terminal dashboard built with BubbleTea
• Web UI — Browser-based dashboard with REST API and WebSocket live updates on localhost:9615
• MCP — Model Context Protocol server for AI agent integration (stdio + HTTP transports)
• Go SDK — Embeddable supervisor library for Go applications, supporting go, python, node, bun, deno, ruby, and php runtimes

Quick Example

# runix.yaml
processes:
  api:
    runtime: go
    entrypoint: ./cmd/api
    args: ["--port", "8080"]
    restart_policy: always
    max_restarts: 10
    env:
      PORT: "8080"
      LOG_LEVEL: info

  worker:
    runtime: python
    entrypoint: worker.py
    restart_policy: on-failure
    watch:
      paths: ["./src"]
      ignore: ["__pycache__", "*.pyc"]
    health_check:
      type: http
      url: http://localhost:8081/health
      interval: 10s

# Start the daemon and launch processes
runix daemon start
runix start --config runix.yaml

# Or run directly (no daemon)
runix start api

# Check status
runix list
runix status api
runix logs api --follow

Documentation Sections

• Getting Started — Install Runix and run your first process
• Architecture — Understand how Runix works internally
• Configuration — Full YAML schema and config options
• CLI Reference — Every command with flags and examples
• Features — Deep dives into each feature
• Interfaces — TUI, Web UI, MCP, and SDK documentation
• Developer Guide — Build, test, and extend Runix

Project Information

Language	Go 1.25.7+
License	See LICENSE
Repository	github.com/runixio/runix
Code Size	~21k LOC across 149 .go files
Architecture	Single binary, no CGO, static compilation