eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 10 Packages Wiki Activity Actions
hephaestus/docs/how-to/run-the-daemon.md
Erich Blume 1315b9ce18
Some checks failed
Build / validate (pull_request) Has been cancelled
Details
docs: daemon lifecycle becomes an explicit service (connect-only surfaces) 
A surface-owned, auto-spawned daemon can't be shared once the CLI is also a
first-class client — so drop auto-spawn and manage the daemon as an OS service.

- design §4: daemon lifecycle = explicit OS service; surfaces connect-only
- heph-nvim.md: rewrite the daemon-lifecycle section (connect-only) + history
- new how-to/run-the-daemon.md (heph daemon start/stop/restart/status); indexed
- install-heph.md: post-install is `heph daemon start`; plugin no longer spawns
- tech-spec §14: mark the managed-daemon entry superseded
- changelog fragment

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-02 21:07:11 -07:00

2.2 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=on-failure, enabled for login.

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