Skip to main content

First-time setup

The Rystad CLIs and MCP packages live on a private Azure DevOps Artifacts feed under the @rystad scope. Set up a couple of things once — Node and a feed token (plus pnpm/uv when you build) — and you never revisit this page.

Two errors that just mean "not set up yet":

  • 404 … is not in this registry — you dropped the scope. It's @rystad/create-rystad-dashboard, not create-rystad-dashboard.
  • 401 Unauthorized — your machine isn't authenticated to the feed. Section 2 fixes it.

More first-run errors (missing pnpm/uv, Docker not ready) and their fixes live on the Debugging page.

1. Install Node.js​

Install Node.js 18 or newer (the latest LTS, 20 or 22, is recommended). npm ships with Node, so there's nothing else to install here.

node --version

You'll also need pnpm and uv later. The dashboard frontend runs on pnpm and the Flask backend installs its Python deps with uv — neither ships with Node. Install them when you first hit pnpm dev or uv sync:

  • pnpm: corepack enable pnpm (preferred) or npm install -g pnpm.
  • uv: pip install uv (needs Python 3; use pip3 if pip is Python 2).

If either command isn't found, see Debugging.

2. Authenticate to the npm feed​

Do these four once, in order.

a. Create an Azure DevOps token. Sign in to Azure DevOps, open User settings → Personal access tokens → New Token, select the Packaging → Read scope, create it, and copy it now — Azure DevOps shows it only once.

b. Base64-encode the token. The feed stores the PAT base64-encoded. Don't encode it by hand — run one command and copy the output:

# Windows (PowerShell)
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("PASTE_YOUR_PAT"))
# macOS / Linux
printf "PASTE_YOUR_PAT" | base64

c. Add it to your user-level ~/.npmrc — not a project .npmrc (Windows: %USERPROFILE%\.npmrc; macOS/Linux: ~/.npmrc). Replace BASE64_PAT with the value from step b:

@rystad:registry=https://pkgs.dev.azure.com/RE-Technology/_packaging/RystadEnergyNuGetFeed/npm/registry/
//pkgs.dev.azure.com/RE-Technology/_packaging/RystadEnergyNuGetFeed/npm/registry/:always-auth=true
//pkgs.dev.azure.com/RE-Technology/_packaging/RystadEnergyNuGetFeed/npm/registry/:username=RE-Technology
//pkgs.dev.azure.com/RE-Technology/_packaging/RystadEnergyNuGetFeed/npm/registry/:_password=BASE64_PAT
//pkgs.dev.azure.com/RE-Technology/_packaging/RystadEnergyNuGetFeed/npm/registry/:email=npm-requires-email-but-does-not-use-it

Keep it secret. This token belongs only in your personal ~/.npmrc — never in a project .npmrc, and never committed to git.

d. Verify. A version number (instead of 401) means you're authenticated:

npm view @rystad/create-rystad-dashboard version

3. Authenticate to the Python (uv) feed​

Only needed for backend or full-stack (create-rystad-dashboard) projects — a frontend-only React or Angular scaffold never runs uv, so skip this if that's all you need. The Flask backend installs its Python deps from the same Azure Artifacts feed, exposed as a PyPI index. Reuse the same PAT from section 2 (no base64 this time) via one of the two approaches below.

Recommended: az login + artifacts-keyring​

The generated backend's pyproject.toml already declares the feed for uv (with the required VssSessionToken username baked into the index URL) and reads your credential from the system keyring. Two one-time steps:

uv tool install keyring --with artifacts-keyring  # puts the keyring CLI on uv's PATH
az login                                          # Azure sign-in (opens a browser)

pip install artifacts-keyring is not enough for uv. Unlike pip, uv shells out to the keyring executable, so it must be on your PATH — that is what uv tool install … guarantees. uv also only consults keyring when the index URL carries a username (VssSessionToken for Azure Artifacts), which the generated pyproject.toml already includes. Miss either and the feed answers 401 Unauthorized.

Alternative: a persistent token file (~/.netrc)​

Prefer a saved token like your ~/.npmrc? uv reads credentials from a user-level ~/.netrc (Windows: %USERPROFILE%\.netrc; macOS/Linux: ~/.netrc). Add the feed host with your PAT — no base64 needed:

machine pkgs.dev.azure.com
login RE-Technology
password PASTE_YOUR_PAT

Keep it secret. Like your ~/.npmrc, this file holds a raw token — keep it in your user profile only, and never commit it to git.

Verify with a clean backend install: cd my-dash/backend && uv sync. If it still fails with dynamix_wrapper / python_logger not found, see Debugging.

4. Scaffold your first project​

You're set up. Pick your stack and scaffold with a dashboard id your team assigns (here, 300). Full run + build steps are in the Quickstart.

npx @rystad/create-rystad-dashboard my-dash --dashboard-id 300

The full-stack umbrella: a React + Vite + TypeScript frontend and a Rystad Flask backend, wired to the same dashboard id. The CLI installs both sides, then auto-starts the whole stack with docker compose up once the local prerequisites are ready (Docker running, the registry images pulled via az acr login, an aspose.license.key file, and a filled .env). Until then it prints the exact steps — see the generated RUN_LOCAL.md. Once up, open http://localhost:5000/300/ to see your dashboard behind the real gateway.

Stuck on this setup? A command failing with 401, 404, or a missing pnpm/uv/Docker is expected on a fresh machine — each has a one-line fix on the Debugging page.

Next steps​

  • Quickstart — build your first feature (React or Angular) with your AI assistant behind the guardrails.
  • Concepts — what the guardrails are doing for you.
  • Safe prompting — get better results from your AI assistant.
  • Debugging — common first-run errors and their fixes.

Working from a clone of the repo instead? The same steps live in PREREQUISITES.md at the repo root.