Build / validate (pull_request) Successful in 5m45s

Details

feat(heph): bake daemon mode/hub/oidc/self-update-interval into the service

`heph daemon start`/`restart` previously hardcoded `hephd --mode local` and
only wired the bare `--self-update` bool — the poll interval and all spoke/hub
sync config (`--hub-url`, `--http-addr`, `--oidc-*`) could not be set on the
managed service without hand-editing the plist/unit (which a later
start/restart would clobber).

Generate the hephd arg vector from a DaemonConfig and add the corresponding
`heph daemon start/restart` flags: --mode, --hub-url, --http-addr,
--oidc-issuer, --oidc-audience, --oidc-client-id, and
--self-update-interval-secs. Regenerating now reads the existing service file
and preserves any flags not passed (start as well as restart), so a bare
invocation never silently drops baked config.

Closes the "pass through --self-update-interval-secs" and "bake hub/spoke
config into the generated service" backlog tasks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-08 13:25:15 -07:00

4.6 KiB

Raw Permalink Blame History

title

modified

Run the heph daemon

heph and heph.nvim are thin clients — they talk to a hephd daemon over a unix socket and never start one themselves (design §4). Run the daemon as an OS-managed service with heph daemon:

heph daemon start      # install + start (idempotent)
heph daemon status     # is it installed/running? where are its socket/db/log?
heph daemon restart    # restart — run this after upgrading the binary
heph daemon stop       # stop it now
heph daemon uninstall  # stop and remove the service for good

All verbs are idempotent — start when it's already running is a no-op, stop when it's already stopped is fine.

What it manages

macOS — a launchd LaunchAgent (org.hephaestus.hephd) at ~/Library/LaunchAgents/org.hephaestus.hephd.plist, with RunAtLoad + KeepAlive (starts at login, restarts if it crashes).
Linux — a systemd user service (heph.service) at ~/.config/systemd/user/heph.service, with Restart=always, enabled for login.

Upgrading from an older install: earlier units used Restart=on-failure, which does not respawn after a clean exit — so opt-in self-update (which exits cleanly to hand off to the new binary) wouldn't come back on Linux. Run heph daemon restart once (it regenerates the unit) to pick up Restart=always.

By default it runs hephd --mode local against the default store (~/.local/share/heph/heph.db) and socket, with logs at ~/.local/share/heph/hephd.log. Pass flags to start/restart to bake a different runtime config into the service (see below).

stop vs uninstall: stop halts the daemon now, but the service is still installed, so on macOS it starts again at next login. Use uninstall to stop it persistently.

Baking sync config (spoke / hub)

By default the service runs a standalone --mode local daemon. To make the managed service a spoke (background-syncs to a hub) or a hub (--mode server), pass the corresponding hephd flags to start (or restart) — they get baked into the generated plist/unit:

# Spoke: sync to a hub, authenticating with OIDC
heph daemon start \
  --hub-url http://hub.example:8787 \
  --oidc-issuer https://idp.example/application/o/heph/ \
  --oidc-client-id heph

# Hub: expose the authenticated sync endpoint
heph daemon start --mode server \
  --http-addr 0.0.0.0:8787 \
  --oidc-issuer https://idp.example/application/o/heph/ \
  --oidc-audience heph

Bakeable flags: --mode, --hub-url, --http-addr, --oidc-issuer, --oidc-audience, --oidc-client-id, --self-update, --self-update-interval-secs. Regenerating preserves what's already baked in — start/restart read the existing service file and carry over any flags you don't pass, so a bare heph daemon restart never drops your spoke/hub or self-update config. Pass a flag again to add or override it.

Spoke sync is HTTP-only today (hephd's sync client doesn't speak HTTPS) — a --hub-url over the tailnet or behind a TLS-terminating proxy is the usual setup.

After upgrading

When you rebuild/reinstall (cargo install … --force), the running daemon is still the old binary until you restart it:

heph daemon restart

Self-update (opt-in)

hephd can keep itself current: heph daemon start --self-update generates a service that polls the forge for newer releases and, when one appears, rebuilds via cargo install (anonymous HTTPS clone of the public repo — no credentials) and restarts onto the new binary. It is off by default; the generated service also gets a PATH that can find cargo. Override the 6h poll cadence with --self-update-interval-secs <secs>. Both start and restart preserve an already-baked self-update setting (and its interval), so a bare invocation won't silently disable it — pass --self-update again only to turn it on later. Requires the Rust toolchain (cargo) installed for the service user.

Development isolation

heph daemon manages the installed daemon on the default paths. For in-repo development, run the working-tree daemon on separate paths instead and point a dev Neovim/CLI at it (never touches your real store):

mise run dev                                              # working-tree hephd on .dev/ paths
HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
HEPH_SOCKET="$PWD/.dev/hephd.sock" heph next

install-heph — install heph/hephd and the plugin
design — §4 the connect-only surface model

4.6 KiB Raw Permalink Blame History