Skip to main content

Configuration Reference

Complete reference for overwatch.yaml configuration.

File Locations

Overwatch searches for config in this order:
  1. Path specified with --config
  2. overwatch.yaml in current directory
  3. overwatch.yml in current directory
  4. .overwatch.yaml in current directory
  5. .overwatch.yml in current directory
  6. ~/.overwatch/config.yaml

Complete Schema

# Config version (required)
version: 1

# Default settings for all servers
defaults:
  action: prompt          # Default action: allow, deny, prompt
  timeout: 60000          # Approval timeout in ms
  sessionDuration: 300000 # Default session grant in ms

# MCP server configurations
servers:
  server-name:
    command: string       # Command to run (required)
    args: [string]        # Command arguments
    env:                  # Environment variables
      KEY: value
    policies:             # Policy rules
      - tools: [string]   # Tool names or patterns
        action: string    # Action: allow, deny, prompt
        paths:            # Path-based rules (filesystem)
          allow: [string]
          deny: [string]

# Tool shadowing detection
toolShadowing:
  enabled: boolean        # Enable detection (default: true)
  checkDescriptions: boolean # Check for injection in descriptions
  detectMutations: boolean   # Detect mid-session changes

# Audit logging settings
audit:
  enabled: boolean        # Enable audit logging
  redactPII: boolean      # Redact sensitive data

Examples

Minimal Configuration

version: 1

servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]

Full Development Setup

version: 1

defaults:
  action: prompt
  timeout: 60000

servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      DATABASE_URL: postgres://localhost/dev
    policies:
      - tools: ["query", "select"]
        action: allow
      - tools: ["insert", "update"]
        action: prompt
      - tools: ["drop_*", "delete_*"]
        action: deny

  filesystem:
    command: npx
    args: ["-y", "@anthropic/mcp-server-filesystem", "./"]
    policies:
      - tools: ["read_file", "list_directory"]
        action: allow
      - tools: ["write_file"]
        action: prompt
        paths:
          allow:
            - ./src/**
            - ./test/**
          deny:
            - /.*
            - ~/.ssh/**
            - **/.env*
      - tools: ["delete_file"]
        action: deny

toolShadowing:
  enabled: true
  checkDescriptions: true
  detectMutations: true

audit:
  enabled: true
  redactPII: true

Production Setup

version: 1

defaults:
  action: deny  # Deny by default in production
  timeout: 30000

servers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    policies:
      - tools: ["query", "select"]
        action: allow
      - tools: ["*"]
        action: deny

toolShadowing:
  enabled: true
  checkDescriptions: true
  detectMutations: true

audit:
  enabled: true
  redactPII: true

Environment Variables

Use ${VAR_NAME} syntax to reference environment variables:
servers:
  postgres:
    env:
      DATABASE_URL: ${DATABASE_URL}

Policy Actions

ActionBehavior
allowAlways allow without prompt
denyAlways deny
promptAsk user for approval

Tool Patterns

PatternMatches
queryOnly query
read_*read_file, read_directory, etc.
*All tools

Path Patterns

For filesystem operations:
PatternMatches
./src/**All files under src/
**/.env*All .env files anywhere
~/.ssh/**All SSH key files
/.*Hidden files in root
deny patterns take precedence over allow patterns.

Validation

Validate your configuration:
overwatch policies validate
Or check overall installation:
overwatch doctor
This checks:
  • YAML syntax
  • Required fields
  • Server command availability
  • Valid action values