Prerequisites

Everything that has to be true before the Quick start's one bootstrap command works. Ten minutes, once per machine.

You need	Why
Access to the `@engineering11` registry scope	Every Alloy package is private - the CLI, the MCP server (`@engineering11/alloy-mcp`, which your agent starts on its own) and any shared corpus all resolve from it. Without it `npx @engineering11/alloy-cli` 404s or 401s
Node 22 or newer, with `npm`/`npx` on your PATH	Alloy is built and tested on Node 22; `npx` is how you run the CLI
A git clone of the repo to document, on your machine, with a clean working tree	Alloy stamps every doc with the commit it was derived from - a zip download has no history to stamp
An agent harness - Claude Code, Cursor, Codex, or OpenCode - opened at that repo's root	Your agent runs almost everything; the CLI hands it skills. A browser chat cannot see your repo or run the CLI

Running Foundry? Its installer already covers the registry scope and the skills - skip to the Quick start.

The registry scope

@engineering11/* packages resolve from one of two private registries. Which one you use depends on who you are, and the two are not interchangeable - a token issued for one fails against the other.

You are	Registry	Credential
A client or partner	Cloudsmith	The entitlement token from your Engineering11 onboarding email
An Engineering11 engineer	GitHub Packages	A GitHub personal access token with `read:packages`

npm routes exactly one registry per scope, so pick the one that matches your credential. Both setups have the same shape: a token in your environment, and a two-line global ~/.npmrc that references it.

1. Put the token in your environment

This step is done in your terminal, by you. Do not paste the token into your agent's chat - the agent never needs to see it, because npx reads it from your shell environment.

# ~/.zshrc (or ~/.bashrc) - persist it, or it works in exactly one terminal tab
export ENGINEERING11_NPM_AUTH_TOKEN=<your token>

Open a new terminal and confirm it prints token is set:

echo ${ENGINEERING11_NPM_AUTH_TOKEN:+token is set}

2. Write a global `~/.npmrc`

The first line says where the scope lives; the second says how to authenticate there. The ${…} form is read from your environment at install time, so the file holds no secret.

Cloudsmith (clients)GitHub Packages (E11 engineers)

ini

# ~/.npmrc - the path is /<organization>/<repository>/; ours are both "engineering11"
@engineering11:registry=https://npm.cloudsmith.io/engineering11/engineering11/
//npm.cloudsmith.io/engineering11/engineering11/:_authToken=${ENGINEERING11_NPM_AUTH_TOKEN}

ini

# ~/.npmrc - the host is fixed; nothing per-organization in the URL
@engineering11:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${ENGINEERING11_NPM_AUTH_TOKEN}

Two details that trip people up:

Cloudsmith: the auth line must repeat the whole path, trailing slash included. A bare //npm.cloudsmith.io/:_authToken=… does not match the registry URL, so the request goes out unauthenticated and a private repository answers 404, not 401. The entitlement token is a standard npm registry credential issued to you by Engineering11; you do not need to create a Cloudsmith account or install its CLI.
GitHub Packages: the token starts ghp_ and needs the read:packages scope (classic tokens are the reliable choice; a fine-grained token needs organization Packages: read on engineering11). The registry line has no trailing slash and the auth line does.

The global file is not optional, even if your repo has its own

The bootstrap command is npx @engineering11/alloy-cli …, and npx resolves against your user-level config. A project .npmrc alone leaves that first command with a 404. Commit a project .npmrc with the same two lines too if you want CI and teammates to agree on the routing - with the ${…} interpolation, never a literal token.

pnpm users

pnpm deliberately does not expand ${…} in a project-level .npmrc, so a committed file carrying the auth line silently fails under pnpm. Keep the auth line in ~/.npmrc (as above) and only the routing line in the project file - that split works identically under npm, pnpm and Yarn Classic.

3. Verify with a read, not an install

npm view @engineering11/alloy-cli version

A version number means the scope, the host and the token all line up. That is the only thing on this page you cannot discover by reading.

In CI (optional)

Running Alloy locally? Skip this whole section.

This only matters if you wire Alloy into GitHub Actions - the self-updating corpus CI that alloy init --ci scaffolds. If you are just running Alloy on your own machine, you are done after the steps above - go straight to the Quick start. The snippets below are GitHub Actions specific; another CI system needs the same idea (a token in the environment, a ~/.npmrc that reads it) in its own syntax.

GitHub Actions is the only CI we support today

Alloy's self-updating CI (alloy init --ci) scaffolds GitHub Actions workflows and nothing else - GitLab CI, Bitbucket Pipelines, CircleCI and the rest are a future step. Registry auth on its own is plain npm, so any CI runner can pull @engineering11/* once it has the token in ~/.npmrc - but for now you would translate the GitHub Actions recipe below into your platform's syntax by hand.

On a GitHub Actions runner, let actions/setup-node write the runner's ~/.npmrc; the token arrives as NODE_AUTH_TOKEN and nothing credential-shaped is committed.

Cloudsmith (clients)GitHub Packages (E11 engineers)

yaml

- uses: actions/setup-node@v4
  with:
    node-version: 22
    registry-url: https://npm.cloudsmith.io/engineering11/engineering11/
    scope: '@engineering11'
- run: npx @engineering11/alloy-cli status
  env:
    NODE_AUTH_TOKEN: ${{ secrets.ENGINEERING11_NPM_AUTH_TOKEN }}

yaml

- uses: actions/setup-node@v4
  with:
    node-version: 22
    registry-url: https://npm.pkg.github.com
    scope: '@engineering11'
- run: npx @engineering11/alloy-cli status
  env:
    NODE_AUTH_TOKEN: ${{ secrets.ENGINEERING11_NPM_AUTH_TOKEN }}

Cache installs in CI. An uncached runner re-pulls every package on every build, which is slow for you and counts against the delivery allowance behind your entitlement token.

When it doesn't work

Symptom	Cause
`E401`/`E403` on `@engineering11/*`	The token is not exported in this shell, `~/.npmrc` was never written, or a GitHub token lacks `read:packages`
`E404` on a package that should exist	The scope line is missing, or the registry host does not match your credential. On Cloudsmith, also check the auth line repeats the full `/engineering11/engineering11/` path
`npx` 404s but `pnpm install` works	You only wrote the project `.npmrc`; `npx` reads the global one
Works in one terminal, not another	The `export` never made it into `~/.zshrc`/`~/.bashrc`
The agent says `/alloy` is not an available tool	You are in a browser chat, or the agent was not restarted from the repo root after the bootstrap. See Where you run this
The agent refuses to help with the token or `.npmrc`	The token was pasted into the chat, or commands were sent without context. Start a fresh session with the framing message in the Quick start and keep the token in your terminal
A leaked token	Tell Engineering11 and a new one is issued. A literal token in a committed file is a rotation event

→ Quick start - the one bootstrap command, then your agent does the rest. → Installation - the consumer paths, if you are pinning or serving a central corpus rather than documenting your own repo.

Prerequisites ​

The registry scope ​

1. Put the token in your environment ​

2. Write a global ~/.npmrc ​

3. Verify with a read, not an install ​

In CI (optional) ​

When it doesn't work ​

Next ​