{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Flockfile",
"type": "object",
"properties": {
"$schema": {
"description": "The editor's schema hint, read and discarded.\n\nThis is the \"future schema key\" the comment above anticipated, added\nHERE explicitly rather than by relaxing `deny_unknown_fields`: a\ntypo'd key must still fail loudly, and exactly one more key is now\nlegal. shep does not validate against the named schema and makes no\npromise about it — it is a hint for the operator's editor, which is\nthe only consumer that ever reads it.\n\nTOML Flockfiles do not need it: taplo's `#:schema <url>` directive is\na comment, invisible to serde. JSON and JSON5 have no comment an\neditor agrees to look in, which is why this field exists at all.",
"type": [
"string",
"null"
],
"default": null
},
"app": {
"type": "array",
"default": [],
"items": {
"$ref": "#/$defs/AppConfig"
}
},
"dog": {
"description": "A dog's own per-app configuration, read and discarded.\n\nAdded the same way `$schema` was, explicitly rather than by relaxing\n`deny_unknown_fields`, so a typo'd key still fails loudly and exactly\none more key is legal.\n\nIt exists because the alternative is a Flockfile no daemon will accept.\nA dog that needs per-app configuration has nowhere to put it: shep-deploy\nwants a build command for the app it deploys, which belongs beside that\napp's declaration and nowhere else, and a Flockfile carrying one was\nrefused outright by `shep start`. Measured 2026-08-28 against shep\n0.1.8: an operator following shep-deploy's own README could not register\ntheir app at all. `unknown field `build`, expected `$schema` or `app``.\n\nIt must BE a table. shep does not read what is inside it, does not\nvalidate it, and makes no promise about it. Those are two different\nclaims and only the second one is a promise not to care: the dog that\nowns a key under this table is the only thing that understands it, and\nshep refusing a document because it does not recognise another\nprogram's config is a coupling neither side wants.\n\nNested under one key rather than allowing loose top-level keys, so\nexactly one name is reserved and a typo anywhere else still fails.\n\nA map of ignored values rather than `IgnoredAny`, which would have\naccepted `dog = 5` and `dog = [\"a\"]` as happily as a table. Not reading\nwhat a dog wrote is the point; not caring whether it wrote a table at\nall is a different thing, and it would have made the one key this file\nadds the one key where a typo does not fail loudly.",
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"additionalProperties": false,
"$defs": {
"AppConfig": {
"description": "Per-app configuration — one sheep's entry in a Flockfile\n\nField names are the Flockfile contract (sheep-native; pm2 spellings are\nrejected — the importer translates them). Unknown fields are errors so\ntypos fail loudly at parse time.\n\n# Example\n```\nuse shep_core::config::AppConfig;\n\nlet app: AppConfig = toml::from_str(\"name = \\\"web\\\"\\nscript = \\\"./srv\\\"\").unwrap();\nassert!(app.autorestart); // spec default\n```",
"type": "object",
"properties": {
"action_timeout": {
"description": "How long a triggered action gets to answer on the shepherd channel\nbefore its row becomes `ActionOutcome::TimedOut`.\n\nDefaults to 3s — comfortably under the 5s an RPC caller gets when it\nsends no deadline of its own (`shep-client`'s `DEFAULT_DEADLINE`,\nmirrored daemon-side as `rpc`'s `DEFAULT_DEADLINE_MS`). The margin\nmatters more than the number: push this past that budget and a caller\nusing the plain default gives up with `DeadlineExceeded` before the\ndaemon's own honest `TimedOut` row ever reaches it. A legitimately\nslow action (a cache flush, say) can still ask for longer, but its\ncaller has to ask for a longer deadline in step —\n`Client::request_with_deadline`, the way `shep logs -f` already asks\nfor `LOG_PLANE_DEADLINE` rather than the client's default. `normalize`\nrefuses a value no caller could ever satisfy, however long a deadline\nit asks for; a value merely above the *default* budget is a caller's\nchoice to widen its own deadline, not a config error this crate can\nsee.",
"$ref": "#/$defs/UpDuration",
"default": "3s",
"init": {
"blurb": "How long a triggered action has to answer before shep gives up",
"group": "control"
}
},
"args": {
"description": "Arguments passed to the script",
"type": "array",
"default": [],
"init": {
"blurb": "Arguments passed to the script, as a list",
"group": "inputs"
},
"items": {
"type": "string"
}
},
"autorestart": {
"description": "Restart on unexpected exit",
"type": "boolean",
"default": true,
"init": {
"blurb": "Restarts the process automatically when it exits unexpectedly",
"group": "control"
}
},
"autostart": {
"description": "Start when the daemon starts / on `shep muster`",
"type": "boolean",
"default": true,
"init": {
"blurb": "Start this app when the daemon starts, and on shep muster",
"group": "control"
}
},
"channel": {
"description": "Open the shepherd channel on fd 3 for this app on its own, without\nneeding `wait_ready` or `shutdown_with_message` to imply it.\n\nDefaults to `false`: a socketpair plus two pump tasks per sheep is\nreal cost weighed against spec §14.11's single-digit-MB idle-RSS\ngoal, so a channel is opened only when something asks for one.",
"type": "boolean",
"default": false,
"init": {
"blurb": "Opens fd 3 so the app can talk to shep directly",
"group": "inputs"
}
},
"cron_restart": {
"description": "Cron pattern for scheduled restarts (croner dialect)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Restart on a schedule, written as a cron pattern",
"example": "* * * * *",
"group": "cron"
}
},
"cron_timezone": {
"description": "Timezone for `cron_restart` (IANA name)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Which timezone cron_restart is read in, as an IANA name",
"example": "US/Eastern",
"group": "cron"
}
},
"cwd": {
"description": "Working directory (default: daemon's cwd at spawn registration)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Where the process runs. Without it, the daemon's own directory",
"example": "/srv/app",
"group": "process"
}
},
"env": {
"description": "Environment for the sheep (merged over the daemon's filtered env)",
"type": "object",
"additionalProperties": {
"type": "string"
},
"default": {},
"init": {
"blurb": "Environment variables for this app, layered over the daemon's own",
"example": "{ NODE_ENV = 'production' }",
"group": "inputs"
}
},
"err_file": {
"description": "Stderr log file (default: `$SHEP_HOME/logs/<name>-<instance>-err.log`; `merge_logs` collapses to `<name>-err.log`)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Where stderr goes. Defaults to a file under $SHEP_HOME/logs",
"example": "/var/log/my-first-sheep/err.log",
"group": "process"
}
},
"exp_backoff_restart_delay": {
"description": "Initial backoff delay; grows ×1.5 capped at 15s (spec §4)\n\nDefaults to 100ms, not unset. An unstable exit (sooner than\n`min_uptime`) with neither this nor `restart_delay` configured would\notherwise restart with no delay at all, so an app that can never\nstart (a missing dependency, a bad config) would burn its whole\n`max_restarts` budget inside a second, logging the same failure\ndozens of times.\n\nAll of the above assumes `restart_delay` is unset. A fixed\n`restart_delay` takes precedence over this field on every exit,\nstable or not, so a stable exit restarts immediately only while\n`restart_delay` stays unset, and setting this field to `\"0\"`\ndisables the backoff without producing an immediate restart if a\nnonzero `restart_delay` is also configured.",
"anyOf": [
{
"$ref": "#/$defs/UpDuration"
},
{
"type": "null"
}
],
"default": "100",
"init": {
"blurb": "Starting delay between restarts, growing each time it fails again",
"example": "5s",
"group": "control"
}
},
"fold": {
"description": "Fold (group) this sheep belongs to",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "A fold to group this app with others, for commands that take one",
"example": "backend",
"group": "process"
}
},
"graceful_timeout": {
"description": "Drain window for the old instance during reload",
"$ref": "#/$defs/UpDuration",
"default": "8s",
"init": {
"blurb": "How long the old instance gets to drain during a reload",
"group": "control"
}
},
"group": {
"description": "Run as this group (unix)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Run as this group, on unix",
"example": "www-data",
"group": "process"
}
},
"ignore_watch": {
"description": "Watch ignore globs (defaults added daemon-side: dot-entries, node_modules)",
"type": "array",
"default": [],
"init": {
"blurb": "Paths watch should skip, on top of dotfiles and node_modules",
"group": "control"
},
"items": {
"type": "string"
}
},
"instances": {
"description": "Instance count (\"cluster\" = N fork instances; spec §4)",
"type": "integer",
"format": "uint32",
"default": 1,
"init": {
"blurb": "How many copies of this app to run",
"group": "process"
},
"minimum": 0
},
"interpreter": {
"description": "Interpreter override (`\"none\"` = run script directly)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "What runs the script. Set it to none to exec the file directly",
"example": "none",
"group": "process"
}
},
"kill_signal": {
"description": "Stop signal, one of `SIGTERM`/`SIGINT`/`SIGQUIT`/`SIGUSR2` (the `SIG`\nprefix and the case are both optional). Unset means `SIGTERM`.\n\nA `String` rather than a [`KillSignal`](crate::config::KillSignal) so\nthe Flockfile schema and this struct's wire form stay plain text;\n`normalize` is what refuses a name outside that set, the same split\n`cron_restart` and the watch globs already use.",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Which signal shep sends first when stopping this app",
"example": "SIGTERM",
"group": "process"
}
},
"kill_timeout": {
"description": "Grace period between stop signal and SIGKILL",
"$ref": "#/$defs/UpDuration",
"default": "1600",
"init": {
"blurb": "How long shep waits after the stop signal before SIGKILL",
"group": "control"
}
},
"listen_timeout": {
"description": "Readiness fallback window when no ready signal/probe configured",
"$ref": "#/$defs/UpDuration",
"default": "3s",
"init": {
"blurb": "How long to wait for readiness when nothing else reports it",
"group": "control"
}
},
"liveness_probe": {
"description": "Liveness probe — failures feed the restart policy (spec §7)",
"anyOf": [
{
"$ref": "#/$defs/ProbeConfig"
},
{
"type": "null"
}
],
"default": null,
"init": {
"blurb": "A health check that triggers a restart when it keeps failing",
"example": {
"kind": "http",
"target": "http://127.0.0.1:8080/healthz"
},
"group": "control"
}
},
"max_memory": {
"description": "Memory ceiling — polling enforcer restarts above this",
"anyOf": [
{
"$ref": "#/$defs/MemSize"
},
{
"type": "null"
}
],
"default": null,
"init": {
"blurb": "Restart the app if it climbs above this much memory",
"example": "512M",
"group": "control"
}
},
"max_restarts": {
"description": "Consecutive unstable exits before `errored`",
"type": "integer",
"format": "uint32",
"default": 16,
"init": {
"blurb": "How many unstable exits in a row before shep gives up",
"group": "control"
},
"minimum": 0
},
"merge_logs": {
"description": "Merge instance logs into one file pair",
"type": "boolean",
"default": false,
"init": {
"blurb": "Put every instance's output in one pair of files",
"group": "process"
}
},
"min_uptime": {
"description": "Uptime below this marks an exit as unstable",
"$ref": "#/$defs/UpDuration",
"default": "1s",
"init": {
"blurb": "An exit sooner than this counts as unstable",
"group": "control"
}
},
"name": {
"description": "Unique sheep name (required)",
"type": "string",
"default": "",
"init": {
"blurb": "A convenient and unique name for shep to display",
"example": "my-first-sheep",
"group": "process"
}
},
"out_file": {
"description": "Stdout log file (default: `$SHEP_HOME/logs/<name>-<instance>-out.log`; `merge_logs` collapses to `<name>-out.log`)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Where stdout goes. Defaults to a file under $SHEP_HOME/logs",
"example": "/var/log/my-first-sheep/out.log",
"group": "process"
}
},
"readiness_probe": {
"description": "Readiness probe — gates reload's AwaitReady (spec §7)",
"anyOf": [
{
"$ref": "#/$defs/ProbeConfig"
},
{
"type": "null"
}
],
"default": null,
"init": {
"blurb": "A health check shep waits on before it treats a reload as finished",
"example": {
"kind": "http",
"target": "http://127.0.0.1:8080/ready"
},
"group": "control"
}
},
"restart_delay": {
"description": "Fixed delay before every restart (alternative to backoff)",
"anyOf": [
{
"$ref": "#/$defs/UpDuration"
},
{
"type": "null"
}
],
"default": null,
"init": {
"blurb": "A fixed wait before every restart, instead of growing backoff",
"example": "3s",
"group": "control"
}
},
"reuse_port": {
"description": "Asserts that the app itself sets `SO_REUSEPORT` before it binds —\nshep binds nothing, so it cannot set the option on the app's behalf.\nThe child process owns the mechanism (Node ≥22's `reusePort`, Go's\n`net.ListenConfig.Control`, nginx's `reuseport`); shep's contribution\nis permission for the old and new instance to overlap during reload,\nnot the socket option itself.\n\nThat permission is what the field buys, and it is read by exactly one\nthing: which reload the daemon runs for the app.\n\n- **Unset**, and the app has a `readiness_probe`: reload is SERIAL.\n The instance being replaced is drained first and its replacement is\n spawned into the empty slot, so the app is down for the length of\n the drain. That is the cost of an honest answer — while both\n instances are up, a probe against an address cannot say which of\n them answered, and shep would take the outgoing instance's reply as\n proof the incoming one is ready.\n- **Set**: reload OVERLAPS. The replacement is spawned alongside the\n instance it replaces and takes over without a gap — if the app really does set\n `SO_REUSEPORT`. If it does not, the replacement takes `EADDRINUSE`\n and the reload fails, which is the failure this field exists to keep\n opt-in.\n\nAn app with no `readiness_probe` overlaps either way: with nothing\nprobing an address, there is no answer for the wrong instance to give.\nSo does one using `wait_ready`, because the shepherd channel a\nreplacement reports on is its own — the instance being replaced has no\nway to answer it. Both of those need `SO_REUSEPORT` as much as a\n`reuse_port` app does if they bind an address, since they are overlapped\ntoo; what this field changes is which apps get overlapped, not what an\noverlap costs.\n\nSetting this on an app that does NOT set the socket option is the one\nway to get it wrong, and shep cannot check it: the option is set\ninside the child, after the fork, on a socket shep never sees.",
"type": "boolean",
"default": false,
"init": {
"blurb": "The app sets SO_REUSEPORT itself, so reload may overlap the two instances",
"group": "process"
}
},
"script": {
"description": "Executable or script path (required)",
"type": "string",
"default": "",
"init": {
"blurb": "The script that shep should use to launch your app",
"example": "./index.js",
"group": "process"
}
},
"shutdown_with_message": {
"description": "Send `{\"kind\":\"shutdown\"}` on the shepherd channel instead of a signal",
"type": "boolean",
"default": false,
"init": {
"blurb": "Ask the app to stop over the channel instead of signalling it",
"group": "control"
}
},
"stdin": {
"description": "Open a pipe on this sheep's stdin, so `shep whisper` can write to it.\n\nDefaults to `false`, and the default is the decision rather than a\nconvenience. Without it a sheep gets `/dev/null` on fd 0, which is what\nevery sheep has had until now, and three things argue for keeping it\nthat way unless an app asks otherwise:\n\n- Flipping it for the whole flock is a behaviour change to processes\n nobody asked to change.\n- **Programs detect stdin.** A closed or null fd 0 is how a great many\n programs decide they are non-interactive — no prompt, no pager, no\n readline, no colour. Handing them a pipe silently moves them to the\n other branch.\n- It costs a descriptor and a pump task per sheep for the whole life of\n the process, against spec §14.11's single-digit-MB idle-RSS goal — the\n same budget [`Self::channel`]'s own default is protecting.\n\nUnlike `channel`, nothing implies this: `wait_ready` and\n`shutdown_with_message` both need fd 3 and so turn `channel` on for you,\nwhile nothing in shep needs a sheep's stdin except an operator typing\n`shep whisper`. A sheep without it answers a `no_stdin` row and names\nthis field.\n\nThe pipe's write end lives as long as the sheep does, so the app sees\nEOF on stdin when the process is on its way out, never before.",
"type": "boolean",
"default": false,
"init": {
"blurb": "Keeps stdin open so shep whisper can write to the process",
"group": "inputs"
}
},
"stop_exit_codes": {
"description": "Exit codes treated as clean stop (no restart)",
"type": "array",
"default": [],
"init": {
"blurb": "Exit codes that mean a clean stop, so shep will not restart",
"group": "control"
},
"items": {
"type": "integer",
"format": "int32"
}
},
"user": {
"description": "Run as this user (unix)",
"type": [
"string",
"null"
],
"default": null,
"init": {
"blurb": "Run as this user, on unix",
"example": "www-data",
"group": "process"
}
},
"wait_ready": {
"description": "Expect `{\"kind\":\"ready\"}` on the shepherd channel",
"type": "boolean",
"default": false,
"init": {
"blurb": "Wait for the app to say it is ready on the channel",
"group": "control"
}
},
"watch": {
"description": "Watch files and restart on change",
"type": "boolean",
"default": false,
"init": {
"blurb": "Restart when a file changes",
"group": "control"
}
},
"watch_delay": {
"description": "Watch debounce window (default 500ms, applied daemon-side)",
"anyOf": [
{
"$ref": "#/$defs/UpDuration"
},
{
"type": "null"
}
],
"default": null,
"init": {
"blurb": "How long to wait after a change before restarting",
"example": "500",
"group": "control"
}
},
"watch_options": {
"description": "Watch include globs (empty = watch cwd)",
"type": "array",
"default": [],
"init": {
"blurb": "Which paths to watch. Empty means the working directory",
"group": "control"
},
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"MemSize": {
"description": "A byte quantity: digits, optionally suffixed G, M or K (binary units).",
"type": "string",
"pattern": "^\\d+(G|M|K)?$"
},
"ProbeConfig": {
"description": "Readiness/liveness probe configuration (spec §7)",
"type": "object",
"properties": {
"failure_threshold": {
"description": "Consecutive failures before the probe reports unhealthy (default 3)",
"type": "integer",
"format": "uint32",
"default": 3,
"minimum": 0
},
"interval": {
"description": "Time between probes (default 10s)",
"$ref": "#/$defs/UpDuration",
"default": "10s"
},
"kind": {
"description": "Probe mechanism",
"$ref": "#/$defs/ProbeKind"
},
"target": {
"description": "URL (http), `host:port` (tcp), or command line (exec)",
"type": "string"
},
"timeout": {
"description": "Per-probe timeout (default 5s)",
"$ref": "#/$defs/UpDuration",
"default": "5s"
}
},
"additionalProperties": false,
"required": [
"kind",
"target"
]
},
"ProbeKind": {
"description": "How a health probe checks a sheep",
"oneOf": [
{
"description": "HTTP GET must return 2xx",
"type": "string",
"const": "http"
},
{
"description": "TCP connect must succeed",
"type": "string",
"const": "tcp"
},
{
"description": "Command must exit 0",
"type": "string",
"const": "exec"
}
]
},
"UpDuration": {
"description": "A duration: digits, optionally suffixed ms, h, m or s. Plain digits are milliseconds.",
"type": "string",
"pattern": "^\\d+(ms|h|m|s)?$"
}
}
}