---
title: Install heph (and isolate dev)
modified: 2026-06-02
tags:
  - how-to
---

# Install heph (and isolate dev)

How to install `heph`/`hephd` from the forge and run the `heph.nvim` plugin,
**isolated** from in-repo development so the two never share data. No prebuilt
binaries yet — everything builds from source (works on macOS/arm64,
linux/arm64, linux/amd64).

## 1. Install the binaries from the forge

Build and install `heph` + `hephd` to `~/.cargo/bin` (on `PATH`) from a forge
ref. Until v1 is tagged, install from the branch:

```bash
cargo install --locked \
  --git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
  --branch feature/v1-prototype \
  heph hephd
```

Re-run with `--tag vX.Y.Z` once a release is cut. This needs forge SSH access
(an unlocked 1Password / ssh-agent key).

The **installed** daemon owns the default paths — socket
`$XDG_RUNTIME_DIR/heph/hephd.sock`, DB `$XDG_DATA_HOME/heph/heph.db` — i.e. your
real data.

## 2. The Neovim plugin

`heph.nvim` lives in a subdirectory of the monorepo, and lazy.nvim can't load a
subdir plugin from a bare git URL (it puts the clone *root* on `runtimepath`).
For now, point lazy at a dedicated checkout via `dir`:

```bash
git clone --branch feature/v1-prototype \
  ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
  ~/.local/share/heph/checkout
```

```lua
-- lazy.nvim spec
{
  dir = vim.fn.expand("~/.local/share/heph/checkout/heph.nvim"),
  config = function()
    require("heph").setup({}) -- connect-only: talks to the daemon you started
  end,
}
```

The plugin is **connect-only** — it talks to a `hephd` you run as a service, it
does not start one itself. Start the daemon once:

```bash
heph daemon start    # launchd agent (macOS) / systemd user service (Linux)
```

See [[run-the-daemon]] for `start`/`stop`/`restart`/`status`. Update the plugin
by `git pull`ing the checkout (and after a `cargo install` upgrade, `heph daemon
restart` to pick up the new `hephd`). (A future split of `heph.nvim` into its own
forge repo will make this a normal `{ "eblume/heph.nvim" }` spec.)

## 3. Isolate development

In-repo development must not touch the installed store. Run the dev daemon on
separate paths and point a dev Neovim at it:

```bash
mise run dev   # runs the working-tree hephd on .dev/hephd.sock + .dev/heph.db
```

```bash
# dev Neovim — the plugin reads these envs and targets the dev daemon
HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
```

The installed plugin (no envs) talks to the installed daemon; the dev Neovim
talks to the dev daemon. They never share a socket or DB. `.dev/` is gitignored.

## Related

- [[heph-nvim]] — the plugin surface and its managed-daemon lifecycle
- [[tech-spec]] — §3.1 runtime modes; the daemon's exclusive DB lock