Getting started

Installation

pip install vectimus

Or with uv:

uv pip install vectimus

Initialise

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

vectimus init

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

If you already have hooks configured for Claude Code, Cursor or Copilot, 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 and Copilot 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

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-base-030). 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

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.

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-base-007

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-base-010

# Disable a rule everywhere
vectimus rule disable vectimus-base-010 --global

# View project-specific overrides
vectimus rule overrides

# Re-enable a rule for the current project
vectimus rule enable vectimus-base-010

# Re-enable a rule everywhere
vectimus rule enable vectimus-base-010 --global

Per-project overrides are stored in ~/.vectimus/projects/, not inside the repository. This prevents malicious PRs from disabling governance rules for anyone who clones the repo.

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

Packs are groups of related rules that can be enabled or disabled together:

# List all policy packs
vectimus pack list

# Disable a pack
vectimus pack disable owasp-agentic

# Enable a pack
vectimus pack enable owasp-agentic

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