eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 11 Packages Wiki Activity Actions
hephaestus/docs/how-to/run-the-daemon.md
Erich Blume 544c8bba0e C2(hephd-self-update): impl systemd Restart=always for clean-exit respawn 
Self-restart works by exiting cleanly and letting the service manager
respawn the new binary. launchd already does this (KeepAlive=true), but
the systemd user unit was Restart=on-failure, which ignores a clean
exit (code 0). Switch to Restart=always + RestartSec=1, update the unit
test, and note in run-the-daemon that existing Linux installs must
`heph daemon restart` once to regenerate the unit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-04 13:44:36 -07:00

2.5 KiB
Raw Blame History

title modified tags
Run the heph daemon 2026-06-02
how-to

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

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

Related

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