Getting started

Installation

pipx install vectimus

Or with uv:

uv tool install vectimus

For framework integrations, install with extras:

pip install vectimus[server]     # FastAPI server mode
pip install vectimus[adk]        # Google ADK integration
pip install vectimus[langgraph]  # LangGraph middleware
pip install vectimus[all]        # Everything

Initialise

Run vectimus init in your project directory. It detects which AI tools you have installed and generates the appropriate hook configurations.

vectimus init

That’s it. 79 policies are active immediately across 11 domain packs. Your agents are now governed. Dangerous commands, secret access, infrastructure changes and supply chain attacks are blocked before execution.

Vectimus works with Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex CLI, Google ADK, LangGraph and the Claude Agent SDK. If you already have hooks configured, vectimus init merges its hooks with your existing ones. Your custom hooks are preserved.

Uninstall from a project

To remove Vectimus hooks from all detected tools in the current project:

vectimus remove

This strips Vectimus entries from Claude Code, Cursor, Copilot, Gemini CLI and Codex CLI config files while preserving any non-Vectimus hooks you have. It does not touch your ~/.vectimus/ config or audit logs.

Use --force to skip the confirmation prompt:

vectimus remove --force

To reinstall later, run vectimus init again.

Observe mode (optional)

If you want to trial Vectimus without blocking anything, observe mode logs all decisions to the audit trail but always allows actions.

vectimus observe on

Review the audit log at ~/.vectimus/logs/ to understand which actions your policies would block. When you’re satisfied, switch to enforcement:

vectimus observe off

You can check the current mode at any time:

vectimus observe status

For CI/CD pipelines, set the environment variable instead:

export VECTIMUS_OBSERVE=true

Policy updates

Vectimus ships with bundled policies. You can also sync updated policies from api.vectimus.com manually or on a schedule.

To sync manually:

vectimus policy update

To enable automatic background sync (disabled by default), add this to ~/.vectimus/config.toml:

[updates]
auto_sync = true                              # enable background sync
sync_url = "https://api.vectimus.com"         # optional, this is the default
sync_interval_hours = 24                      # optional, this is the default

Or set VECTIMUS_AUTO_SYNC=true as an environment variable.

Check current policy version and sync status:

vectimus policy status

Updated policies are cached at ~/.vectimus/policy-cache/ and override the bundled versions when a newer pack is available. If the sync fails (no network, API down), Vectimus falls back to the bundled policies shipped with the installed package. Governance is never interrupted.

Test your policies (optional)

To see what your loaded policies would do against a set of sample events:

vectimus test

This prints a summary table of allow/deny decisions. Useful for verifying custom rules or checking what happens after disabling rules.

MCP server allowlist

Vectimus blocks all MCP tool calls by default (rule vectimus-mcp-001). This prevents agents from communicating with unapproved MCP servers.

Auto-discovery during init

vectimus init reads MCP server names from your existing tool configs and prompts you to approve them:

MCP servers detected:
  Claude Code:  posthog, slack
  Cursor:       github

Allow all 3 servers? [y/N]: n
  Allow github? [Y/n]: y
  Allow posthog? [Y/n]: y
  Allow slack? [Y/n]: n

Approved 2 MCP server(s): github, posthog

If you decline the bulk prompt, each server is offered individually (default yes). To skip prompts entirely and approve all discovered servers:

vectimus init --allow-mcp

CI/CD pipelines

Use the --ci flag to run init non-interactively. All prompts are suppressed. MCP servers are discovered but not allowed unless you also pass --allow-mcp.

# Non-interactive init — discovers MCP servers but does not allow them
vectimus init --ci

# Non-interactive init — auto-allow all discovered MCP servers
vectimus init --ci --allow-mcp

It reads from these config files:

Manual management

You can manage the allowlist at any time:

# Approve servers one at a time
vectimus mcp allow github
vectimus mcp allow slack

# View the current allowlist
vectimus mcp list

# Remove a server from the list
vectimus mcp deny evil-server

For CI/CD or container deployments, use the environment variable:

export VECTIMUS_MCP_ALLOWED="github,slack,jira"

The environment variable merges with the config file list.

How it works: Vectimus intercepts the agent’s request to call an MCP tool before it is sent. It sees the server name, tool name and input parameters. It does not observe what happens on the MCP server. Server allowlisting blocks the request entirely if the server is not approved. Input inspection rules add defence in depth by checking tool parameters for credential paths, CI/CD files and dangerous commands.

Project-local configuration

Vectimus supports a .vectimus/config.toml file in your project root, following the .claude/ and .cursor/ convention. This file is version-controllable and discoverable by your team.

[identity]
persona = "default"
groups = ["engineering", "platform"]
identity_type = "human"

[limits]
content_inspection_max_lines = 5000
excessive_turns_threshold = 50

[audit]
max_file_size_mb = 100
log_dir = "~/.vectimus"

[rules]
disabled = []

Resolution order: Environment variables take highest precedence, then project .vectimus/config.toml, then global ~/.vectimus/config.toml, then hardcoded defaults.

The .vectimus/ directory is protected by policy vectimus-fileint-005. Agents cannot modify it. Changes must be made by a human via the CLI or editor.

Rule management

Vectimus ships with built-in policy packs. You can manage individual rules via the CLI:

# List all rules and their status
vectimus rule list

# Show full details for a rule
vectimus rule show vectimus-infra-001

Per-project rule overrides

You can disable specific rules for a specific project without affecting your global policy. This is useful when a project legitimately needs operations that a rule would otherwise block.

# Disable a rule for the current project only
vectimus rule disable vectimus-infra-004

# Disable a rule everywhere
vectimus rule disable vectimus-infra-004 --global

# View project-specific overrides
vectimus rule overrides

# Re-enable a rule for the current project
vectimus rule enable vectimus-infra-004

# Re-enable a rule everywhere
vectimus rule enable vectimus-infra-004 --global

Per-project overrides are stored in .vectimus/config.toml in the project root. Legacy overrides at ~/.vectimus/projects/ are still read as a fallback.

Precedence model: A rule is disabled if it appears in either the global disabled list or the project disabled list. Project overrides can only relax (disable) rules. They cannot re-enable a globally disabled rule.

Pack management

Policies are organized into 11 domain-based packs:

Packs can be enabled or disabled together:

# List all policy packs
vectimus pack list

# Disable a pack
vectimus pack disable data-exfiltration

# Enable a pack
vectimus pack enable data-exfiltration

Pack enable/disable is always global. Per-project overrides apply to individual rules only.

System status

Check the current state of your Vectimus installation:

vectimus status

This shows configured tools, loaded policies, audit statistics and current mode.

Write custom policies

See Writing policies for the full guide. Place .cedar files in your policy directory and Vectimus will load them automatically.

Environment variables