generated from eblume/project-template
Erich Blume
1315b9ce18
Some checks failed
Build / validate (pull_request) Has been cancelled
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>
66 lines
2.2 KiB
Markdown
66 lines
2.2 KiB
Markdown
---
|
|
title: Run the heph daemon
|
|
modified: 2026-06-02
|
|
tags:
|
|
- 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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|