Deploy Sirius MCP

Run the Sirius MCP server locally. Solo use is free: no license key is required.

Two install paths, pick one:

1. npx (default quick-start) — for Claude Code / Cursor / OpenCode users who want the simplest path. No Docker.
2. Docker — for persistent, VPS or team-hosted deployments.

1. Quick start with npx#

Prerequisites

• Node.js 22 or newer (installing Node also installs npm, which provides npx).
• Nothing else for solo use (no Docker, no license file, no account).

Missing Node? If you see command not found: npx (macOS/Linux) or 'npx' is not recognized (Windows), the prerequisite is Node itself: install it from https://nodejs.org (any LTS version ≥ 22), reopen your terminal, then continue below. npx is a part of npm, which ships with Node — there is no separate install step.

MCP client config

Add one short entry to your MCP client config. No path variables, no multi-line commands.

mcpServers — Claude Code (.mcp.json / ~/.claude.json), Cursor, Antigravity, Windsurf

{
  "mcpServers": {
    "sirius": {
      "command": "npx",
      "args": ["-y", "@sirius-mcp/mcp"]
    }
  }
}

mcp — OpenCode (opencode.json)

{
  "mcp": {
    "sirius": {
      "type": "local",
      "command": ["npx", "-y", "@sirius-mcp/mcp"],
      "enabled": true
    }
  }
}

-y answers the one-time "install package?" prompt automatically so the client startup never blocks. npx re-resolves the latest published version from the npm registry on every run — verified on npm 11.16.0 (Node 24.18.0, 2026-08-25): each invocation revalidates the package against the registry, so an unpinned npx @sirius-mcp/mcp always starts the newest release; appending @latest is not required.

Prefer a persistent sirius-mcp command instead of npx? Install globally with npm i -g @sirius-mcp/mcp.

Verify

Ask your agent to run context_list. If it returns documents, Sirius is installed and working.

2. Docker — persistent / VPS / team-hosted#

The Docker path is fully supported and is the recommended option when you want an immutable, version-pinned deployment (a VPS, a shared host, or a team running the same image). Use npx for quick personal installs instead.

Prerequisites

• Docker installed and running
• Nothing else for solo use (no Node.js, no license file, no account)

Install with docker run

One copy-paste command. MCP uses JSON-RPC over stdin/stdout, so -i is required. The optional port mapping (-p 127.0.0.1:4200:4200) exposes the embedded Living Architecture Web Portal. --pull=always re-fetches the image on every start so :latest never goes stale.

docker run -i --rm \
  --pull=always \
  -p 127.0.0.1:4200:4200 \
  -v "$PWD:/project" \
  -e SIRIUS_PROJECT_ROOT=/project \
  ghcr.io/sirius-mcp/sirius-mcp:latest

• Bind-mounts the current directory to /project inside the container
• Sets SIRIUS_PROJECT_ROOT so the .context/ store lives on the host
• Publishes port 4200 locally (127.0.0.1:4200) to access the Living Architecture Web Portal in your browser
• Runs as non-root (node, uid 1000)
• Pin a release with a semver tag instead of latest when you need a fixed version (see Versioning)

--pull=always and registry outages (verified behavior)

Verified empirically on Docker 29.7.2 (client and server, 2026-08-25): when the registry is unreachable, docker run --pull=always fails hard (exit code 125, failed to resolve reference) — it does not fall back to the locally cached image. The same happens when the remote tag does not exist yet, even if a matching image is cached locally. This is fail-closed, not fail-open.

If a registry outage must not break your session starts, use the explicit fallback (pull first, ignore failure, then run from cache):

docker pull ghcr.io/sirius-mcp/sirius-mcp:latest || true
docker run -i --rm \
  -v "$PWD:/project" \
  -e SIRIUS_PROJECT_ROOT=/project \
  ghcr.io/sirius-mcp/sirius-mcp:latest

docker pull refreshes the cached image when the registry is reachable; || true keeps the session alive from cache when it is not.

Equivalent docker-compose.yml

Compose is useful for local validation. It is not a 24/7 daemon: the server is interactive stdio. Real MCP clients should use docker run -i (or the client config snippets below). pull_policy: always is the Compose equivalent of --pull=always; it has the same fail-closed behavior on registry outages described above (prepend a docker compose pull || true if you need the fallback).

services:
  sirius:
    image: ghcr.io/sirius-mcp/sirius-mcp:latest
    pull_policy: always
    container_name: sirius
    stdin_open: true
    tty: true
    ports:
      - "127.0.0.1:4200:4200"
    environment:
      - SIRIUS_PROJECT_ROOT=/project
      - SIRIUS_WEB_PORTAL=1
      - SIRIUS_WEB_PORT=4200
      - SIRIUS_HOST=0.0.0.0
    volumes:
      - .:/project
    restart: "no"

docker compose up

3. Environment variables#

Solo

Living Architecture Web Portal (Phase 2)

File watcher and crawler (Phase 2)

Vector search and embeddings (optional)

Enterprise (not needed for solo use)

The phone-home validation URL is a real setting today: SIRIUS_LICENSE_SERVER_URL (defaults to a development placeholder). The production validation URL is issued with the enterprise license.

4. MCP client configuration#

Two supported commands, same MCP protocol. Pick the envelope that matches your client.

• npx command: npx -y @sirius-mcp/mcp — always runs the latest published release (see Quick start).
• Docker command: docker run -i --rm --pull=always -v "${workspaceFolder}:/project" -e SIRIUS_PROJECT_ROOT=/project ghcr.io/sirius-mcp/sirius-mcp:latest — replace ${workspaceFolder} with your project path if the client does not expand that variable.

mcpServers — Claude Code, Cursor

{
  "mcpServers": {
    "sirius": {
      "command": "npx",
      "args": ["-y", "@sirius-mcp/mcp"]
    }
  }
}

Docker variant:

{
  "mcpServers": {
    "sirius": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--pull=always",
        "-v", "${workspaceFolder}:/project",
        "-e", "SIRIUS_PROJECT_ROOT=/project",
        "ghcr.io/sirius-mcp/sirius-mcp:latest"
      ]
    }
  }
}

mcp — OpenCode

{
  "mcp": {
    "sirius": {
      "type": "local",
      "command": ["npx", "-y", "@sirius-mcp/mcp"],
      "enabled": true
    }
  }
}

Docker variant:

{
  "mcp": {
    "sirius": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "--pull=always", "-v", "${workspaceFolder}:/project", "-e", "SIRIUS_PROJECT_ROOT=/project", "ghcr.io/sirius-mcp/sirius-mcp:latest"],
      "enabled": true
    }
  }
}

Tip (Web Portal): To open the Living Architecture Web Portal in your browser while your agent works, add "-p", "127.0.0.1:4200:4200" to the args array in mcpServers or command in opencode.json.

5. Bootstrap & Smoke test#

Note: The JSON-RPC payloads below illustrate the underlying MCP wire protocol for debugging. In your day-to-day workflow, you can simply ask your coding agent (Claude Code, Cursor, OpenCode, Windsurf, Antigravity) to initialize the store or crawl the repository.

Initialize or Bootstrap an Existing Project

1. New project: Run project_init to create a fresh .context/ store:

   json

   {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"project_init","arguments":{}}}
   

2. Existing (Brownfield) codebase bootstrap: Run context_crawl to scan and ingest documentation into draft documents:

   json

   {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"context_crawl","arguments":{"path":"."}}}
   

   Supported Ecosystems & Manifests:

   • JavaScript / TypeScript: package.json
   • Java: pom.xml, build.gradle, build.gradle.kts, settings.gradle, settings.gradle.kts
   • C# / .NET: *.csproj, *.sln
   • Python: pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile
   • Go: go.mod, go.work
   • Rust: Cargo.toml

3. Verify Context: List documents in your store:

   json

   {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"context_list","arguments":{}}}
   

4. Local FTS5 Search: Query architectural patterns and decisions using fast full-text search:

   json

   {"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"context_search","arguments":{"query":"auth flow tenant isolation"}}}
   

Living Architecture Web Portal

When port 4200 is forwarded (-p 127.0.0.1:4200:4200), open http://127.0.0.1:4200 to interact with:

• Interactive D3 Topology Canvas: Visual dependency graph of all system components, decisions, features, and business rules with multi-LOD rendering.
• Document Inspector & Markdown Reader: Instant preview with YAML frontmatter HUD, Invariants Box, Boundaries Box, and Mermaid diagram visualization.
• Search Modal (⌘K / Ctrl+K): Real-time full-text search across all documents.
• SSE Status Beacon (/api/events): Real-time live reload when files in .context/ change.

If port 4200 is busy, the portal retries the next consecutive ports (up to 4209) — the URL actually bound appears in the boot log and in the context://system/web-portal resource.

Real-Time Indexing (File Watcher)

Sirius includes a native File Watcher (SIRIUS_WATCH_ENABLED=1). Any manual edits to .context/ markdown files are automatically detected and indexed into SQLite FTS5 in ≤ 2 seconds. You no longer need to call reindex manually during normal editing.

6. Volume permissions (Docker)#

The container runs as uid 1000. If the host directory is not writable by that uid, project_init and context_upsert fail with EACCES.

Two ways to fix it:

# Run the container as your own uid/gid (works on Linux and macOS)
docker run -i --rm --pull=always --user "$(id -u):$(id -g)" \
  -v "$PWD:/project" \
  -e SIRIUS_PROJECT_ROOT=/project \
  ghcr.io/sirius-mcp/sirius-mcp:latest

# Or make the directory writable by the container's uid
chown -R 1000:1000 "$PWD"

Docker Desktop on Windows usually handles permissions via the VM, but WSL2 volumes may need the same chown inside the WSL distribution.

7. Air-gap / offline mode#

Solo use checks for updates by default (the release endpoint now has a default, see Environment variables). To run fully air-gapped, set SIRIUS_AUTO_UPDATE=disabled and leave SIRIUS_LICENSE_KEY unset: no update check runs and no license phone-home runs. A docker run with that configuration makes no outbound calls beyond pulling the image itself.

• Local SQLite FTS5 Full-Text Search: Runs 100% in-process with SQLite FTS5 lexical indexing. Zero external network egress, zero API keys required.
• Web Portal Zero-Egress Invariant: All UI assets, textures, and fonts (Newsreader, Inter, JetBrains Mono) are packaged locally with immutable caching (NFR-SEC-03). Zero external font or CDN calls.
• Anti-DNS Rebinding Security: The embedded web server enforces strict Host/Origin header validation on loopback addresses (NFR-SEC-02), rejecting external rebinding with HTTP 403.

Enterprise deployments can go further:

• SIRIUS_LICENSE_OFFLINE=1 (requires a SIRIUS_LICENSE_KEY): validates against a local encrypted license file instead of phone-home. Without a key it is a no-op — solo mode already makes no license calls.
• SIRIUS_AUTO_UPDATE=disabled turns off update checks explicitly.

In air-gap mode, apply updates by pulling a newer image tag (see Versioning) or reinstalling the npm package; the in-process update check will not run.

8. Privacy guarantees#

Sirius does not send project names, document contents, file paths, or logs to any outbound endpoint. The only network requests it can make are:

• Auto-update check: GET to the release endpoint with query parameters limited to version and arch. In solo mode (SIRIUS_LICENSE_KEY unset), only version and arch are sent; with a license key, licenseKey is added. If the primary release endpoint is unreachable, the check falls back to https://registry.npmjs.org/@sirius-mcp/mcp/latest. With SIRIUS_AUTO_UPDATE=disabled, neither request runs.
• License validation (enterprise builds only): a lightweight check sending licenseKey, an anonymous instanceFingerprint (one-way hash of machine identity), and version. Solo mode performs no license validation and sends no license data.

Customer, subscription, and email data are never transmitted from the MCP runtime.

9. Versioning#

Published image: ghcr.io/sirius-mcp/sirius-mcp · Published npm package: @sirius-mcp/mcp (on npm since v1.4.0 — older tags are GHCR-only)

Prefer a semver tag in production or shared environments so pulls stay reproducible. Use latest for quick local trials. The npm path always resolves the latest published release (npx re-validates on every run — see Quick start).

Images are published on git tags matching v*.*.*; each publish also updates latest. The same tag publishes the npm package, so a release reaches both registries in one pipeline.

Updating: pull a newer tag and recreate the container:

docker pull ghcr.io/sirius-mcp/sirius-mcp:vX.Y.Z

Updates never touch the .context/ store. If you run from source as a contributor, see CONTRIBUTING.md for the bare-metal workflow, including the sidecar update script.

10. Embeddings (optional)#

Sirius supports local hybrid vector search combining semantic embeddings with lexical SQLite FTS5 through Reciprocal Rank Fusion (RRF). Semantic vector search runs entirely on your machine using ONNX Runtime with quantized Xenova/multilingual-e5-small embeddings (384 dimensions) — no remote API calls, no token fees, zero telemetry.

Setup

On the npm path, embedding libraries and models are opt-in to keep the default package lean. To enable vector search:

# If installed globally:
sirius-mcp setup embeddings

# Or via npx:
npx @sirius-mcp/mcp setup embeddings

The command installs @huggingface/[email protected] into the embeddings vendor directory (~/.sirius/embeddings), downloads the model weights at the pinned revision, and runs a functional smoke test.

To verify your runtime status:

sirius-mcp doctor

Disk footprint

The embedding runtime requires approximately ~430 MB of disk space:

• ~230 MB for the transformer runtime and ONNX execution libraries.
• ~195 MB for the quantized multilingual E5 model weights and tokenizer files.

Docker tier (batteries-included)

The official Docker image (ghcr.io/sirius-mcp/sirius-mcp:latest) comes with the embedding runtime and model weights pre-seeded at /home/node/.sirius/embeddings. Containers start in the ready state out-of-the-box without requiring any post-install download.

Air-gapped and enterprise pre-seed

In air-gapped environments without internet access:

1. Run sirius-mcp setup embeddings on an internet-connected machine.

2. Copy the resulting directory (default: ~/.sirius/embeddings) to the offline environment.

3. Configure the SIRIUS_EMBEDDINGS_DIR environment variable to point to the shared vendor directory:

   bash

   export SIRIUS_EMBEDDINGS_DIR=/opt/sirius/embeddings
   

   Important: Always specify an absolute path for SIRIUS_EMBEDDINGS_DIR in IDE and MCP client configuration files. Relative paths resolve against whichever working directory the host MCP client spawns the Node.js process from (often the user home directory or IDE install location, not the project root).

Custom mirror override

If your organization hosts HuggingFace model assets on an internal mirror or proxy, configure the base URL with:

export SIRIUS_EMBEDDINGS_MIRROR="https://hf-mirror.corp.internal"
sirius-mcp setup embeddings

Kill-switch

To disable vector search at runtime and force lexical-only FTS5 search:

export SIRIUS_VECTOR=0

Honest degradation

Vector search is strictly optional. If the embedding runtime is absent, incomplete, or uninstalled, Sirius automatically operates in lexical-only FTS5 mode. Search queries never fail or throw errors due to missing vector dependencies.

11. Troubleshooting#

• command not found: npx / 'npx' is not recognized: Node.js is missing — install Node ≥ 22 from https://nodejs.org, reopen your terminal, retry (see Quick start).
• Client startup hangs on a package prompt: use -y in the npx args (the config snippets above already include it).
• No response from MCP client (Docker): ensure -i is present and the client is attached to the container stdin/stdout.
• docker run --pull=always fails with failed to resolve reference during a registry outage: --pull=always is fail-closed (verified on Docker 29.7.2) — use the docker pull ... || true fallback documented in Docker.
• EACCES on .context/: uid 1000 inside the container cannot write the host volume. Run with --user "$(id -u):$(id -g)" or chown -R 1000:1000 "$PWD" (see Volume permissions).
• better-sqlite3 native errors (Docker): the image builds the native module for Alpine musl. If you rebuild the image on a different base, delete the host sirius-mcp/node_modules and rebuild. On the npm path, better-sqlite3 fetches a prebuilt binary automatically; a local compile only happens on platforms it does not prebuild for, which needs a C++ toolchain.

12. Changelog and Release Notes#

Versioned, dated publication history. If you are returning to this doc because your instance stopped being updated, this section tells you what you are missing and how far behind you are — no account, login or identification needed.

Public references (no login needed): npm versions — https://www.npmjs.com/package/@sirius-mcp/mcp?activeTab=versions · GHCR image — https://github.com/sirius-mcp/sirius-mcp/pkgs/container/sirius-mcp

Publication dates come from the git tags in the private sirius-mcp/sirius-mcp-core repository (the public github.com/sirius-mcp/sirius-mcp repo is a placeholder, without docs, releases or tags). Published versions: https://www.npmjs.com/package/@sirius-mcp/mcp?activeTab=versions · GHCR package: https://github.com/sirius-mcp/sirius-mcp/pkgs/container/sirius-mcp.

How to tell which version you are running

• Any client: the MCP initialize handshake reports the server version — your client logs it on connect (look for version: "X.Y.Z").
• Docker: the image tag in your config (docker run ... ghcr.io/sirius-mcp/sirius-mcp:<tag>); latest tracks the newest publish only when combined with --pull=always or an explicit docker pull.
• npm: npx @sirius-mcp/mcp always starts the latest published release — see Quick start.
• Newer instances (post-fix): the server logs update available: vX.Y.Z at boot/24h when a newer release exists, and the read-only resource context://system/update-status exposes the last check of the session (JSON). Instances running these newer builds reuse that existing cadence — no extra mechanism, nothing to configure.
• Older instances (pre-fix): no in-binary signal can reach them. This changelog section is the fallback: check your tag against the table above and pull the newest release.