yhay81/procherd

ProcHerd

Durable local process control for software agents.

Status: 0.2 release. The complete local lifecycle is implemented and tested on Linux, macOS, and Windows.

ProcHerd starts a command under a detached per-run supervisor and returns a stable run ID. A later shell, agent turn, or local tool can inspect state, wait for readiness, page through bounded logs, or stop the entire owned process tree.

procherd start \
  --lease-port web \
  --ready-port web \
  -- npm run dev -- --port {port:web}

procherd wait run_01J... --for ready --timeout 60s
procherd logs run_01J... --after 0 --limit 50
procherd stop run_01J... --grace 5s

Why

Shell backgrounding gives callers a PID, but not durable ownership. Agent workflows routinely lose background processes, fill pipes or context with output, race for local ports, confuse “spawned” with “ready,” and leave descendants behind.

ProcHerd makes those lifecycle boundaries explicit:

• stable run<ULID identity independent of process IDs;
• a detached supervisor per run, with no shared daemon to configure;
• Unix process groups or Windows Job Objects for tree cleanup;
• bounded stdout/stderr capture with monotonic cursors and full-stream digests;
• AND-composed TCP, HTTP, file, log-literal, and leased-port readiness;
• named loopback-port and private temporary-directory leases;

• maximum runtime, graceful shutdown, forced cleanup, and durable evidence;
• versioned JSON results, JSON Schemas, stable exit codes, and completions.

Install

Download a native archive from GitHub Releases, or install from a source checkout with Rust 1.85 or newer:

cargo install --path . --locked

See INSTALL.md for platform-specific, checksum- and provenance-verified native installation, updating, and removal.

Generate completion scripts with procherd completions bash (also zsh, fish, powershell, and elvish).

Start and reacquire a run

Commands are always passed as an argument vector after --; ProcHerd never reconstructs a shell string.

result=$(
  procherd --format json start \
    --max-runtime 10m \
    --ready-log "listening" \
    -- ./my-server --port 8080
)

run_id=$(printf '%s' "$result" | jq -r .run.run_id)
procherd --format json status "$run_id"
procherd --format json wait "$run_id" --for ready --timeout 30s