shelbi daemon

View as markdown

shelbi daemon [OPTIONS] [COMMAND]

shelbi daemon runs the hub-side daemon that listens on ~/.shelbi/hub.sock (overridable via $SHELBI_HUB_SOCK) for worker messages and appends event-verb payloads to ~/.shelbi/events.log. Bare shelbi daemon (no subcommand) is the foreground entry point that launchd/systemd call into; the install / uninstall / status / restart subcommands manage that platform supervisor on your behalf.

Subcommands

Subcommand	Description
`run`	(default — also the form launchd/systemd invoke) Bind the hub socket and accept worker messages in the foreground until killed.
`install`	Install the platform supervisor unit (launchd plist on macOS, systemd user service on Linux) so the daemon auto-starts at login and is restarted on crash. Idempotent — re-running just refreshes the unit file and reloads it.
`uninstall`	Stop the daemon and remove the platform supervisor unit.
`status`	Print a short human-readable status by wrapping `launchctl print` or `systemctl --user status`.
`restart`	Stop the daemon so the supervisor relaunches it — picks up a freshly installed binary without losing the auto-restart guarantee.

Running shelbi daemon with no subcommand is equivalent to shelbi daemon run: it binds the hub socket and stays in the foreground, ingesting worker messages until killed. That's the form the platform supervisor invokes. You rarely run it by hand except to debug ingestion.

Flags

Every subcommand accepts the same options:

Flag	Type	Default	Description
`--root <PATH>`	string	install-time default / `$SHELBI_ROOT` / `~/.shelbi`	Override the Shelbi root directory. The flag wins over both the env var and the compile-time default.
`-p, --project <PROJECT>`	string	env / cwd lookup	Project to operate on.

Reverse-forward health and tuning

Every shelbi-routed ssh invocation carries a reverse forward so remote workers can write to the hub's events log over the multiplexed channel. The TUI poller rechecks that forward on a slow cadence and repairs it if it has gone stale.

Two failure modes are transient (direct SSH stays healthy) but can be noisy in the events log, so the recheck handles them explicitly:

A flaky master_open is retried with exponential backoff before it is reported. A blip that self-heals is logged once as detail=master_open_recovered attempts=N status=established; only an outage that survives the whole retry budget logs detail=master_open_failed attempts=N status=failed.
Loopback-port exhaustion on a TCP-fallback host is surfaced distinctly as detail=loopback_port_exhausted band=<lo>-<hi>, so it reads apart from a master-open blip. Before allocating, the recheck reclaims the port its own prior master was holding, then sweeps the configured band.

These environment variables tune the behavior (all optional; sensible defaults apply):

Variable	Default	Description
`SHELBI_FORWARD_RETRY_ATTEMPTS`	`3`	Master-open attempts before a transient failure is reported. Clamped to `1..=10`.
`SHELBI_FORWARD_RETRY_BACKOFF_MS`	`250`	Base backoff between attempts; doubles each retry. Clamped to `<= 5000`.
`SHELBI_TCP_FORWARD_PORT_BASE`	`47100`	First loopback port for a TCP-fallback forward.
`SHELBI_TCP_FORWARD_PORT_SPAN`	`64`	Width of the loopback band swept on a bind collision. Widen this if you see `loopback_port_exhausted`.

Examples

Install the supervisor unit so the daemon auto-starts at login and restarts on crash:

shelbi daemon install

Check whether the daemon is running:

shelbi daemon status

Pick up a freshly installed binary without losing the auto-restart guarantee:

shelbi daemon restart

Remove the supervisor unit and stop the daemon:

shelbi daemon uninstall

Subcommands

Flags

Reverse-forward health and tuning

Examples

See also