Introduction

Vigils is a local-first control plane for AI agents designed to monitor, approve, and secure interactions between agents and sensitive tools or data. Built with Rust, Tauri, and Chrome MV3, it ensures that prompts, secrets, and audit trails remain entirely on the user’s machine, eliminating the risk of remote exposure. The system operates as an intermediary between AI agents and their targets, enforcing four core guarantees: visibility into agent actions, pre-approval for risky operations, prevention of credential leakage, and containment of execution failures.

The architecture is modular, composed of independently testable Rust crates that handle audit logging, policy enforcement, firewalling, approval workflows, redaction, credential management, sandboxing, and remote authentication. These components integrate into three primary applications: a CLI gateway (vigil-hub), a desktop app (Tauri + Vue 3), and a Chrome MV3 browser extension. Each layer adheres to a fail-closed design, ensuring that any breach at one level does not compromise the entire system.

Vigils supports a wide range of AI agents, including Claude Code, Codex, Cursor, Zed, Kimi CLI, ZCode, and browser-based assistants. It intercepts tool calls, file accesses, API requests, and web UI interactions, applying granular controls to prevent unauthorized or malicious activity. The system is particularly focused on mitigating credential leaks, prompt injection, and unauthorized data exfiltration—common risks when AI agents operate with elevated privileges.

The project is open-source under the Apache 2.0 license, with active development since 2026. It emphasizes verifiable security through formal verification of core components, third-party audits, and compliance with standards like SOC2 Type II and ISO 27001. Vigils is positioned as a foundational tool for securing AI agent workflows in both individual and enterprise environments.

How It Works

Vigils functions as a local control plane that sits between AI agents and the tools or data they interact with. Its architecture is divided into distinct layers, each responsible for a specific security function. The system operates under a default-deny policy, meaning no action is permitted unless explicitly approved or allowed by predefined rules. This approach minimizes the attack surface and ensures that only authorized operations proceed.

Core Layers and Components

The system is structured around eight key layers, each implemented as a separate Rust crate for modularity and isolation.

Every agent action is recorded with full-text search capabilities (FTS5) over redacted trails, ensuring immutability and traceability.
Policy Layer (vigil-policy): Enforces a Rust-based policy DSL that defines rules for tool access, credential usage, and operation approvals. Policies are agent-specific and can be dynamically adjusted. The default-deny firewall ensures that only explicitly permitted actions are executed.
Firewall Layer (vigil-firewall): Acts as a gatekeeper for tool calls, applying per-agent rules and OAuth scope allow-lists for remote MCP (Machine Control Plane) servers. This layer prevents unauthorized access to sensitive tools or APIs.
Approval Layer (vigil-mcp broker): Implements human-in-the-loop approvals for high-risk operations, such as file writes, network requests, or destructive actions. Approvals can be scoped to single operations, sessions, or specific tools, with grants recorded in the audit trail.
Redaction Layer (vigil-redaction): Detects and masks secrets and personally identifiable information (PII) using two engines: a deterministic hard-fingerprint system for structured credentials (e.g., GitHub PATs, Stripe keys, database URLs) and an optional ML-based ensemble for broader PII detection (names, addresses, dates). The redaction engine operates in fail-closed mode, ensuring no plaintext secrets reach models, logs, or UIs.
Lease Layer (vigil-lease): Manages short-lived credential leases, injecting secrets only into the child process requiring them. Plaintext credentials are never persisted; instead, they are revoked immediately after use via RAII (Resource Acquisition Is Initialization) mechanisms.
Runner Layer (vigil-runner): Executes tool commands in isolated environments using either native processes or WebAssembly (Wasm) via Wasmtime. The runner defaults to fail-closed behavior, halting execution if isolation is compromised.
Gateway Layer (vigil-mcp): Acts as a unified entry point for MCP servers, handling both stdio and HTTP-based tool calls. It includes descriptor pinning to detect drift (e.g., changes in tool definitions) and supports bare-command stdio upstreams (e.g., npx, node, python), resolving paths via the host’s PATH before sandboxing.
Browser Layer (vigil-browser): Powers the Chrome MV3 extension, which intercepts paste and submit events on AI platforms (e.g., ChatGPT, Claude, Gemini, Perplexity) to prevent secrets or PII from entering the LLM context.
It offers a thin, well-documented interface for integrating Vigils into other tools or workflows.

Execution Flow

When an AI agent initiates an action, Vigils intercepts the request and processes it through the following stages:

Redaction: Secrets and PII are scanned and masked using the redaction engine before the request reaches the model or logs. This prevents credential leakage in prompts, tool arguments, or audit trails.
Firewall Check: The request is evaluated against the policy DSL. If the action is not explicitly permitted, it is blocked unless it requires human approval.
Approval Queue: High-risk operations (e.g., file modifications, network calls) are paused for manual review.
Sandbox Execution: The operation is executed in an isolated environment (native or Wasm) with restricted permissions.
Audit Logging: Every action is recorded in the tamper-evident ledger, including the outcome (allowed, blocked, approved). The ledger supports full-text search for forensic analysis.
Credential Lease Management: If the operation requires credentials, they are injected as short-lived environment variables into the sandbox. The lease is automatically revoked after execution, leaving no residue.
Outbound Gate (Opt-In): For LLM API calls (e.g., Claude Code, Codex), Vigils optionally proxies requests through a loopback HTTP gate. This scans request bodies for credentials before they leave the machine, addressing blind spots like @file inlining or model-generated secrets.

Desktop and Browser Integration

Vigils provides two primary user interfaces:

Desktop App (Tauri + Vue 3): A graphical interface that simplifies deployment and monitoring. Users can deploy the 'Guardian' mode with a few clicks, which automatically detects AI agents on the system, backs up their configurations, and applies Vigils protections. The app includes an approval queue, activity feed, and real-time status updates. It supports bilingual interfaces and integrates with the underlying vigil-hub engine.
Chrome MV3 Extension: Intercepts paste and submit events on AI platforms to prevent secrets from entering the LLM context.

Installation and Deployment

Vigils is distributed as pre-built binaries for Windows, macOS (Apple Silicon and Intel), and Linux. Users can install the CLI via a one-line command or download platform-specific installers.

Hard-Fingerprint (Default): Uses deterministic rules to detect 17+ credential classes (e.g., GitHub PATs, Stripe keys, database URLs). This engine is instant and requires no additional dependencies.
The ML build is available as a separate asset and can coexist with the default engine.

The ML engine is supported on Linux (glibc ≥ 2.28) and macOS (Apple Silicon only); Intel macOS users default to the hard-fingerprint engine due to upstream limitations.

Use Cases

Vigils addresses critical security challenges in AI agent workflows, particularly in environments where agents interact with sensitive tools, APIs, or data. Its use cases span individual developers, teams, and enterprise deployments.

Preventing Credential Leaks

AI agents often require access to credentials (API keys, tokens, database URLs) to perform tasks. Without proper safeguards, these credentials can leak into prompts, logs, or model responses, exposing them to unauthorized parties.

Redaction: Secrets are masked before reaching models, logs, or UIs. The hard-fingerprint engine detects structured credentials (e.g., github_token, aws_access_key), while the ML engine identifies broader PII.
Outbound Gate: For LLM API calls (e.g., Claude Code, Codex), Vigils proxies requests through a loopback gate that scans request bodies for credentials before they leave the machine.
Credential Leases: Secrets are injected as short-lived environment variables into sandboxed processes and revoked immediately after use. No plaintext credentials are persisted in logs or audit trails.

For example, if an agent accidentally pastes a GitHub token into a Claude Code chat window, the Chrome extension or desktop app will intercept and redact the token before it reaches the model. The audit trail records the event without exposing the credential.

Enforcing Approval for High-Risk Operations

Some agent actions—such as file modifications, network requests, or destructive operations—pose significant risks if executed without oversight. Vigils implements a human-in-the-loop approval system to ensure these actions are reviewed before execution. Key features include:

Approval Queue: Risky operations are paused and displayed in an approval queue. Users can grant permissions with scopes such as one-time, session-wide, or tool-specific.
Policy Scoping: Approval rules can be tailored to specific agents or tools, reducing the likelihood of unauthorized actions.

For instance, if an agent attempts to write a file to a sensitive directory, Vigils will pause the operation and prompt the user for approval. The decision is logged, and subsequent similar actions can be automatically allowed or denied based on the policy.

Securing Agent Tool Calls

AI agents frequently interact with external tools, APIs, or local files. Without proper controls, these interactions can lead to unauthorized access, data exfiltration, or tool tampering.

Firewall Rules: Tool calls are gated by a default-deny policy DSL. Only explicitly permitted tools or APIs can be accessed, with per-agent rules enforcing least privilege.
Descriptor Pinning: Vigils monitors tool definitions for drift (e.g., changes in API endpoints or command-line arguments). If a tool’s definition changes unexpectedly, the system alerts the user to potential tampering.
Sandbox Execution: Tools are executed in isolated environments (native or Wasm) with restricted permissions. Linux Landlock ensures filesystem isolation, and envclear prevents child processes from inheriting sensitive environment variables.

For example, if an agent attempts to call an unauthorized API or execute a command with elevated privileges, Vigils will block the request unless it has been explicitly approved. The audit trail captures the attempt, providing visibility into potential security incidents.

Browser-Based AI Assistant Security

Many AI assistants operate within web browsers, where users may accidentally paste sensitive information into chat interfaces.

Chrome MV3 Extension: Intercepts paste and submit events on platforms like ChatGPT, Claude, Gemini, and Perplexity. It applies the same redaction rules as the desktop app, preventing secrets from entering the LLM context.
Real-Time Interception: Secrets or PII are masked immediately upon paste or submit, ensuring they never reach the model or logs. The extension supports hard-fingerprint detection for credentials and broader PII identification via the ML engine.

For example, if a user accidentally pastes an AWS access key into a ChatGPT prompt, the extension will redact the key before it is sent to the model. The user receives no indication of the block, but the audit trail records the event for review.

Enterprise and Team Workflows

Teams using AI agents for business-critical tasks—such as code generation, API integrations, or data processing—require auditability and compliance with security policies.

Immutable Audit Trails: Every tool call generates a tamper-evident DecisionRecord in the SHA-256 hash-chained ledger. This provides a verifiable history of agent actions, essential for compliance and forensic analysis.
Mandatory Approvals: High-risk operations (e.g., file writes, network calls) automatically enter the approval queue, ensuring oversight for sensitive actions.
Centralized Policy Management: Policies can be defined at the agent or team level, with granular controls over tool access, credential usage, and approval workflows.
Red-Team Testing: Vigils includes built-in test scenarios for prompt injection, tool descriptor tampering, and secret leakage. These are enforced in CI to ensure the system remains resilient against evolving threats.

For instance, a development team using Claude Code for internal tooling can deploy Vigils to enforce approvals for API key usage and maintain an audit trail of all agent actions. This ensures compliance with internal security policies and provides visibility into potential risks.

Developer and CLI Workflows

Developers integrating AI agents into their workflows can use Vigils to secure tool calls, API interactions, and credential management.

MCP Gateway: Acts as a unified entry point for multiple AI agents, routing tool calls through Vigils’ security layers. Supports both stdio and HTTP-based tool invocations.
Sandboxed Execution: Tools are executed in isolated environments with restricted permissions, minimizing the risk of privilege escalation or data leaks.
Audit Integration: All agent actions are logged in the tamper-evident ledger, providing visibility into tool usage and potential security incidents.

For example, a developer using Codex for code generation can wrap the agent’s tool calls through vigil-hub to enforce redaction, approvals, and sandboxing. This ensures that sensitive operations are reviewed and executed securely.

Key Features and Capabilities

Vigils combines multiple security mechanisms to create a comprehensive defense-in-depth strategy for AI agent workflows. Its features are designed to address specific threats while maintaining usability and transparency.

Tamper-Evident Audit Ledger

The audit ledger is the foundation of Vigils’ transparency and accountability. It uses SQLite with SHA-256 hash chains to ensure that every agent action is recorded immutably.

Hash-Chained Records: Each entry in the ledger is cryptographically linked to the previous one, making tampering detectable. Any alteration to a record invalidates the chain, providing proof of integrity.
Full-Text Search (FTS5): The ledger supports full-text search over redacted trails, enabling efficient querying of audit logs for forensic analysis or compliance reporting.
Redaction-Safe Logging: Only redacted versions of prompts, tool arguments, and responses are stored. Plaintext secrets are never logged, ensuring compliance with privacy regulations.

An auditor can later verify that no unauthorized modifications occurred.

Default-Deny Firewall

Vigils operates under a default-deny policy, meaning no tool call or operation is permitted unless explicitly allowed by the policy DSL. This minimizes the attack surface and enforces least privilege.

Policy DSL: A Rust-based domain-specific language for defining rules. Policies can specify allowed tools, APIs, or file paths, with per-agent granularity.
OAuth Scope Allow-Lists: For remote MCP servers, Vigils enforces OAuth scope restrictions, ensuring agents only access authorized endpoints.

For instance, a policy might allow an agent to read files from /tmp but deny writes to /etc. If the agent attempts an unauthorized write, the request is blocked and logged.

Human-in-the-Loop Approvals

High-risk operations—such as file modifications, network requests, or destructive actions—require explicit approval before execution.

Approval Queue: Risky operations are paused and displayed in a queue for user review. Approvals can be scoped to single operations, sessions, or tools.
Scoped Grants: Users can grant permissions with temporal or contextual limits (e.g.,

Secret and PII Redaction

Vigils prevents secrets and PII from leaking into models, logs, or UIs through a dual-layer redaction system.

Hard-Fingerprint Detection: Deterministic rules identify 17+ credential classes (e.g., GitHub PATs, Stripe keys, database URLs). These rules are updated regularly to cover new credential formats.
Fail-Closed Merge Layer: The redaction engine operates in fail-closed mode, ensuring that no plaintext secrets reach their destination.
Outbound LLM-API Gate: For LLM API calls (e.g., Claude Code, Codex), Vigils proxies requests through a loopback gate that scans request bodies for credentials before they leave the machine. This addresses blind spots like @file inlining or model-generated secrets.

For example, if an agent’s prompt contains a GitHub token, the redaction engine will mask it before the prompt reaches the model. The audit trail records the event without exposing the credential.

Credential Lease Management

Vigils avoids persisting plaintext credentials by using short-lived leases.

Short-Lived Injection: Credentials are injected as environment variables into the sandboxed process requiring them. The lease is revoked immediately after execution via RAII.
No Plaintext Persistence: Secrets are never stored in logs, audit trails, or configuration files. Only reference aliases (e.g., secret://github/read-only) appear in records.
System Keychain Integration: Real credentials are stored in the system keychain, while Vigils holds only aliases. This ensures that secrets are never exposed outside the secure context.

For instance, if an agent needs a GitHub token to fetch a repository, Vigils retrieves the token from the keychain, injects it into the sandboxed process, and revokes it immediately afterward. The audit trail records the alias, not the token itself.

Sandboxed Execution

Tools and commands are executed in isolated environments to prevent privilege escalation or data leaks.

Native and Wasm Runners: Commands can be executed as native processes or in WebAssembly (Wasm) via Wasmtime.
Environment Clearing (envclear): Child processes inherit only the minimal required environment, preventing them from accessing sensitive variables from the parent process.

Sources

github.comhttps://github.com/duncatzat/vigils

vigils