hephaestus/docs/how-to/install-heph.md

title	modified	tags
Install heph (and isolate dev)	2026-06-04	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 the latest release tag:

cargo install --locked \
  --git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
  --tag v1.0.0 \
  heph hephd

Bump --tag to upgrade to a newer release; to track unreleased work instead, swap --tag vX.Y.Z for --branch main. This needs forge SSH access (an unlocked 1Password / ssh-agent key).

heph --version / hephd --version report X.Y.Z (<git-sha>) for a tagged install and 0.0.0 (<git-sha>) for a branch/dev install — the release version is baked into the tag's manifest (main itself stays 0.0.0), and the short SHA is captured at build time so any build is traceable to its commit.

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

The plugin lives in its own forge repo, eblume/hephaestus.nvim, with the plugin at the repo root — so lazy.nvim loads it from a bare git URL. Point lazy at the forge over SSH:

-- lazy.nvim spec
{
  url = "ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.nvim.git",
  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:

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

See run-the-daemon for start/stop/restart/status. Update the plugin with :Lazy update (and after a cargo install upgrade of the binaries, heph daemon restart to pick up the new hephd).

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:

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

# 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
• v1-prototype-tech-spec — §3.1 runtime modes; the daemon's exclusive DB lock