Configuration reference

Vectimus uses a layered configuration system. Every setting can be controlled via TOML config files or environment variables.

Resolution order

Settings are resolved in this order (first match wins):

Environment variables — highest precedence, useful for CI/CD
Project-local config — .vectimus/config.toml in the project root
Global config — ~/.vectimus/config.toml
Hardcoded defaults — sensible out-of-the-box values

Config file locations

Project-local: `.vectimus/config.toml`

Lives in your project root alongside .claude/ and .cursor/. Version-controllable and shared with your team. Protected by Cedar policy vectimus-fileint-005 — agents cannot modify this directory.

Global: `~/.vectimus/config.toml`

User-wide defaults. Created automatically by vectimus init.

Policy cache: `~/.vectimus/policy-cache/`

Policies synced from api.vectimus.com via vectimus policy update or background auto-sync are stored here. Cached packs override bundled packs with matching names. If the cache is empty or corrupted, Vectimus falls back to bundled policies.

Full TOML schema

[identity]
persona = "default"              # Identity persona for Cedar policies
groups = ["engineering"]         # Group memberships (available in Cedar as a Set)
identity_type = "human"          # "human" or "agent"

[limits]
content_inspection_max_lines = 5000   # Max lines inspected in file content/scripts
excessive_turns_threshold = 50        # Agent turns before EXCESSIVE_TURNS flag
session_spawn_limit = 10              # Max agent spawns per session (server mode)
session_message_limit = 50            # Max messages per session (server mode)
session_ttl_seconds = 3600            # Session expiry in seconds (server mode)
git_timeout_seconds = 5               # Timeout for git identity/repo lookups

[audit]
max_file_size_mb = 100     # Max audit log file size before rotation
log_dir = "~/.vectimus"    # Directory for audit JSONL files

[rules]
disabled = []              # Rule IDs to disable for this project/globally

[rules.enforcement]
# Per-rule enforcement level overrides (deny, escalate, observe)
# "custom-001" = "escalate"
# "custom-002" = "observe"

[packs]
# Pack-level enable/disable
# [packs.exfiltration]
# enabled = false

[mcp]
allowed_servers = []       # Approved MCP server names

[mode]
observe = false            # Log decisions but always allow

[receipts]
enabled = true             # Generate signed governance receipts
retention_days = 7         # Days to keep receipt files before cleanup

[updates]
auto_sync = false          # Background policy sync (opt-in)
sync_url = "https://api.vectimus.com"   # Policy API endpoint
sync_interval_hours = 24   # Hours between background checks

Environment variable reference

All environment variables override config file values.

Identity

Variable	Purpose	Default
`VECTIMUS_PERSONA`	Identity persona	`default`
`VECTIMUS_GROUPS`	Comma-separated group list	Empty
`VECTIMUS_IDENTITY_TYPE`	`human` or `agent`	`human`

Limits

Variable	Purpose	Default
`VECTIMUS_CONTENT_MAX_LINES`	Content inspection line limit	5000
`VECTIMUS_EXCESSIVE_TURNS`	Excessive turns threshold	50
`VECTIMUS_GIT_TIMEOUT`	Git command timeout (seconds)	5
`VECTIMUS_SESSION_SPAWN_LIMIT`	Max spawns per session	10
`VECTIMUS_SESSION_MESSAGE_LIMIT`	Max messages per session	50
`VECTIMUS_SESSION_TTL`	Session TTL (seconds)	3600

Audit

Variable	Purpose	Default
`VECTIMUS_AUDIT_MAX_MB`	Max log file size (MB)	100
`VECTIMUS_LOG_DIR`	Audit log directory	`~/.vectimus`

Policy sync

Variable	Purpose	Default
`VECTIMUS_AUTO_SYNC`	Enable background policy sync (`true`/`1`)	Off
`VECTIMUS_SYNC_URL`	Policy API endpoint	`https://api.vectimus.com`
`VECTIMUS_SYNC_INTERVAL`	Sync check interval (hours)	24

Daemon

Variable	Purpose	Default
`VECTIMUS_NO_DAEMON`	Disable daemon, use inline evaluation (`true`/`1`)	Off

Receipts

Variable	Purpose	Default
`VECTIMUS_RECEIPTS_ENABLED`	Enable signed governance receipts (`true`/`false`)	`true`

General

Variable	Purpose	Default
`VECTIMUS_OBSERVE`	Observe mode (`true`/`1`)	Off
`VECTIMUS_MCP_ALLOWED`	Comma-separated MCP servers	All blocked
`VECTIMUS_SERVER_URL`	Forward to shared server	Local evaluation
`VECTIMUS_API_KEY`	Server auth key	None
`VECTIMUS_TIMEOUT`	Server request timeout (seconds)	5

Example configurations

Solo developer

Minimal config. Most defaults work well for individual use.

[rules]
disabled = []

Team with groups

Share governance config across a team. Groups can be referenced in custom Cedar policies.

[identity]
persona = "platform-team"
groups = ["engineering", "platform", "infra"]

[limits]
content_inspection_max_lines = 10000
excessive_turns_threshold = 100

CI/CD agent

Stricter limits for automated pipelines. Use environment variables for secrets.

[identity]
identity_type = "agent"
persona = "ci-runner"

[limits]
content_inspection_max_lines = 2000
excessive_turns_threshold = 20

[audit]
log_dir = "/var/log/vectimus"

Set VECTIMUS_GROUPS=ci,deploy and VECTIMUS_API_KEY via your CI environment.