folk-plugin-process

Auxiliary process supervisor plugin for Folk — starts, monitors, and restarts non-PHP sidecar processes.

Status: in active development. See folk-spec for the roadmap.

Requirements

• Rust 1.85+
• folk-api

Installation

# Cargo.toml
folk-plugin-process = "0.1"

Quick start

Add supervised processes to folk.toml:

[[process]]
name = "tailwind"
command = "npx tailwindcss -w -o public/css/app.css"
restart = "on_failure"
max_restarts = 5
restart_delay = "1s"

[[process]]
name = "vite"
command = "npx vite"
restart = "always"

Check process status via the admin RPC:

folk admin rpc process.list

Example output:

tailwind: Running
vite: Running

Configuration

The plugin reads a [[process]] array. Each entry defines one supervised process:

Key	Type	Default	Description
name	String	"unnamed"	Display name for logs and RPC output.
command	String	"true"	Shell command to execute. Parsed by whitespace.
restart	"always" | "on_failure" | "never"	"on_failure"	When to restart the process. on_failure restarts only on non-zero exit.
max_restarts	u32	5	Maximum consecutive restart attempts before marking as Failed.
restart_delay	Duration	"1s"	Delay between restart attempts.

How it works

Each [[process]] entry spawns an independent supervisor task. The supervisor starts the command via tokio::process::Command and monitors its exit status.

When a process exits, the restart policy decides what happens:

• always — Restart regardless of exit code.
• on_failure — Restart only if the exit code is non-zero.
• never — Do not restart; the process stays in Stopped state.

If a process exceeds max_restarts consecutive failures, it transitions to Failed state and stops retrying. The restart_delay is applied between each attempt.

On server shutdown (SIGTERM), each supervised process receives SIGTERM with a 5-second grace period.

RPC methods

• process.list — Returns the status of all supervised processes (Starting, Running, Stopped, or Failed).
• process.restart — Restarts a named process.

Health check

The plugin registers a "process" health check. It reports degraded if any process is in Failed state, ok otherwise.

License

MIT