shep 🐑

A process manager written in Rust. One binary runs a daemon called the
shepherd, which keeps a flock of your long-running processes alive, restarts
them when they die, captures what they print, and says plainly when something
is wrong.

Every command answers with the whole flock, not just the sheep you touched.
The face in the STATUS column is the fastest thing on the page to read:
(o.o) online, (o~o) starting, (>_<) waiting to restart, (-.-) stopped,
(x.x) errored.

Status: 0.1.24, and pre-1.0 means anything can still change. macOS, Linux
and Windows. The Windows tier is the newest of the three, and the three
things it will not do are under Windows below.

Install

cargo install shep
shep welcome

Coming from pm2

shep is a clean-room reimplementation of pm2's feature list, and shep import
turns whatever pm2 save last wrote into a Flockfile. It reads --from, or
~/.pm2/dump.pm2, and starts nothing.

The difference worth switching for is that shep tells you the truth about what
it did. shep reload does not claim zero-downtime, because shep never binds
your app's listening socket and so cannot promise it. A refusal names the
sheep, the path it tried, and what to change. A command that touched one
sheep still shows you the other eleven, because the question you actually
had was whether anything else moved.

Where the sheep vocabulary would cost clarity it gets dropped. kill is
called kill, errors are plain technical English, and every themed verb has a
straight alias: flock is also ls, bleats is also logs.

A first flock

A Flockfile describes what should be running:

[[app]]
name = "api"
script = "./bin/api"

[[app]]
name = "worker"
script = "./bin/worker"

$ shep start ./Flockfile.toml
┌────┬────────┬──────────────┬───────┬──────────┬──────┬─────┬────────┬────────┬──────┬──────┐
│ ID │ NAME   │ STATUS       │ PID   │ RESTARTS │ EXIT │ CPU │ MEM    │ UPTIME │ FOLD │ SMIT │
├────┼────────┼──────────────┼───────┼──────────┼──────┼─────┼────────┼────────┼──────┼──────┤
│ 0  │ api    │ (o.o) online │ 30115 │ 0        │ -    │ -   │ 640.0K │ 0s     │ -    │ -    │
│ 1  │ worker │ (o.o) online │ 30116 │ 0        │ -    │ -   │ 1.2M   │ 0s     │ -    │ -    │
└────┴────────┴──────────────┴───────┴──────────┴──────┴─────┴────────┴────────┴──────┴──────┘

shep save writes that down, and shep startup installs the service that
brings it back after a reboot.

Following output

$ shep bleats --no-follow --lines 4
api | api listening on :8080
worker | worker ready

bleats follows by default, so drop --no-follow to keep watching.
A sheep that already crashed has said everything it is going to say, so
--lines prints that history before following rather than showing you an
empty screen.

Reloading

$ shep reload api
┌────┬────────┬────────────────┬───────┬──────────┬──────┬──────┬──────┬────────┬──────┬──────┐
│ ID │ NAME   │ STATUS         │ PID   │ RESTARTS │ EXIT │ CPU  │ MEM  │ UPTIME │ FOLD │ SMIT │
├────┼────────┼────────────────┼───────┼──────────┼──────┼──────┼──────┼────────┼──────┼──────┤
│ 0  │ api    │ (-.-) stopping │ 30115 │ 0        │ -    │ 0.0% │ 3.1M │ 2m 24s │ -    │ -    │
│ 3  │ api    │ (o~o) starting │ 31342 │ 0        │ -    │ -    │ -    │ 0s     │ -    │ -    │
│ 1  │ worker │ (o.o) online   │ 30116 │ 0        │ -    │ 0.0% │ 3.1M │ 2m 24s │ -    │ -    │
└────┴────────┴────────────────┴───────┴──────────┴──────┴──────┴──────┴────────┴──────┴──────┘

Two api rows, because the new instance is up before the old one goes down.
shep spawns, waits for readiness, drains, then reaps.

That overlap is not zero-downtime on its own, and reload --help says so.
shep binds its own control socket and nothing else, never your app's
listener, so both instances want the same port unless your app sets
SO_REUSEPORT on it. Without that the second one takes EADDRINUSE.

An app with a readiness_probe is reloaded the other way round: the old
instance drains first, then the new one starts in its place. One row, and a
gap while it happens. A probe asks an address, and an address cannot say
which of two instances answered it. Run both at once and the outgoing one
answers for the incoming one, so shep would call a release ready that never
bound anything. reuse_port = true says your app really does share the
socket, and buys the overlap back.

Watching it

shep lookout

Four panes over the same selection. j/k moves, / filters, q quits.
Read-only unless you pass --allow-control, and each action key arms a
confirm rather than acting on the keypress that pressed it.

Letting an agent look

shep whistle speaks the Model Context Protocol over stdio, so an agent host
can ask about your flock. It writes nothing else to stdout, because stdout is
the wire.

The four that act exist only when [whistle] allow_control = true in
shep.toml. That gate is about legibility rather than containment: whistle
runs as you, so anything it could do you can already do by hand. A boolean in
a config file has a diff and an mtime somebody can audit.

Dogs

A dog is a plugin process the shepherd supervises alongside your flock.

• shep-log-rotate rotates
  and compresses bleat logs.
• shep-deploy redeploys a sheep
  when a watched git branch moves.

shep dogs lists them, shep adopt takes one on.

Everything else

Run things       start serve stop restart reload delete stock
See what's up    flock describe bleats lookout fold barks
Survive reboots  save muster startup unstartup
Talk to a sheep  trigger signal whisper
The shepherd     ping kill reopen flush set get unset
Dogs and agents  dogs enable disable adopt rehome whistle
Foreground runs  runtime dev
Coming from pm2  import
Help             welcome init help completions style

Full documentation, including a generated reference for every flag of every
verb, is at shep-pm.com.

Windows

The day-to-day loop works: start, stop, restart, reload, flock,
describe, bleats, delete, save/muster, lookout, whistle, and the
dogs. shep talks over a named pipe instead of a unix socket, and each sheep
sits in a job object instead of a process group.

Three limits are real, and none of them is going to be papered over:

• shep stop has no polite signal to send. Windows offers nothing
  SIGTERM-shaped that can be delivered to an arbitrary process, so a sheep
  that has not opted into the shepherd channel gets its full kill_timeout
  and is then terminated. Set shutdown_with_message = true and read the
  channel if your app needs a clean shutdown. Same path as unix, except the
  handle arrives as $SHEP_CHANNEL_PIPE instead of fd 3.

• shep startup is not built. Boot-time supervision on Windows means a
  Service Control Manager service, which is a different program shape rather
  than a fifth unit template. Run shep start in your own session, or wrap
  shep runtime in NSSM or WinSW.

• user and group in a Flockfile are refused, permanently. Dropping
  privilege on Windows needs a logon session or a primary-token privilege,
  which is a different and security-sensitive feature rather than a
  different call.

Smaller things differ too, and they are listed in
docs/specs/deferred.md: most shep signal names
have no Windows delivery, and $SHEP_HOME inherits its parent's ACL rather
than being narrowed the way 0700 narrows it on unix.

Building

git clone https://github.com/shep-pm/shep
cd shep
cargo build --release
cargo test --workspace --all-features

MSRV 1.88, edition 2024. shep-core, shep-client and shep are
#![forbid(unsafe_code)]. shep-daemon denies it crate-wide and permits it in
two files: sys.rs, for adopting a descriptor the daemon inherited, and
sys_windows.rs, for the job object that holds a sheep and its lambs. That
is eight sites on unix and ten on Windows, each with its own
// SAFETY: note. shep-channel also denies it crate-wide and permits two
sites, both in endpoint.rs: taking the descriptor the shepherd names in
SHEP_CHANNEL_FD, which a process-global guard makes reachable at most once
per process, and PeekNamedPipe on Windows. The workspace's unsafe surface
is three files across two crates.

License

MIT or Apache-2.0, at your option.