Install¶
Two paths, depending on whether you want to use ANCHOR or hack on it.
Use it (from PyPI)¶
anchor and anchor-mcp are now on your PATH globally. The wheel includes the prebuilt frontend, so no Node toolchain is required to just run it.
Installing from git source needs a frontend build first
The web UI ships prebuilt inside the PyPI wheel. Installing directly from
git source does not build the frontend.
uv tool install "git+https://github.com/Novia-RDI-Seafaring/anchor@main"
fails at the wheel build hook, which requires a prebuilt web/dist and does
not run pnpm. To install from source, build the frontend first with the
from-source recipe, or install the PyPI wheel above.
Requires Python 3.12+. CI tests Linux and runs CLI smoke checks on macOS and Windows; verify browser and PDF workflows on your target platform.
First run¶
Installed? The Quickstart takes you from here to a source-grounded value in about five minutes, no API key. It covers picking an environment (your trust boundary), wiring ANCHOR into your harness, and the first ingest.
For the project model behind it (environments, projects, data zones), see Environments and projects.
Optional extras¶
| Extra | Install | Adds |
|---|---|---|
fmus |
uv tool install 'anchor-kb[fmus]' |
FMU simulation runtime (fmpy). Without it, FMU tools fail closed unless you opt into the synthetic demo with ANCHOR_FMU_DEMO=1. |
Hack on it (from source)¶
git clone https://github.com/Novia-RDI-Seafaring/anchor
cd anchor
uv sync --extra dev # adds pytest, ruff, import-linter
pnpm --dir web install
If pnpm is not installed globally, use one of these forms instead:
Dev mode runs two processes: one for the backend, one for the frontend with hot-reload.
# terminal 1
uv run anchor serve
# terminal 2
pnpm --dir web dev
# -> backend on :8002, Vite HMR on :5173
With the npm fallback, run the frontend command as:
Storage resolves from the active project. Run inside a project folder, or
select by name with --env / --project, anchor use, or ANCHOR_ENV /
ANCHOR_PROJECT. The config precedence is: built-in defaults, the environment
env.toml, the project anchor.toml marker, then ANCHOR_* environment
variables and flags. The API key stays in ANCHOR_OPENAI_API_KEY or the
environment's gitignored .env, never in the profile.
Install from source¶
Use this when the published PyPI wheel is behind main and you want a global
anchor command with the UI. It clones the repo, builds the frontend, then
builds and installs the wheel from your local checkout.
git clone https://github.com/Novia-RDI-Seafaring/anchor && cd anchor
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
uv tool install --force .
The web UI ships prebuilt in the PyPI wheel. Installing directly from git
source (uv tool install "git+https://github.com/Novia-RDI-Seafaring/anchor@main")
does not build the frontend. It fails at the wheel build hook, which requires a
prebuilt web/dist and does not run pnpm. Build the frontend first with the
recipe above, or install the PyPI wheel.
If pnpm is not on your PATH, run the build with Corepack or npm instead:
corepack pnpm@10 --dir web install --frozen-lockfile
corepack pnpm@10 --dir web build
# or, with Node.js + npm only:
npx pnpm@10 --dir web install --frozen-lockfile
npx pnpm@10 --dir web build
Reinstall or upgrade¶
Use --force when replacing an installed ANCHOR tool with a newer wheel or a
local source checkout:
If the published PyPI wheel is behind main, install from a local checkout
instead of running uv tool install anchor-kb. The local wheel build includes
the React frontend, so build the frontend first:
cd C:\path\to\anchor
npx pnpm@10 --dir web install
npx pnpm@10 --dir web build
uv tool install --force --reinstall --refresh .
anchor serve
Use this when Node.js and npm are installed, but pnpm is not on PATH and
Corepack fails. npx pnpm@10 runs pnpm through npm for that command without
requiring a global pnpm install.
If Corepack fails with a permission error, install pnpm through npm and run the same local checkout build:
npm install -g pnpm@10
pnpm --dir web install
pnpm --dir web build
uv tool install --force --reinstall --refresh .
anchor serve
If global npm installs are blocked by Windows permissions, use a user-local npm prefix:
mkdir $env:USERPROFILE\.npm-global
npm config set prefix "$env:USERPROFILE\.npm-global"
$env:Path = "$env:USERPROFILE\.npm-global;$env:Path"
npm install -g pnpm@10
pnpm --dir web install
pnpm --dir web build
uv tool install --force --reinstall --refresh .
anchor serve
On Windows, reinstall can fail if an agent harness is still running
anchor-mcp.exe:
failed to copy ... anchor-mcp.exe: The process cannot access the file because it is being used by another process
Close the MCP client first (Claude Code, Cursor, Codex, OpenCode, or another client that registered ANCHOR). Then check for leftover ANCHOR processes:
Get-Process anchor-mcp -ErrorAction SilentlyContinue |
Select-Object Id,ProcessName,Path
Get-Process python -ErrorAction SilentlyContinue |
Where-Object { $_.Path -like '*\uv\tools\anchor-kb\*' } |
Select-Object Id,ProcessName,Path
If those processes are still present after the client is closed, stop only those ANCHOR tool processes:
Get-Process anchor-mcp -ErrorAction SilentlyContinue | Stop-Process
Get-Process python -ErrorAction SilentlyContinue |
Where-Object { $_.Path -like '*\uv\tools\anchor-kb\*' } |
Stop-Process
Then reinstall:
uv tool uninstall anchor-kb
pnpm --dir web install
pnpm --dir web build
uv tool install --force --reinstall --refresh .
If uv tool uninstall anchor-kb reports Access is denied, a process is still
holding a file inside the uv tool directory. Repeat the process check above
before trying again. Do not remove AppData\Roaming\uv\tools\anchor-kb by hand
while anchor-mcp.exe or its Python process is still running.
Gold extraction¶
Bronze and silver run locally with no external service. Gold (structured region
extraction) is where you choose. The recommended no-key path is the harness
provider: your agent reads the pages and ANCHOR embeds locally. The
Quickstart walks it end to end.
For server-side extraction with a cloud vision model, use the openai or
azure provider and a key; see Quickstart, step 6
and, for Azure specifics, the
Azure OpenAI test-drive.
Where config is read from
Settings and storage come from the selected environment, not the working
directory. Select with --env / ANCHOR_ENV / anchor use (default: the
environment named in ~/.anchor/default). The API key lives in
ANCHOR_OPENAI_API_KEY or a gitignored .env next to the profile under
~/.anchor/envs/<name>/.
Verify the install¶
anchor version # -> the installed version
anchor canvas list # -> your existing canvases (empty on a fresh install)
Canvas snapshots¶
Snapshot rendering uses Playwright Chromium and requires a running ANCHOR
server. Install the browser once before using anchor canvas snapshot:
Release process¶
ANCHOR uses tag-driven releases via PyPI's OIDC trusted publishing. Maintainers: see PUBLISHING.md in the repo for the full procedure.