Installation¶
Install a stable grag command, then connect it to your project.
Choose an installer¶
The package ships the web UI. Use plain gragdb for Python-only indexing.
Python 3.10–3.14. Python 3.13 is the shared Windows/macOS version in the CI matrix.
Linux, macOS, and Windows are all exercised in CI. For CLI + MCP use, prefer a
pipx / uv tool install: it puts a stable grag on PATH, so the MCP config
grag init writes keeps working when project virtualenvs come and go.
Windows¶
From grag 0.9.0: Windows x64 grag wheels include the OpenSSL runtime needed by LadybugDB. Ordinary wheel installs require no separate OpenSSL setup. The libraries load from grag's own package directory. Source/editable Windows installs need the runtime build step. Other platforms keep a small universal wheel without these DLLs.
Upgrading an older Windows install¶
Versions 0.8.0 and earlier do not include this fix. A missing-OpenSSL error can
appear as Could not find lbug C API shared library. Upgrade to 0.9.0 or later;
an older doctor report saying “installed” does not prove native loading succeeds.
Ladybug's Windows wheel supplies the native engine; ordinary grag wheel installs
do not require manually downloading the separate C-API DLL used by grag's CI tests.
Human CLI output escapes characters a legacy terminal cannot represent. Saved configuration files and exported JSONL retain UTF-8, including Unicode paths and content. MCP protocol output remains separate from diagnostic messages.
If the harness cannot start a server¶
Some Windows agent harnesses put MCP child processes in a Job Object that kills
them on disconnect. grag requires permission to start an independent shared
daemon; if Windows denies it, grag refuses the unsafe startup and prints a
grag --db ... serve --with-mcp --port=... command. Run that command in a separate
terminal, keep it open, and reconnect your agents. They share that server, and
disconnecting an agent leaves it running. Use grag stop for a clean shutdown.
First-use downloads and offline use¶
The default install uses BM25 full-text search and does not configure an embedding provider. The native engine can download its FTS extension on first use. Optional language-pack grammars and local embedding models may also need downloads before offline use:
grag doctor # offline asset checks; no project DB opened
grag doctor --prepare # explicitly allow missing asset downloads
grag doctor # confirm cached assets now work
Use the same Python environment, operating-system user, and environment variables
as the MCP server. Doctor uses the current command's configuration; it does not
read another harness's MCP environment or change a running server's settings.
For local models, set GRAG_EMBED_PROVIDER=fastembed and the intended model/dimensions
before preparing. Set FASTEMBED_CACHE_PATH to a persistent writable cache if
the default temporary cache may be cleaned. Doctor never installs Python extras.
What preparation downloads¶
Preparation covers FTS, the optional legacy VECTOR extension, all grag-supported
grammars when the code extra is installed, and the configured local model. It
does not enable embeddings, ingest code, or send a remote embedding request.
Extension downloads use extension.ladybugdb.com and ~/.lbdb/extension;
language-pack grammars use the package's release host and per-user cache, reported
by doctor. Models use their configured provider's model host and FastEmbed cache.
First use also logs preparation before a missing asset download. Cache/download
errors retain the asset name and underlying cause.
Local storage and provider access¶
Local storage and retrieval do not send graph contents to a hosted retrieval
service. Your agent harness may send retrieved context to its model provider.
GRAG_EMBED_PROVIDER=remote also sends embedding input to the configured service.
See embeddings for the optional local model and its costs.
What doctor verifies¶
Doctor opens a temporary native database and runs Cypher, builds and queries an FTS index, loads/parses each supported installed grammar, and runs real inference for a configured local model. Separate child processes contain native crashes and timeouts. Plain checks do not download assets. An installed package or existing cache directory alone cannot produce a readiness success.
grag doctor --json returns structured install checks and ready. Exit code 1
means a required capability is unavailable; optional VECTOR absence does not
block normal FTS/exact-cosine use. Disabled extras and untested remote providers
are explicit. --timeout <seconds> sets each probe's deadline (30 seconds by
default, 300 with --prepare). Slow model preparation may need a longer deadline.
In grag 0.10.0, doctor also discovers client registrations, runtime
paths and the selected owner. Cached index observations are available from owners
that advertise passive diagnostics; ordinary inspection performs no graph reads
or refreshes. Only explicit --verify-client starts a saved launcher and reads its
existing graph, which can replay WAL or trigger refresh. Installation ready remains
separate from that MCP result. See installation discovery.
Doctor does not repair corruption or certify memory completeness. Preparation does not
replace a damaged cached binary or reinstall a missing package. Retain the exact
error and see troubleshooting.
Engine compatibility¶
Without an embedder, everything works FTS-only (BM25 is native to the engine).
LadybugDB compatibility. grag 0.10.0 pins LadybugDB 0.20.3. grag disables the
engine's cached-physical-plan fast path on every connection (CALL
enable_cached_prepared_statement='none', the upstream kill switch for the
LadybugDB/ladybug#877 family of stale-re-execution bugs) and falls back to per-statement
eviction of the private prepared-statement cache on older runtimes. Do not downgrade an existing
database in place: a file opened by 0.20.x uses storage version 47 and cannot be
opened by 0.19.1 (storage version 43). A rollback requires exporting with the
newer compatible grag/Ladybug installation and importing into a fresh database.
On the C-API backend, grag also binds integer list members with a consistent
INT64 type. The upstream 0.20.3 Python wrapper still rejects mixed integer ranges
such as [0, 128] without this adaptation. Stored embedding bytes and cosine
retrieval remain unchanged.
The 0.20.4 upgrade is deferred: release qualification observed native process failures during Windows FTS preparation and shared-owner shutdown. Use grag's pinned dependency; installing a newer Ladybug wheel separately is unqualified.