Skip to main content

​
Configuration Files

Vectra Guard uses YAML configuration files to control its behavior. You can configure protection levels, sandbox settings, policies, and more.

​
File Locations

Vectra Guard looks for configuration files in the following order (last one wins):
1

Global Config

~/.config/vectra-guard/config.yamlCreated by vg init - applies to all projects for the user
2

Project Config

./vectra-guard.yamlIn your project root - share protection policies with your team
3

Repo-Local Config

./.vectra-guard/config.yamlCreated by vg init --local - project-specific overrides
4

Explicit Path

Via --config flag
vectra-guard exec --config /path/to/config.yaml npm test
Commit vectra-guard.yaml to git to share security policies across your team!

​
Configuration Discovery

When you run a Vectra Guard command, it automatically discovers configuration files:
  1. Starts with built-in defaults
  2. Loads global config (~/.config/vectra-guard/config.yaml)
  3. Looks for project config (./vectra-guard.yaml)
  4. Applies repo-local overrides (./.vectra-guard/config.yaml)
  5. Applies environment variable overrides
# In your project root
cat vectra-guard.yaml

​
Basic Configuration Structure

A minimal configuration file contains these key sections:
vectra-guard.yaml
# Guard Level - Controls what requires approval
guard_level:
  level: auto  # auto, low, medium, high, paranoid
  allow_user_bypass: true

# Sandbox - Controls where commands run
sandbox:
  enabled: true
  mode: always  # always, auto, risky, never
  security_level: balanced  # permissive, balanced, strict, paranoid
  enable_cache: true

# CVE Awareness
cve:
  enabled: true
  sources: ["osv"]
  update_interval_hours: 24

# Logging
logging:
  format: json  # json or text

# Policies
policies:
  monitor_git_ops: true
  detect_prod_env: true
Everything is optional - Vectra Guard uses smart defaults if you don’t specify a value.

​
Using the Init Command

The vg init command helps you create configuration files quickly.

​
Create Global Config

vg init
This creates ~/.config/vectra-guard/config.yaml with recommended defaults.

​
Create Project Config

cd your-project
vg init --local
This creates ./.vectra-guard/config.yaml in your project directory.

​
Interactive Setup

vg init --interactive
Answers questions to customize your configuration:
  • What’s your use case? (development/CI/production)
  • Do you want aggressive sandboxing?
  • Should CVE scanning be enabled?
  • What logging format do you prefer?

​
View Current Config

vg init --show-config
Displays the currently active configuration (after all merging and overrides).

​
Configuration Layers

Vectra Guard uses a layered approach, where each layer can override the previous one:
Vectra Guard ships with sensible defaults:
  • guard_level: auto
  • sandbox.mode: always
  • sandbox.security_level: balanced
  • sandbox.enable_cache: true
  • CVE scanning enabled
~/.config/vectra-guard/config.yamlYour personal preferences that apply to all projects.
./vectra-guard.yamlTeam-wide policies committed to version control.
./.vectra-guard/config.yamlProject-specific overrides (not usually committed to git).
VECTRA_GUARD_LEVEL=paranoid vg exec "deploy script"
Runtime overrides for specific situations.

​
Environment Variable Overrides

Override any configuration at runtime: 
# Temporarily lower protection
VECTRA_GUARD_LEVEL=low vg exec "risky command"

# Force paranoid mode
VECTRA_GUARD_LEVEL=paranoid vg exec "production deploy"

​
Best Practices

Use Auto-Detection

Set guard_level: auto and let Vectra Guard intelligently adjust protection based on context.

Commit Project Config

Share security policies with your team by committing vectra-guard.yaml to version control.

Layer Your Protection

Use global config for personal preferences, project config for team policies, and env vars for situational overrides.

Test Your Config

Use vg validate script.sh to test how your configuration handles commands.

​
Validating Configuration

Test your configuration before deploying: 
# Validate config file syntax
vg validate vectra-guard.yaml

# Test how a command would be handled
vg explain "npm install dangerous-package"

# Dry run
vg exec --dry-run "risky command"

​
Next Steps

Presets

Use pre-configured settings for common scenarios

Sandbox Config

Configure sandboxing modes and security levels

Guard Levels

Understand auto-detection and protection levels

API Reference

Complete configuration schema reference

Build docs developers (and LLMs) love

Get started for freeTalk to us