Erich Blume 59822d7257 C2(hephd-self-update): impl service-env-forge-access (public HTTPS, cargo on PATH)

The repo is public, so self-update needs no credentials: cargo install
--git is a plain anonymous clone (NOT the access-restricted Forgejo cargo
registry, which is what required forge.ops.eblu.me). Point INSTALL_GIT_URL
and the releases poll at the canonical public host over HTTPS — verified
end-to-end (cargo install --git https://forge.eblu.me/... --tag v1.0.3
builds a working hephd with zero auth).

Make the headless service able to run the apply path: 'heph daemon
start --self-update' (default off) generates a launchd/systemd service
that passes --self-update and bakes a PATH (incl ~/.cargo/bin) + HOME so
the minimal service env can find cargo. restart preserves the setting.
Default (no flag) services are byte-identical to before. Template + URL
behavior covered by unit tests.

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

2026-06-04 14:46:34 -07:00

3 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.

Either way it runs hephd --mode local against the default store (~/.local/share/heph/heph.db) and socket, with logs at ~/.local/share/heph/hephd.log.

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.

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. heph daemon restart preserves the setting (pass --self-update again 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

3 KiB Raw Permalink Blame History