Neuronpedia: an open source interpretability platform you can run yourself

What the platform is for

Neuronpedia describes itself as an open source interpretability platform, hosted at neuronpedia.org and developed under the hijohnnylin repository with TypeScript as the primary language and Apache-2.0 licensing. The README opens by pointing at a blog post about why the project was open sourced, which is a reasonable thing for a hosted interpretability service to publish.

The feature list is stated as a dense strip of keywords rather than prose, and reading it in order tells you what the platform actually does: an API, steering, activations, circuits and graphs, natural language autoencoders, the Jacobian lens, autointerp, scoring, inference, search, filter, dashboards, benchmarks, cosine similarity, UMAP, embeds, probes, sparse autoencoders, lists, exports and uploads. That is a wide surface. The through-line is that each of those is a different view over the same underlying tables of features and activations, which is why the platform can offer a graph explorer and a dashboard builder over one dataset.

The tree adds three things the README does not advertise. `architecture.key` and `architecture.png` sit at the repository root as a first-class diagram, `vercel.json` shows the webapp is shaped for Vercel deployment, and `webapp-python-client/` is a generated Python client for the API rather than something assembled by hand.

Five standalone services and a Make target for each

The README has an architecture section with a subsection titled Services Are Standalone Apps, which is the most important design statement in the repository. Each service runs directly on your machine rather than through a container orchestration layer, and the Makefile formalizes that with a naming convention it states outright: commands follow the pattern `make [app]-[action]`, and the file's own comment gives `make webapp-dev` as the example.

The Python apps are enumerated in the Makefile itself, and there are five: `autointerp`, `graph`, `inference`, `nla` and `sparsity`. The target list covers a full lifecycle for each one, with an install target, a dev target and an OpenAPI target, so `make graph-install`, `make graph-dev` and `make graph-openapi` are all real entry points. The webapp gets a wider set, adding `webapp-build`, `webapp-run` and `sdk-dry-run`, which is the one to reach for when you want to know whether a generated client still matches the API.

Shared plumbing is visible in the target names too. `db-init`, `db-check`, `db-status` and `db-reset` handle the database, `host-add`, `host-list` and `host-remove` manage what the local services are pointed at, and `engine-link`, `engine-unlink` and `engine-status` handle linking an engine in and out. That last trio matters more than it sounds: a platform with separate inference and autointerp services needs a way to connect them and a way to confirm they are connected.

Postgres with pgvector is the whole storage story

There is no exotic datastore here. The README requires Postgres 16 with the pgvector extension, and gives both a Homebrew and a Debian install line:

brew install postgresql@16 pgvector && brew services start postgresql@16
sudo apt install postgresql-16 postgresql-16-pgvector && sudo systemctl start postgresql

The README says outright why pgvector is there: Neuronpedia uses it to search explanations by meaning. That is a design decision worth sitting with, because it means natural language explanations are stored as vectors and searchable by similarity rather than only by keyword, which is what makes a search box across autointerp explanations feel usable.

Two commands get you from a running Postgres to a schema. `make db-check` verifies the platform can reach the database, and `make db-init` creates the tables and seeds the initial rows:

make db-check
make db-init

Connection details live in `apps/webapp/.env.localhost` and default to user `postgres`, password `postgres`, database `postgres` on port `5432`. If yours differ you edit `POSTGRES_PRISMA_URL` and `POSTGRES_URL_NON_POOLING` there. The two variable names tell you the webapp uses a pooled Prisma client for normal work and a separate non-pooled connection for the migrations.

Three SAEs are already configured in the tree

The repository root contains three environment files, and each names both a model and a sparse autoencoder dataset. There is one for DeepSeek R1 Distill Llama 8B with the Llama Scope SLIM PJ dataset at 32k, one for Gemma 2 2B IT with Gemmascope RES at 16k, and one for GPT-2 Small with the RES JB dataset.

This is a quietly useful detail. Config files checked into the repository that pair a model with a published SAE mean you can look at real explanations for real published features without assembling your own pipeline first. It also tells you what the platform was used against most: the Llama Scope and Gemmascope releases are the SAE datasets that most of the public interpretability conversation has been about, so the default configuration tracks the field rather than a private setup.

The Makefile also expects an inference configuration per setup, which is consistent with that. A target named `inference-list-configs` implies configurations are named things you can enumerate, and the README's setup flow asks you to configure a local inference instance for the specific model, source and SAE you are working with rather than assuming one global server.

What a local instance can and cannot do

The README is unusually clear about the two warnings it puts in front of the local database path, and both are worth reading before you start. The first: your database starts out empty, and you have to use the admin panel to import sources and data, meaning activations and explanations. The second: a local database environment has no inference servers connected, so activation testing and steering will not work until you configure a local inference instance.

That second warning is the one that shapes a first session. The browsing experience, the search over explanations and the graph explorer work against the database alone. Anything that requires running the model needs the inference service, and that service is a separate app with its own install target.

The README's own table of contents is organized by intent rather than by module, with branches for wanting a local database or more data, wanting to do webapp development, wanting to run or develop inference locally, wanting the graph server locally, wanting autointerp locally, wanting high volume autointerp explanations, and wanting to generate your own dashboards and data and add it to Neuronpedia. That last one is the least discussed and probably the most interesting for a research group, since it suggests the platform is meant to be extended with your own visualizations rather than only consumed.

Agent rules, githooks and an OpenAI key in the appendix

The repository root is crowded with assistant configuration: `.claude/`, `.cursor/`, `.gemini/`, `.aider.conf.yml`, `AGENTS.md` and `CLAUDE.md`. Two Make targets exist specifically to police this, `agent-rules-check` and `githooks-install`, and `python-lint` plus `python-lint-fix` mirror what the CI workflow runs. The pattern is that the project treats agent instructions as something to verify rather than assume.

The appendix explains why an OpenAI API key is needed for search explanations, and the Makefile comments explain where keys live: the repository root `.env` holds your personal keys including `OPENAI_API_KEY` and `HF_TOKEN`, is layered under each service's own env file, and is created by `make init-env`. So the key is not optional for the explanation search feature, and it is read from one file rather than from per-service configuration.

One detail in the Makefile deserves attention for anyone running this on a laptop. A shared secret that the webapp presents to the local inference, autointerp and graph servers defaults to `localhost-secret` and must match `INFERENCE_SERVER_SECRET` and its siblings in `apps/webapp/.env.localhost`. It is fine for local work and is exactly the kind of default you change before exposing anything.

Editorial conclusion

Neuronpedia is one of the few interpretability efforts where the deployment story is as documented as the research tooling, and the repository reflects that: five standalone services, one Make target each, and an OpenAPI client per app so the Python side is a first-class consumer rather than an afterthought. What you get locally is the full browsing and graph experience against Postgres and pgvector, not a demo, with three SAEs already configured in the tree. The costs are honest ones. Inference has to run separately before steering or activation testing works, explanations cost money through an OpenAI key, and a local database starts empty until you import. Start with the pgvector install, then `make db-check` and `make db-init` before touching the webapp, and read the appendix on importing data first, because that import step is where most of the time goes.

Frequently asked questions

Official sources

1. hijohnnylin/neuronpedia on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases