Skip to content
runy

process

kind: process
name: web
spec:
  cmd: pnpm
  args: [dev, --port, "${ port.web.status.value }"]
  env:
    NODE_ENV: development
  cwd: products/web
  restart: { kind: fixed, delay: 1000, max_restarts: 5, on: failure }
  watch:
    include: ["src/**"]
    exclude: ["**/*.snap"]
  health:
    web:
      http: { port: "${ port.web.status.value }", path: / }
      initial_delay: 2
      period: 1
      timeout: 5
      failures: 60
  journal:
    max_lines: 1000

Spec

Section titled “Spec”
field default
cmd the program, looked up on the daemon’s PATH or relative to cwd required
args list of arguments; each may be an expression []
env variables added to the daemon’s environment {}
cwd working directory, relative to the workspace root the root
restart the restart policy never
watch a file set whose changes restart the process none
health named health checks {}
journal.max_lines lines the journal keeps 1000

Unknown keys are rejected and reported as a diagnostic.

The process runs in its own process group with its stdout and stderr piped into its journal. A changed cmd, args, env, cwd, restart, watch or health restarts it; a changed journal.max_lines is applied to the running child.

Restart

Section titled “Restart”

restart is never (the default), always, or an object with a kind:

fields
never the process stays stopped or failed after it exits
always restart at once on
{ kind: fixed } wait delay between restarts delay (ms, default 1000), max_restarts, on
{ kind: exponential } the wait starts at initial_delay and multiplies up to max_delay initial_delay (ms, 1000), max_delay (ms, 30000), multiplier (2), max_restarts, on

on is always (the default: every exit restarts) or failure: only a non-zero exit, a death by signal or a health check that failed failures times in a row restarts the process. A clean exit under on: failure leaves it stopped, which is how a one-shot build stays finished and lets its dependents’ needs pass. max_restarts caps the attempts; after it the process is failed.

Watch

Section titled “Watch”

watch is a file set (include, exclude, prefix; see watcher). Any change in it restarts the process. It needs watchman.

Status

Section titled “Status”
{
  "pid": 4242,
  "state": "running",
  "restarts": 0,
  "started_at": 1762070000000,
  "healthy": true,
  "health": { "web": { "ok": true, "failures": 0, "checked_at": 1762070005000 } }
}
field
pid the child’s pid, null when not running
state starting, running, stopped (exited cleanly, or stopped on purpose) or failed (a non-zero exit, a signal, or the restarts ran out)
restarts restarts since the resource was applied
started_at ms since the epoch, null before the first start
exit_code present once the process exited: the code, or null when killed by a signal
healthy the process runs and every check passes (no checks: true while running)
health one entry per declared check: ok, failures in a row, checked_at, error

runy ps prints these as running healthy, running unhealthy, stopped (exit 0) and so on.

Signals

Section titled “Signals”

runy signal <ns>/process/<name> restart stops the child and starts it again on the same spec; stop stops it and leaves it stopped until the spec changes or the namespace is reactivated. A stop sends SIGTERM to the process group, waits five seconds and sends SIGKILL.