AI Agent Integration

Configure Cursor, Copilot, OpenClaw, and other AI coding assistants to use Vectra Guard

Overview

AI coding assistants like Cursor, GitHub Copilot, OpenClaw, and others can execute commands that might be risky. Vectra Guard protects you by automatically sandboxing and validating commands suggested by AI agents.

Supported Agents

  • OpenClaw — Local AI assistant with full system access
  • Cursor — AI-powered code editor
  • Claude Code — Anthropic's CLI coding agent
  • GitHub Copilot — AI pair programmer
  • VS Code — AI agents in Visual Studio Code
  • Windsurf — AI-assisted editor
  • Codex — OpenAI Codex agent
  • Generic Agents — Any AI agent via AGENTS.md

Seed Targets

Each agent maps to a seed target and destination file:

agents → AGENTS.md
claude → CLAUDE.md
codex → CODEX.md
copilot → .github/copilot-instructions.md
cursor → .cursor/rules/vectra-guard.md
openclaw → ~/.openclaw/AGENTS.md (auto-detected)
vscode → .vscode/vectra-guard.instructions.md
windsurf → .windsurf/rules.md

Quick Start

Seed agent instructions in your project with a single command:

Seed Agent Instructions
# Seed instructions for specific agents
vg seed agents --target . --targets "cursor,copilot"

# Seed OpenClaw — auto-detects ~/.openclaw and merges safely
vg seed agents --targets openclaw

# Non-interactive mode (CI/scripts) — auto-confirms detected path
vg seed agents --targets openclaw --yes

# Seed everything at once
vg seed agents --target . --targets "agents,claude,cursor,copilot,openclaw"

# List all available targets with their destination files
vg seed agents --list
Tip: The seed command shows rich context — repository name, branch, project type, agent coverage matrix, and VectraGuard protection status. For OpenClaw, it also auto-detects the install location and merges without overwriting your custom instructions.

OpenClaw Integration

OpenClaw is a local AI assistant with full system access — browser automation, shell commands, and file operations. VectraGuard automatically detects where OpenClaw is installed, confirms the destination with you, and merges its security section into your existing AGENTS.md without overwriting your custom instructions.

Smart Detection

VectraGuard checks for the OpenClaw state directory in this order (first match wins):

OPENCLAW_STATE_DIR environment variable
CLAWDBOT_STATE_DIR legacy environment variable
~/.openclaw/ default path
~/.clawdbot/ ~/.moldbot/ ~/.moltbot/ legacy fallbacks
Seed OpenClaw Instructions
# Interactive — auto-detects and asks you to confirm
vg seed agents --targets openclaw

#   OpenClaw detected (default)
#   State directory: /Users/you/.openclaw
#
#   Destination: /Users/you/.openclaw/AGENTS.md
#   Confirm? [Y/n/custom path]: y

# Non-interactive / CI — auto-confirms detected path
vg seed agents --targets openclaw --yes

# Override with env var
OPENCLAW_STATE_DIR=/custom/path vg seed agents --targets openclaw --yes

Marker-Based Merge

VectraGuard wraps its content in <!-- vectraguard:begin --> / <!-- vectraguard:end --> markers. Your custom instructions outside the markers are never touched.

[+] written — No file existed, created with markers
[~] merged — File existed without markers, appended VectraGuard section
[~] updated — Markers found, replaced only VectraGuard section

Generated Instructions Preview

Code
# Your existing custom instructions stay untouched above

<!-- vectraguard:begin -->
# VectraGuard Security Instructions for OpenClaw

## Safe Execution
- Run shell commands via `vg exec -- <command>`
- Destructive commands are blocked by design

## CVE Scanning (Before Installing Dependencies)
- Always scan: `vg cve scan --path .`

## Soft Delete (Safe File Deletion)
- Files deleted via `rm` are automatically backed up
- Restore with: `vg restore <backup-id>`

## Secret Detection
- Scan for exposed secrets: `vg scan-secrets --path .`

## Session Tracking
- Track agent activity: `vg session start --agent "openclaw"`
<!-- vectraguard:end -->
Note: Re-running vg seed agents --targets openclaw is idempotent — it replaces only the marked VectraGuard section. Your custom instructions are always preserved.

Cursor Integration

Cursor reads instructions from .cursor/rules/vectra-guard.md file. Vectra Guard automatically generates this file with security-focused rules.

Setup Cursor
# Generate .cursor/rules/vectra-guard.md
vg seed agents --target . --targets cursor

# The generated file includes:
# - Instructions to use Vectra Guard for all commands
# - Security best practices
# - Command validation rules

Example .cursor/rules/vectra-guard.md Content

Code
# Vectra Guard Security Rules for Cursor

## Command Execution
- Always use Vectra Guard (vg) to execute commands
- Use `vg exec` instead of direct command execution
- Use `vg validate` before running scripts
- Use `vg cve scan` before installing dependencies

## Security Guidelines
- Never execute commands that modify system files without approval
- Always scan for CVEs before installing packages
- Use sandbox mode for untrusted commands
- Validate scripts before execution

## Example Usage
```bash
# Instead of: npm install
vg exec -- npm install

# Instead of: ./deploy.sh
vg validate scripts/deploy.sh && vg exec -- ./deploy.sh
```

GitHub Copilot Integration

Copilot reads instructions from .github/copilot-instructions.md. Configure it to use Vectra Guard for safer command suggestions.

Setup Copilot
# Generate Copilot instructions
vg seed agents --target . --targets copilot

# Creates .github/copilot-instructions.md

Copilot Instructions Example

Code
# Vectra Guard Security Instructions

When suggesting commands:
1. Always prefix with `vg exec --` for execution
2. Use `vg validate` for script validation
3. Use `vg cve scan` before package installation
4. Prefer sandboxed execution for untrusted code

Example:
- Bad: `npm install express`
- Good: `vg exec -- npm install express`
- Better: `vg cve scan --path . && vg exec -- npm install express`

Generic Agent Integration

For any AI agent that can read markdown files, use AGENTS.md. This file contains universal instructions for AI agents.

Setup Generic Agents
# Generate generic agent instructions
vg seed agents --target . --targets agents

# Creates AGENTS.md

Agent Instructions Template

Code
# Vectra Guard - AI Agent Instructions

## Overview
This project uses Vectra Guard for secure command execution. All commands should be executed through Vectra Guard.

## Command Execution Rules

### 1. Always Use Vectra Guard
- Use `vg exec -- <command>` instead of direct execution
- Example: `vg exec -- npm install` not `npm install`

### 2. Validate Scripts
- Use `vg validate <script>` before executing scripts
- Example: `vg validate scripts/deploy.sh`

### 3. Scan for CVEs
- Run `vg cve scan --path .` before installing dependencies
- Check for high/critical severity vulnerabilities

### 4. Use Sessions
- Start a session: `SESSION=$(vg session start --agent "ai-agent")`
- Export: `export VECTRAGUARD_SESSION_ID=$SESSION`

## Security Best Practices
- Never execute destructive commands without validation
- Always scan dependencies for vulnerabilities
- Use sandbox mode for untrusted code
- Review command output before proceeding

Configuration

Customize agent instructions by editing the generated files or configuring Vectra Guard:

Agent Configuration
# Configuration for agent integration
agents:
  enabled: true
  auto_seed: true  # Auto-generate on vg init

  # Instruction templates
  templates:
    cursor: .cursor/rules/vectra-guard.md
    copilot: .github/copilot-instructions.md
    openclaw: .openclaw/AGENTS.md
    generic: AGENTS.md

  # Security level for agent commands
  security_level: 2  # 1-4, default is 2

  # Auto-sandbox agent commands
  auto_sandbox: true

Workflow Integration

Integrate Vectra Guard into your AI-assisted development workflow:

1. Project Setup

Code
# Initialize Vectra Guard
vg init --local

# Seed agent instructions (openclaw auto-detects ~/.openclaw)
vg seed agents --target . --targets "agents,claude,cursor,copilot,openclaw" --yes

2. Start Development Session

Code
# Start a tracked session
SESSION=$(vg session start --agent "cursor")
export VECTRAGUARD_SESSION_ID=$SESSION

# Now Cursor will use Vectra Guard automatically

3. AI Agent Workflow

  1. AI agent suggests a command
  2. Command is automatically routed through Vectra Guard
  3. Vectra Guard validates and sandboxes if needed
  4. Command executes safely
  5. Results are logged to session

4. Monitor with Dashboard

Code
# Start the security dashboard
vg serve --port 8000

# View sessions, metrics, CVE results in real time
# Open http://127.0.0.1:8000

# Review session activity
vg session show $SESSION

Best Practices

1. Always Seed Instructions

Run vg seed agents in every project to ensure AI agents know about Vectra Guard.

2. Use Sessions

Start a session when working with AI agents. This provides a complete audit trail of all commands.

3. Review Before Execution

Even with Vectra Guard, review commands suggested by AI agents before executing them.

4. Enable Auto-Sandbox

Configure agents.auto_sandbox: true to automatically sandbox all AI-suggested commands.

5. Regular CVE Scans

When AI agents suggest installing packages, always run CVE scans first to check for vulnerabilities.

6. Monitor with the Dashboard

Run vg serve to open the local security dashboard for real-time visibility into agent sessions, sandbox metrics, and CVE results.

Troubleshooting

Agent Not Using Vectra Guard

If your AI agent isn't following Vectra Guard instructions:

  • Verify the instruction file exists (e.g., .cursor/rules/vectra-guard.md)
  • Check that the agent supports reading instruction files
  • Try regenerating instructions: vg seed agents --target . --force
  • Restart your editor/agent after seeding

OpenClaw Instructions Not Detected

If OpenClaw isn't picking up VectraGuard rules:

  • Verify the instruction file exists: ~/.openclaw/AGENTS.md (or wherever VectraGuard detected your install)
  • Check that vectra-guard binary is on your PATH
  • Re-seed with the --yes flag to auto-confirm: vg seed agents --targets openclaw --yes
  • Override detection with an env var: OPENCLAW_STATE_DIR=/path/to/.openclaw vg seed agents --targets openclaw --yes
  • Check the markers exist in the file: <!-- vectraguard:begin --> and <!-- vectraguard:end -->

Commands Still Running on Host

If commands aren't being sandboxed:

  • Check sandbox configuration: sandbox.enabled: true
  • Enable auto-sandbox for agents: agents.auto_sandbox: true