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