Configuration

Overview

Guardian configuration is focused on one goal: control AI-generated code before it ships. This guide covers policy, gate, and runtime settings.

Policy Source of Truth

Guardian uses a version-controlled policy file in your repository root:

guardian.policy.yaml

Minimum gate fields:

• schema_version
• packs[]
• gate.pass_max_warnings
• gate.block_on_critical
• gate.require_human_approval_on_ai_heavy
• gate.require_override_reason

Use this file as the single source of truth for desktop, CLI, and CI release decisions.

Accessing Settings

Click the gear icon (⚙️) in the header to open the Settings modal.

Provider Configuration

Selecting a Provider

Choose your AI provider from the dropdown:

Model Selection

After selecting a provider, choose a model. Available models are fetched automatically from the provider.

Choosing a model:

• Prefer a faster model for day-to-day monitoring and quick Guru questions.
• Use a deeper model when you need higher-quality architectural analysis.
• For Ollama, pick a model you already pulled locally (for example: ollama pull <model>).

API Key Management

For providers requiring API keys:

1. Obtain your API key from the provider dashboard
2. Enter the key in the "API Key" field
3. Click Save to store securely
4. Click Clear to remove stored key

Security: API keys are stored in platform-native secure storage (Keychain, Credential Manager, or Secret Service).

Theme Settings

Toggle between Light and Dark themes:

• Click the theme toggle in the Settings modal
• Or use the theme toggle in the header

Scan Scope

Scan Scope controls which files Guardian includes during monitoring (cost vs coverage).

Open Settings > General > Scan Scope and choose:

Changes apply the next time monitoring starts (restart monitoring to apply).

Web Search (Tavily)

Enable AI-powered web search for Guru:

1. Get an API key from tavily.com
2. Enter the key in the "Tavily API Key" field
3. Guru can now search the web for context

Search Depth

In Settings > Web Search, you can control how deep the search should go:

• Auto: Picks a sensible depth based on the query.
• Basic: Good default for most questions.
• Advanced: Higher recall (slower, more expensive).
• Fast / Ultra-fast: Faster, smaller result sets.

URL Extract

If your question includes a URL, Guru will prefer URL extraction to pull the most relevant chunks from that page (instead of doing a broad search first).

Per-Message Overrides

You can force web search for a single question by adding:

• /web prefix (for example: /web explain the latest Node.js LTS changes)
• @web tag anywhere in the question

This works even if Web Search is off, but it still requires a Tavily key.

Best Practices

1. Keep web queries short and specific (Guardian truncates Tavily queries to ~400 characters).
2. Use site:example.com when you already know the best source domain.
3. Prefer a URL + a clear instruction when you want one page summarized (Extract is tighter than broad Search).

Updates

Check for Updates

Guardian checks for updates automatically. You can also:

• Click Check Now in Settings
• View current version information

Update Feed URL

Advanced users can configure a custom update feed URL for self-hosted update servers via the GUARDIAN_UPDATE_FEED_URL environment variable.

Configuration Storage

Guardian stores configuration in platform-specific locations:

guardian.lock

The guardian.lock file ensures reproducible scans across different machines and time periods.

What It Does

• Pins rules version (hash)
• Records workspace ID
• Tracks Guardian version
• Ensures scan consistency

Lock File Location

your-project/
├── guardian.lock          # Auto-generated
├── .guardian/
│   ├── AGENT_INSTRUCTIONS.md
│   ├── baseline.json
│   ├── critiques.json
│   ├── critiques.md
│   ├── history.jsonl
│   ├── agent_queue.jsonl
│   ├── chat.md
│   ├── chat_queue.md
│   ├── STALL              # Only while stalled
│   └── undo/              # Only after applying a fix
└── .agent/rules/

Lock Schema

{
  "schema_version": 1,
  "created_at": "2026-02-10T12:00:00Z",
  "updated_at": "2026-02-10T12:00:00Z",
  "guardian_version": "1.2.3",
  "workspace_id": "sha256-hash",
  "rules_hash": "abc123...",
  "rules_source": ".agent/rules"
}

CLI Enforcement Modes

When using guardian-cli, you can enforce lock compliance:

# Warn mode (default): Warn on mismatch but continue
 guardian-cli scan --root . --lock-mode warn

# Strict mode: Fail scan on any mismatch
guardian-cli scan --root . --lock-mode strict

# Off mode: Ignore lock file
guardian-cli scan --root . --lock-mode off

Migration

If upgrading from older releases (before guardian.lock existed):

1. Open your project in Guardian Desktop
2. Run a scan (lock file auto-created)
3. Recreate baseline via UI
4. See Migration Guide for details

Semantic Index Settings

Configure semantic search behavior:

Embedding Provider

Choose how code embeddings are generated:

# Environment Variables
GUARDIAN_EMBED_MODE=auto            # "auto", "openai", "ollama", "local"
GUARDIAN_EMBED_MODEL=text-embedding-3-small
GUARDIAN_EMBED_MODEL_OLLAMA=nomic-embed-text
GUARDIAN_OFFLINE=1                  # Forces local hash mode

Auto mode behavior

• If a valid OpenAI key exists, auto mode prefers OpenAI.
• If no OpenAI key exists, auto mode skips OpenAI entirely and starts with Ollama, then local hash fallback.

Similarity Thresholds

Guardian filters semantic matches at a minimum similarity score of 0.72.

Best Practices

1. Backup Configuration: Export a PDF snapshot before major changes
2. Secure API Keys: Never share or commit API keys
3. Test After Changes: Verify Guru works after changing providers
4. Keep Updated: Enable automatic update checks
5. Commit guardian.lock: Include in version control for team consistency
6. Use Strict Mode in CI: Enforce lock compliance in CI/CD pipelines