Running Vectimus as a shared server

The Vectimus server provides HTTP endpoints for centralised policy evaluation. Teams run it to enforce consistent governance across every developer and CI runner from a single point of control.

The server is an optional component. The default pipx install vectimus gives you local-only evaluation via command hooks. The server extends this with a shared /evaluate endpoint that multiple developers can point their hooks at. The open-source server covers authentication, TLS, multi-worker deployments and Docker. Everything you need to run centralised evaluation. For organisations that need SSO, role-based personas, a management dashboard, SIEM integration and compliance reporting, Vectimus Enterprise is coming soon.

Installation

pipx install vectimus[server]

This installs FastAPI and uvicorn alongside the core Vectimus package.

Starting the server

vectimus server start

Options:

vectimus server start --host 0.0.0.0 --port 8420
vectimus server start --workers 4
vectimus server start --policy-dir ./my-policies
vectimus server start --ssl-certfile cert.pem --ssl-keyfile key.pem

Or run directly with uvicorn:

uvicorn vectimus.server.app:create_app --factory --host 0.0.0.0 --port 8420

Authentication

Single key

Set VECTIMUS_API_KEY on both the server and clients. When set, the server requires a valid X-Vectimus-API-Key header on /evaluate requests. Probe endpoints (/health, /healthz, /ready) remain open for monitoring.

# Server
export VECTIMUS_API_KEY="your-secret-key"
vectimus server start

# Client (hooks read the same env var)
export VECTIMUS_API_KEY="your-secret-key"
export VECTIMUS_SERVER_URL="https://vectimus.internal.example.com"

Named API keys (teams)

For teams, use named API keys to attribute audit events to specific tools or people. Each key gets a name that appears in structured logs and audit records.

Via environment variable:

export VECTIMUS_API_KEYS="ci-runner:key-abc123,alice:key-def456,bob:key-ghi789"
vectimus server start

Via vectimus.toml:

[[server.api_keys]]
name = "ci-runner"
key = "key-abc123"

[[server.api_keys]]
name = "alice"
key = "key-def456"

Both sources merge. The legacy VECTIMUS_API_KEY still works and gets the name default.

When no keys are configured, the server runs without authentication. Do not expose it to the public internet without additional network-level controls.

TLS

The server supports TLS termination directly via uvicorn. Pass certificate and key files through the CLI or environment variables.

vectimus server start --ssl-certfile /path/to/cert.pem --ssl-keyfile /path/to/key.pem

Or via environment:

export VECTIMUS_SSL_CERTFILE=/path/to/cert.pem
export VECTIMUS_SSL_KEYFILE=/path/to/key.pem
vectimus server start

For production deployments behind a load balancer or reverse proxy, terminate TLS there instead and run Vectimus on plain HTTP internally.

Workers

For higher throughput under concurrent load, run multiple worker processes:

vectimus server start --workers 4

Or via environment:

export VECTIMUS_WORKERS=4

Each worker is an independent process. Cedar evaluation is CPU-bound, so more workers help with concurrent requests. A good starting point is 2-4 workers.

CORS

If your monitoring dashboard runs on a different origin, configure CORS:

export VECTIMUS_CORS_ORIGINS="https://dashboard.example.com,https://admin.example.com"

Or in vectimus.toml:

[server]
cors_origins = ["https://dashboard.example.com"]

Observe mode

The server supports observe mode via the --observe flag or the VECTIMUS_OBSERVE environment variable. In observe mode the server logs all decisions but always returns allow.

vectimus server start --observe
# or
VECTIMUS_OBSERVE=true vectimus server start

Docker

docker compose up -d

The included docker-compose.yml provides a ready-to-use template. The container runs as an unprivileged user on port 8420.

docker run -e VECTIMUS_API_KEYS=ci:key1,dev:key2 \
           -p 8420:8420 vectimus

TLS in Docker

Mount your certificate files into the container:

services:
  vectimus:
    build: .
    ports:
      - "8420:8420"
    environment:
      - VECTIMUS_SSL_CERTFILE=/certs/cert.pem
      - VECTIMUS_SSL_KEYFILE=/certs/key.pem
      - VECTIMUS_API_KEYS=team1:key1,team2:key2
    volumes:
      - ./certs:/certs:ro

Custom policies

Mount a directory of .cedar policy files:

docker run -p 8420:8420 \
           -e VECTIMUS_POLICY_DIR=/policies \
           -v ./policies:/policies:ro \
           vectimus

Connecting tools to the server

Run vectimus init --server-url https://vectimus.internal.example.com to save the server URL to ~/.vectimus/config.toml. All hooks will use the server for evaluation with automatic fallback to local evaluation if the server is unreachable.

You can also set the server URL via environment variable, which takes precedence over the config file:

export VECTIMUS_SERVER_URL="https://vectimus.internal.example.com"

Endpoints

The /evaluate endpoint accepts an X-Vectimus-Source header to identify the source tool (claude-code, cursor or copilot).

Configuration

The server reads configuration from multiple sources. Higher-numbered sources override lower ones:

1. Built-in defaults
2. ~/.vectimus/config.toml (user-level)
3. ./vectimus.toml (project-level)
4. Environment variables (highest precedence)

[server]
host = "0.0.0.0"
port = 8420
workers = 2
cors_origins = ["https://dashboard.example.com"]

[[server.api_keys]]
name = "ci-runner"
key = "your-key-here"

[policies]
dir = "./policies"

[mcp]
allowed_servers = ["github", "slack"]

[logging]
dir = "~/.vectimus/logs"

Server environment variables

Client environment variables

Set these on the developer’s machine when connecting to a remote server.

Enterprise

The open-source server gives you the full evaluation API, authentication, TLS, multi-worker scaling and Docker deployment. It is production-ready for teams that manage policies via config files and environment variables.

Vectimus Enterprise (coming soon) builds on the same core and adds capabilities for larger organisations:

• SSO and identity federation: connect to your existing IdP
• Role-based personas: map team roles to Cedar policy contexts
• Management dashboard: visibility into evaluations, policy status and audit trails
• SIEM exporters: stream audit events to Splunk, Datadog, Sentinel and others
• Compliance reporting: generate evidence packs for SOC 2, NIST AI RMF and EU AI Act audits

Join the Enterprise waitlist to get early access.