Installation

You consume Alloy as published packages - you never clone or install its source repo. The CLI ships as @engineering11/alloy-cli, run through npx; the corpus and the MCP server ship as their own packages. Everything below serves published corpus-v* versions only.

There are two situations, and they use different entry points:

• You want your repo to host its own corpus (document itself) - the spoke path. This is what the tutorial walks through, and it starts with alloy init --spoke. Reference: Host your own corpus.
• You want to consume a central corpus someone else publishes - pin a version and resolve knowledge from it. That is the three consumer paths below.

Prerequisite: the @engineering11 registry scope

The packages live on the GitHub Packages registry under the @engineering11 scope. If you already install @engineering11/* packages you have this. Otherwise add to ~/.npmrc, with a GitHub token carrying read:packages:

@engineering11:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_TOKEN_WITH_read:packages

Verify:

npm view @engineering11/alloy-cli version

E401 means the token lacks the scope; E404 means the scope line is missing from ~/.npmrc.

Path 1 - the MCP server (the canonical agent access path)

One line, once per machine. This is how an agent session reads the corpus:

claude mcp add alloy-corpus -- npx @engineering11/alloy-mcp
claude mcp list          # expect: alloy-corpus ✓ Connected

It serves the latest published corpus through four read-only tools (resolve, search, manifest, matrix), and halts loudly if no published version exists rather than guessing. See Integrate with agents for how a consuming agent actually queries it.

Path 2 - pin a version in a repo (works in any repo, JS or not)

npx @engineering11/alloy-cli corpus pin 1.0.0    # writes committed .alloy/corpus.lock {version, view}
npx @engineering11/alloy-cli corpus sync         # fetches the corpus into ~/.alloy/cache (offline thereafter)

The committed lock is what makes agent sessions in that repo deterministic: every query passes the pinned { version, view } through. See Views and coverage for what a view is.

Path 3 - the npm package (legacy node_modules consumers)

pnpm add -D @engineering11/alloy

The retriever resolves through a strict ladder - MCP, then the pinned cache, then node_modules, then a loud halt - so a node_modules install keeps working and the MCP one-liner above is an upgrade, not a migration.

Which one do I need?

You want to...	Use
Let an agent read a central corpus	Path 1 (MCP)
Make a repo's agent sessions reproducible against a pinned release	Path 2 (corpus pin / sync)
Keep an older node_modules setup working	Path 3 (npm)
Document your own repo	The tutorial (alloy init --spoke)