GraphRAG Workbench: a local 3D view of a GraphRAG knowledge graph

What the workbench wraps and what it adds

GraphRAG Workbench is a local workbench for turning documents into an inspectable 3D knowledge graph. It wraps Microsoft GraphRAG with local document preparation, indexing controls, a live terminal, project management and the original Three.js graph, and it is described as a dedicated open-source desktop-style web app: clone it, run it, and configure local or cloud models inside the Builder.

The division of labour is stated in the licence section. Microsoft GraphRAG provides extraction, community analysis and indexing, and GraphRAG Workbench provides the local operator interface.

What the interface adds is the part that would otherwise be your own code. The Projects sheet handles naming, loading, renaming and deleting projects, plus files, statistics, builds and terminal output. The build providers are configured in the interface with per-build Local or Ollama and Cloud or OpenAI presets. The graph is full-screen with search and community isolation, and a contextual Inspector shows the selected entity and its strongest connections.

Two of the version 2.0 features are worth singling out. The live constellation population means entities and relationships appear as extraction completes and communities appear as clustering completes, so you watch the graph form rather than waiting for a finished artefact. And the indexing runs are server-owned and cancellable with persisted workflow status, so a build survives closing the Builder, which is the difference between a usable long-running operation and a fragile one.

The local data flow in the README is the whole pipeline in six lines: a text-backed PDF goes to local text extraction, then Microsoft GraphRAG 3.1, then parquet and LanceDB, then local JSON conversion, and finally the Three.js graph and Inspector. The JSON conversion step is what makes the browser side fast, since LanceDB and parquet are storage shapes rather than render shapes.

Requirements and the install sequence

The requirements are Node.js 20.9 or later, pnpm, Python 3.12 and uv. Notably, no model provider is required before the first launch, because the Builder walks you through Ollama or OpenAI setup.

The install is four commands.

git clone https://github.com/lyon-industries/graphrag-workbench.git
cd graphrag-workbench
pnpm install
uv sync --frozen

The --frozen flag on the uv sync matters, since the Python side is a pinned adapter. The pyproject.toml names the package graphrag-workbench-adapter at version 2.0.0, requires Python >=3.12,<3.13, and depends on a single package, graphrag==3.1.0, with package set to false so uv treats it as an environment rather than a distributable library. The engine is therefore pinned exactly, and a frozen sync means you get that version or an error rather than a silent upgrade.

Then you start the app.

pnpm dev

And open http://127.0.0.1:3000. The README notes that development and production commands bind to the local interface, and the package.json confirms it, with the dev script running next dev with the turbopack flag and the 127.0.0.1 hostname, and the start script doing the same for the production server. There is also a launch script that installs dependencies and builds first if either is missing, then starts, which is the one to use if you just want to run it.

Binding to the loopback interface is a sensible default for a tool that holds document content and provider credentials on disk.

Choosing Ollama or OpenAI for a build

Both provider presets can remain configured at the same time, and each indexing run has an explicit Run with Ollama or Run with OpenAI command.

The Local or Ollama preset detects the Ollama installation and service, links to the official installer when it is absent, and pulls the selected completion and embedding models with visible progress. The default preset is Gemma 4 plus EmbeddingGemma at 768 dimensions.

The Cloud or OpenAI preset accepts the API key and model names in a modal, and the key is saved in the workbench-wide .graphrag/providers.json file, restricted to the operating system account with 0600 permissions. It is outside every project, excluded from Git, and never returned to browser code.

That last property is the important one. The key lives in a file the operating system protects and the browser cannot read, which is the right way to handle a credential in a local tool where the rendering process is a web page.

The trade-off between the two is stated plainly. Ollama avoids provider token charges and keeps model processing on the workstation. OpenAI is normally faster and can use a stronger extraction model, but OpenAI indexing sends document content to the configured provider and can consume substantial model tokens.

So the choice is between cost and speed on one side, and whether your documents leave the machine on the other. For a workbench where you are indexing a corpus you care about, the local option is the one that needs no caveat, and the README's engine log surfacing helps you see quota, authentication and missing model failures as they happen rather than after the fact.

Building a project and exploring the graph

The build and inspect sequence is six steps, and the ordering matters because the graph is only meaningful once the build has run.

Open Projects. Give the project a human-readable name. Add one or more text-backed PDFs. Select Run with Ollama or Run with OpenAI and follow each workflow in the Terminal, and if the repository binding is not ready, the setup modal opens at the missing step. Close Projects to explore the graph. Then select a node to open its Inspector, and select a connected entity to traverse the graph.

The Terminal is where the work happens. During a build the engine log is tailed into it, and fatal provider failures such as exhausted quota, a rejected key or a missing model stop the run with the cause and a recovery action named.

The graph interaction is worth knowing because it is not a typical graph viewer. Cmd or Ctrl + K focuses entity search. Drag rotates, scroll zooms and right-drag pans. Isolate community focuses the selected hierarchy, which is the feature that makes a large GraphRAG graph usable, since the community structure is what GraphRAG's own summarisation is organised around.

Two limits are stated in the same section. Image-only PDFs are rejected with an explicit terminal message, and OCR is not included in 2.0. Removing a source schedules it for deletion, and the file and its derived text are deleted only after the replacement graph builds successfully, so a failed rebuild does not leave you with neither the old nor the new state.

Importing and exporting graph artefacts

There are two import paths and one export, and the export format is deliberately narrow.

Import directory accepts a Microsoft GraphRAG output folder containing at least entities and relationships as JSON or parquet, and the supported parquet artefacts are converted locally before the active project is changed. Import bundle accepts a .graphrag.json file previously exported by the workbench.

Export output downloads the active project as a versioned .graphrag.json bundle containing the available entity, relationship, community, community-report and text-unit tables. Imports are validated in a temporary directory before replacing graph artefacts, so a malformed bundle does not destroy the graph you already have.

What the bundle deliberately leaves out is as important as what it has. Source documents, provider credentials, caches, logs and LanceDB indexes are not included in the portable bundle. The reason is visible in the architecture: the bundle is a graph description, not a project archive, and shipping the source PDFs in it would turn a graph export into a document leak.

The native GraphRAG output import is the path that matters for anyone who already runs GraphRAG elsewhere. If you have a working output directory, you can bring it in and use the Workbench purely as a viewer, with no model provider and no indexing run at all.

Where GraphRAG Workbench is the wrong choice

The first limitation is that it is an operator tool, not a product. There is no account, no hosted database and no remote document service, and the README is explicit that chat is intentionally absent from 2.0 while its next interaction model is designed. So the natural next question, what does the graph tell me, is not answered by the tool yet. If you need to query the graph as part of an application, you are building on GraphRAG directly, not on the Workbench.

The second is the PDF-only input. Image-only PDFs are rejected and OCR is not included in 2.0, so a corpus of scanned documents needs OCR before it can be indexed. The README calls the PDFs text-backed, which is the requirement stated plainly rather than hidden.

The third is the model cost and the model choice. With OpenAI, indexing sends your documents to a provider and can consume substantial tokens, and the workbench does not reduce that. With Ollama, the local model has to be good enough at extraction for the graph to be worth looking at, and the default of Gemma 4 with EmbeddingGemma at 768 dimensions is a starting point rather than a recommendation for a serious corpus.

The fourth is the version pinning, in both directions. The Python side is pinned to graphrag 3.1.0 and requires Python 3.12 exactly, and the README says Microsoft GraphRAG 3.1.0 is pinned with uv. A team that wants a different GraphRAG version has to change the adapter, and a team on Python 3.13 has to change the environment.

The fifth is the scale question. The graph is a full-screen 3D constellation, and a large GraphRAG graph is thousands of entities and relationships. Isolate community and search are the tools for that, and a dense 3D rendering of a big graph can be slow on modest hardware, which is a different problem from the correctness of the graph.

Licence, maintenance and the cost of a local GraphRAG tool

The project is under the MIT licence, with the LICENSE file at the root of the repository, and it was built by Lyon Industries in Stavanger, Norway.

The repository is not archived and the last push was on 2026-07-18. The only published release is v0.1.0-alpha.1 from 2025-09-04, named as the first alpha, while the package.json version is 2.0.0 and the pyproject version is 2.0.0. So the release tags and the internal versions have drifted apart, and the version 2.0 features described in the README are on the main branch rather than in a tagged release. That is worth knowing if you want to pin a version.

The cost of running the workbench is that you run two toolchains. Node and pnpm for the interface, and Python with uv for the engine, plus the GraphRAG dependency tree. The quality gates the project runs are the same list a contributor would run, and they are short.

pnpm typecheck
pnpm lint
pnpm build
pnpm audit --prod
uv lock --check

The uv lock --check is the one that matters for a deployment, since it verifies the pinned GraphRAG environment has not drifted from the lock file.

The stack is a conventional modern one. The application is Next.js 16.2 with React 19.2 and TypeScript, the graph is React Three Fiber with Three.js and d3-force-3d, the engine is GraphRAG 3.1.0 on Python 3.12, storage is the local filesystem with parquet, JSON and LanceDB, and progress reaches the browser through server-sent events and persisted local logs.

The privacy posture is the reason to run it locally. Runtime documents, output, caches, logs and project archives are excluded from Git, and the only content that leaves the machine is what the configured model provider needs for its own calls. That is a clear line, and it is the line that separates this from a hosted GraphRAG service.

Editorial conclusion

GraphRAG Workbench suits a developer evaluating GraphRAG on their own documents who wants to see the graph, the community hierarchy and the evidence behind an entity without writing any pipeline code, since the whole loop from PDF to 3D graph is in the interface. It does not suit a production service, since it is a local operator tool with no account and no hosted database. Set up Ollama before you start if you want the documents to stay on your machine, and read the build provider section first, because the two providers differ in cost as well as in privacy.

Frequently asked questions

Official sources

1. License: MIT
2. lyon-industries/graphrag-workbench on GitHub
3. Project website
4. README
5. Releases