Skip to Content
Quickstart

Quickstart

In about five minutes: install NavFlow, get events from a real system flowing into one correlated timeline, and connect an agent that reads it.

Start NavFlow

uv tool install navflow      # or: pipx install navflow
navflow up                   # daemon + console on http://localhost:8787

Open the console at http://localhost:8787 — an empty Sources page, waiting for the next step.

Add a source

The demo is a self-contained stack — a small api-server, Prometheus, and a traffic generator — plus a catalog that wires up three correlated sources, a view, and two triggers. Two files, no checkout. Start the stack NavFlow will ingest from:

curl -O https://raw.githubusercontent.com/glassflow/navflow/main/demo/docker-compose.yml
docker compose up -d

Stop the daemon from the first step (Ctrl-C) and restart it seeded with the demo catalog:

curl -O https://raw.githubusercontent.com/glassflow/navflow/main/demo/catalog.demo.yaml
NAVFLOW_CATALOG=catalog.demo.yaml navflow up

The startup log confirms the import: imported catalog.demo.yaml into catalog (3 sources, 1 views, 2 triggers).

The catalog imports only while your catalog is still empty — fine here, since you haven’t created anything yet. If you have (say, you tried the other tab first), the import is skipped silently; restart on a fresh data directory instead: NAVFLOW_CATALOG=catalog.demo.yaml navflow up --data-dir ~/navflow-demo

Open Explore, pick the api-server entity, and watch metrics, logs, and alerts merge into one timeline. To break it on purpose and watch the triggers fire, see Run the demo stack.

(Prefer no catalog at all? Sources → Discover proposes sources from your running containers — the catalog just pre-wires the correlated view and the triggers.)

Connect an agent

Agents read NavFlow over MCP. Start the MCP endpoint — a second process that proxies to the daemon (skip this if you’re on the Docker compose; it’s already running on :8788):

navflow mcp --transport streamable-http --port 8788 --navflowd http://localhost:8787

Point Claude Code at it:

claude mcp add --transport http navflow http://localhost:8788/mcp
claude mcp list      # navflow: connected

Locally there’s no auth, so the connect command needs no token; on a deployed instance that sets NAVFLOW_AUTH_TOKEN, add --header "Authorization: Bearer <token>".

In a Claude Code session:

Use navflow: list my sources and summarize what each one contains.

The agent calls the MCP tools (list_sources, catalog_describe, query, …) against the daemon. For other clients (Codex, Claude Desktop), transports, and the full tool list, see Connecting agents.

Verify

In the console, Agents → Reads lists each read as it happens, with client = mcp.

Next

  • Run the demo stack — cause an incident and watch the triggers fire.
  • Concepts — the data model.
  • Connectors — Vercel, Postgres, Prometheus, OTLP, Claude Code sessions, and more.
  • Deployment — self-host the daemon, MCP server, and TLS with Docker.
Last updated on
IntroductionConcepts