Running Vectimus as a shared server

The Vectimus server provides HTTP endpoints for centralised policy evaluation. This is useful for small teams who want shared governance without setting up enterprise infrastructure.

The server is an optional component. The default pip 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.

Installation

pip 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 --policy-dir ./my-policies

Or run directly with uvicorn:

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

Authentication

Set the VECTIMUS_API_KEY environment variable on both the server and clients to enable API key authentication. When set, the server requires a valid X-Vectimus-API-Key header on /evaluate requests. The /health and /policies endpoints remain open for monitoring.

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

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

When VECTIMUS_API_KEY is not set, no authentication is required. The server is designed for trusted networks. Do not expose it to the public internet without additional network-level controls.

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 Dockerfile installs vectimus[server] and starts uvicorn on port 8420.

docker run -e VECTIMUS_API_KEY=secret \
           -e VECTIMUS_MCP_ALLOWED=github,slack \
           -p 8420:8420 vectimus

Connecting tools to the server

Run vectimus init --server-url https://vectimus.internal.example.com to configure your tools to send hook events to the server instead of evaluating locally.

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

[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 provides the core evaluation API. Vectimus Enterprise extends it with SSO, personas, a dashboard frontend, SIEM exporters and compliance reporting.