Configuration Reference

Runix loads configuration from runix.yaml, runix.yml, runix.json, or runix.toml.

Resolution Order

When no explicit path is passed, Runix checks the current directory in this order:

1. runix.yaml
2. runix.yml
3. runix.json
4. runix.toml

If no config file is found, Runix still starts with defaults.

Top-Level Schema

daemon:
  socket_path: ~/.runix/runix.sock
  pid_dir: ~/.runix
  data_dir: ~/.runix
  log_level: info

defaults:
  restart_policy: on-failure
  max_restarts: 10
  restart_window: 60s
  backoff_base: 1s
  backoff_max: 60s
  log_max_size: 10485760
  log_max_age: 168h
  watch_debounce: 100ms

processes:
  - name: api
    runtime: go
    entrypoint: ./cmd/api

cron:
  - name: cleanup
    schedule: "0 */6 * * *"
    command: "rm -rf /tmp/old-*"

web:
  enabled: true
  listen: localhost:9615

mcp:
  enabled: false
  transport: stdio
  listen: localhost:8090

security:
  auth:
    enabled: false
    mode: disabled
    local_only: false

metrics:
  enabled: true
  interval: 5s

secrets: {}
profiles: {}

Top-level fields:

Field	Type	Description
daemon	object	Daemon socket, PID, data dir, and log level settings
defaults	object	Default values applied to each process
processes	array	List of ProcessConfig entries
cron	array	List of cron job definitions
web	object	Web UI listen address and legacy auth block
mcp	object	MCP transport settings
security	object	Shared authentication settings
metrics	object	Metrics collector settings
secrets	map	Named secret references
profiles	map	Arbitrary profile overlays

Daemon

Field	Type	Default
socket_path	string	platform/default data dir socket
pid_dir	string	platform/default data dir
data_dir	string	platform/default data dir
log_level	string	info

Defaults

Field	Type	Default
restart_policy	enum	on-failure
max_restarts	integer	10
restart_window	duration	60s
backoff_base	duration	1s
backoff_max	duration	60s
log_max_size	integer	10485760
log_max_age	duration	168h
watch_debounce	duration	100ms

Only some defaults are copied directly onto each process today: restart_policy, max_restarts, and instances fallback behavior. The rest are consumed by the runtime subsystems.

Processes

processes is an array, not a map. Each item is a ProcessConfig.

Required Fields

Field	Type	Notes
name	string	Must be unique
entrypoint	string	Command, script, or executable

Core Fields

Field	Type	Description
runtime	string	go, python, node, bun, deno, ruby, php, auto, unknown
args	string array	Entrypoint arguments
cwd	string	Working directory; defaults to config file directory when omitted
env	string map	Environment overlay
interpreter	string	Explicit interpreter override
use_bundle	bool	Wrap Ruby execution in bundle exec
autostart	bool	Used by start_all and daemon boot startup
instances	integer	Defaults to 1
namespace	string	Namespace prefix for process names
labels	string map	Arbitrary labels
tags	string array	Arbitrary tags
instance_index	integer	Internal multi-instance index

Restart And Shutdown

Field	Type	Description
restart_policy	enum	always, on-failure, never
max_restarts	integer	Maximum restart attempts
restart_window	duration	Restart counting window
stop_signal	string	Signal name, default behavior is SIGTERM
stop_timeout	duration	Grace period before forced kill
cron_restart	string	Cron expression for scheduled restart

Watch

watch:
  enabled: true
  paths: ["./src"]
  ignore: ["node_modules", "dist"]
  debounce: 250ms

Field	Type	Description
enabled	bool	Turns file watching on
paths	string array	Paths to watch
ignore	string array	Ignore patterns
debounce	duration string	Debounce interval

Hooks

hooks is a nested object containing lifecycle commands such as pre_start, post_start, pre_stop, post_stop, pre_restart, post_restart, pre_reload, and post_reload.

Health Checks

Runix supports both the legacy healthcheck_url field and the structured healthcheck block.

healthcheck:
  type: http
  url: http://localhost:8080/health
  interval: 10s
  timeout: 5s
  retries: 3
  grace_period: 15s

Field	Type	Description
type	enum	http, tcp, command
url	string	HTTP health endpoint
tcp_endpoint	string	TCP target in host:port form
command	string	Shell command for command checks
interval	duration string	Check interval
timeout	duration string	Per-check timeout
retries	integer	Consecutive failures before unhealthy
grace_period	duration string	Delay before first check

Scheduling, Dependencies, And Limits

Field	Type	Description
depends_on	string array	Start-order dependencies
priority	integer	Lower values start earlier
extends	string	Inherit from another named process
cpu_quota	string	CPU quota expression
memory_limit	string	Memory limit expression
log_max_files	integer	Rotated log retention

Cron Jobs

cron is an array of CronJobConfig.

cron:
  - name: cleanup
    schedule: "0 */6 * * *"
    command: "rm -rf /tmp/old-*"
    enabled: true
    cwd: /tmp
    timeout: 5m

Field	Type	Notes
name	string	Required
schedule	string	Required
runtime	string	Optional runtime hint
command	string	Required
cwd	string	Working directory
env	string map	Environment values
timeout	duration	Optional timeout
enabled	bool	Explicit enable flag

Security

Shared authentication settings live under security.auth.

security:
  auth:
    enabled: true
    mode: basic
    username: admin
    password_hash: "$2a$10$..."
    local_only: false

Field	Type	Description
enabled	bool	Turns auth on
mode	enum	disabled, basic, token
username	string	Required for basic auth
password	string	Dev-only plain text password
password_hash	string	Preferred bcrypt hash
token	string	Required for token auth
local_only	bool	Skip auth for loopback requests

Validation rules:

• basic mode requires username and exactly one of password or password_hash
• token mode requires a token with length at least 16
• disabled mode ignores credential fields

Web, MCP, Metrics, Secrets, Profiles

These are covered in dedicated pages:

• Web And Auth Configuration
• MCP
• API Schema