Getting started

This guide takes you from a fresh machine to a working Horus investigation. Horus is intentionally local-first: it runs on your workstation and reads from your existing systems. It never writes to production.

What Horus is

Horus is an open-source, local-first incident investigation engine. It connects runtime evidence — logs, metrics, queue state, database state — with source intelligence to produce deterministic, evidence-backed reports.

Unlike a dashboard or alerting tool, Horus does not detect incidents. It reconstructs what happened after an incident is reported, ranks suspected causes, and tells you where to look next.

Prerequisites

• Node.js 22 or later — Horus CLI runs on Node.
• No database to install — investigation history is persisted in an embedded local store at ~/.horus.
• Python 3.11+ with uv — only if you want the optional source-intelligence backend. The backend itself ships inside the Horus bundle; Python and uv are the only prerequisite.
• A Git repository you want to investigate.

Install Horus

Choose one of the following install methods. All three install the same horus binary.

curl installer

curl -fsSL https://horus.sh/install.sh | bash

The curl installer downloads the CLI from GitHub Releases and installs the optional source-intelligence backend from the wheel bundled with the same release — the backend ships inside the Horus bundle, not on PyPI. It does not configure runtime connectors.

npm

npm install -g @merittdev/horus

Homebrew

brew install meritt-dev/tap/horus

Initialize a project

Change into the repository you want to investigate and run horus init. This is the single onboarding command. It checks prerequisites (the optional source-intelligence backend — advisory only, with fix-it hints), creates a .horus/config.json in the project root, registers the project in the global registry at ~/.horus/registry.json, starts or reuses the source-intelligence host, indexes the code and stitches the queue map, and refreshes the project-knowledge snapshot.

cd /path/to/your-repo
horus init

If you have a source-intelligence host already running, point Horus at it during init. The URL is recorded verbatim and the local host spawn and index are skipped:

horus init --source http://127.0.0.1:8420

Re-running horus init is idempotent: it reuses a healthy host and refreshes the index. If the source-intelligence backend is not installed, init still writes and registers the config, skips indexing with an install hint, and exits 0 — investigations then run in degraded, runtime-only mode. You can check host status anytime with horus hosts.

Connect runtime evidence (optional)

Runtime connectors give investigations logs, metrics, errors, and queue and database state. Add them with horus connect <type>:

horus connect elasticsearch
horus connect sentry
horus connect redis

See the Connectors page for every supported type and its options.

Run your first investigation

Investigations start from a hint: an alert name, a log line, a symptom, or a free-text description. Horus resolves the hint to evidence, ranks suspected causes, and returns a report.

horus investigate "checkout latency spike"

By default, the report is printed as readable text. You can also request JSON or Markdown:

horus investigate --format json "checkout latency spike"
horus investigate --format markdown "checkout latency spike"

List and replay investigations

Every investigation is saved to your local store at ~/.horus. List recent investigations to get their IDs:

horus investigations

Replay a saved investigation to re-render the report without re-querying your systems:

horus replay <id>

Generate a postmortem

Once you have an investigation ID, draft a postmortem in Markdown:

horus postmortem <id> --output ./postmortem.md

Common first-run issues