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.
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.
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
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
Commands default --data-dir to ~/anchor-data. Set ANCHOR_DATA_DIR to
change the default for CLI and MCP commands. An explicit --data-dir takes
priority. Use the same path for server, ingest, and agent registration.
Reinstall or upgrade¶
Use --force when replacing an installed ANCHOR tool with a newer wheel or a
local source checkout:
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
corepack pnpm@10 --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.
Configure gold extraction¶
The bronze and silver layers run locally without any external service. The gold layer (structured region extraction) uses an OpenAI-compatible vision model. To enable it, create a .env file with your provider details:
ANCHOR_OPENAI_API_KEY=sk-...
ANCHOR_OPENAI_BASE_URL=https://api.openai.com/v1 # or your Azure / Ollama URL
ANCHOR_REGION_MODEL=gpt-5.4
ANCHOR_POLISH_MODEL=gpt-5.4
Without these, anchor serve still works. You get silver-layer extraction
(page text, page PNGs, and Docling structure), but gold regions are skipped.
Where the .env is read from
pydantic-settings loads .env from the working directory at boot. For globally-installed anchor, run the server from the directory containing your .env, or set the variables in your shell.
Verify the 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.