VERA

Verification & Reliability Architecture

An adversarial verification layer for autonomous AI software engineering.

VERA wraps autonomous coding agents inside deterministic verification contracts, an isolated execution environment, and tamper-evident evidence recording so that task completion is based on verifiable conditions rather than an agent's own success claim.

The Problem: False Success in Autonomous Coding
The VERA Model
How VERA Works
Architecture
Verification Contracts
Quick Start
Example
Security Model
Evidence & Integrity
Agent Integrations
Configuration
CI/CD & Release Engineering
Project Structure
Documentation
Validation & Benchmarks
Limitations
Roadmap
FAQ
Development
Contributing
License

The Problem: False Success in Autonomous Coding

LLM-based coding agents suffer from a fundamental verification problem: the agent is both the actor performing the task and the system claiming the task succeeded. This creates an inherent trust boundary breakdown.

When an AI agent's goal is to "Fix the failing database test," potential "false-success" behaviors emerge, including:

Modifying the test to pass instead of fixing the underlying bug
Deleting a failing assertion
Weakening validation or skipping a required verification command
Changing unrelated architecture to sidestep the problem
Claiming completion after partial execution based solely on LLM intuition

VERA addresses this by acting as an external, adversarial verification boundary.

AI AGENT: "I believe I completed the task." VERA: "The task satisfies its predefined verification contracts."

The VERA Model

The core philosophy of VERA is that an agent is not trusted to determine whether it succeeded. Instead, execution follows a strict pipeline:

Agent → VERA → Verification Contracts → VeraBox (Sandbox) → Evidence → Independent Verification → Verified / Rejected

VERA evaluates predefined, deterministic conditions. If the conditions fail, the task fails—regardless of the agent's internal confidence level.

How VERA Works

The verification lifecycle is completely independent of the agent's internal reasoning loop.

Define the Goal: You establish the primary task and output.
Define Verification Contracts: You establish the strict, deterministic boundaries for success.
Start the Agent: VERA wraps the agent execution.
Agent Performs Work: The agent iterates through its loop.
VERA Observes: The orchestrator records execution and gathers evidence.
Sandbox Enforces Isolation: VeraBox enforces resource boundaries and isolation.
Contracts Evaluate Results: After the agent halts, contracts evaluate the recorded output.
Evidence is Persisted: Tamper-evident logs are finalized.
Verification Produces Result: A cryptographic decision is reached.
Accept/Reject: Completion is either cryptographically accepted or forcefully rejected.

sequenceDiagram
    participant U as User
    participant V as VERA Orchestrator
    participant A as AI Agent
    participant S as VeraBox Sandbox
    participant C as Contracts

    U->>V: Define Goal & Contracts
    V->>S: Initialize Isolation
    V->>A: Start Agent
    loop Agent Execution
        A->>S: Perform Work
        S->>V: Record Actions & Evidence
    end
    V->>C: Evaluate Results
    C-->>V: Verification Result
    alt Verified
        V->>U: Verified Completion
    else Verification Failure
        V->>U: Rejected
    end

Architecture

VERA is structured into two primary technical domains: the Orchestrator and the Sandbox.

flowchart TB
    A[Autonomous AI Agent] --> B[VERA Orchestrator]

    B --> C[Goal & Verification Contracts]
    B --> D[VeraBox Sandbox]
    B --> E[Evidence Store]

    D --> F[Isolated Execution]
    D --> G[Resource Controls]

    C --> H[Exit Code Contract]
    C --> I[YAGNI Diff Contract]
    C --> J[Readonly Contract]

    F --> K[Agent Actions]
    K --> L[Observed Results]

    L --> E
    H --> M[Verification Result]
    I --> M
    J --> M
    E --> M

    M --> N{Verified?}
    N -->|Yes| O[Verified Completion]
    N -->|No| P[Verification Failure]

Orchestrator (Go)

The Go-based orchestrator manages the .vera/goal.yaml configuration, contract evaluation, agent lifecycle recording, and evidence management. It is responsible for bridging the gap between agent commands and cryptographic verification logic.

VeraBox (Rust)

The Rust-based sandbox (verabox) provides an OS-independent capability API for process isolation, resource limits, and execution policies.

Linux: Uses namespaces and cgroups for isolation and limits.
Windows: Uses Job Objects for process bounds, though strict filesystem isolation is currently unsupported on native Windows in V1. (See Limitations).

Evidence Database

Evidence is managed via an HMAC-chained SQLite database. It maintains an append-only integrity model to detect manipulation.

Verification Contracts

Contracts define what "done" means independently of the agent. Rather than evaluating whether the code "looks good," contracts evaluate whether the code meets strict, objective constraints.

Contract	Purpose	What it Checks
exit_code	Validate command execution	Ensures a specified validation command (e.g., `go test`) exits successfully.
yagni_diff	Detect unexpected changes	Ensures the generated `git diff` remains within the declared constrained files, preventing arbitrary rewrites.
readonly	Protect selected paths	Ensures that explicitly protected files or directories (e.g., test fixtures) have not been modified.

Quick Start

1. Installation

Download the latest binary from the Releases page, or build from source:

go install github.com/Grevix/vera/cmd/vera@latest

2. Initialize VERA

vera init

Run vera init from the root of the repository you want VERA to verify. This creates .vera/goal.yaml, where you define the task and verification contracts.

3. Record Agent Execution

VERA wraps your agent's execution to observe and sandbox it:

vera record claude -p "Fix the database race condition"

4. Verify Execution

Once the agent stops, independently verify that its output strictly adhered to the contracts:

vera verify

If the agent cheated (e.g., modified a test instead of the source code), VERA safely catches the violation and fails the verification.

Example

To configure a verification boundary, edit the generated .vera/goal.yaml after running vera init:

goal: "Fix the database race condition"
contracts:
  exit_code:
    command: "go test -v -race ./pkg/db"
    expected: 0
  readonly:
    paths:
      - "pkg/db/db_test.go"

In this scenario, if the agent attempts to delete the race condition test in pkg/db/db_test.go to achieve an exit code of 0, the readonly contract will immediately trigger a Verification Failure.

Security Model

VERA assumes the agent can behave adversarially, incorrectly, or unpredictably.

Because of this, VERA's security philosophy dictates that:

Verification is strictly external to the agent.
Execution boundaries are enforced by VeraBox.
Verification contracts are mathematically deterministic.
Evidence is integrity-protected.

What VERA Protects Against:

Agents modifying tests to achieve false success.
Agents claiming completion when tasks fail.
Agents violating explicit file modification constraints.
Accidental evidence database manipulation.

What VERA Does NOT Protect Against:

Fully compromised local user accounts (same-user attacks).
Strict filesystem virtualization on Windows V1 (an agent using native tools can access host files).
Semantic bypasses (e.g., writing a backdoor into a valid file that passes tests).

For complete technical details, see SECURITY.md.

Evidence & Integrity

To guarantee verification hasn't been bypassed, VERA logs actions to a local SQLite evidence database.

This evidence is protected by an HMAC chained integrity model. Every event logged to the database is hashed alongside the hash of the previous event using a master HMAC key (~/.vera/master.key) located outside the project workspace.

This append-only behavior protects against accidental modification and ordinary database manipulation (e.g., an agent executing SQL to flip a FAIL to a PASS), ensuring that verification consumes provably authentic evidence. (Note: Remote attestation of evidence is planned for a future release).

Agent Integrations

VERA does not replace your agent. It wraps and verifies it.

Agent / Interface	Status	Integration Workflow
Antigravity	CLI / MCP	Use via CLI or MCP Integration
Claude Code	CLI Workflow	`vera record claude ...` (See Docs)
Codex	CLI Workflow	`vera record codex ...` (See Docs)
Gemini	CLI Workflow	`vera record gemini ...` (See Docs)

Note: Claude Code, Codex, and Gemini do not currently have direct native plugin integration with VERA.

Configuration

VERA uses a .vera/goal.yaml file to define task requirements and constraints. The configuration maps to the supported contracts:

goal: The human-readable task definition.
contracts.exit_code.command: The validation script or test command to run.
contracts.readonly.paths: An array of file paths the agent is strictly prohibited from modifying.
contracts.yagni_diff.allowed_paths: An array of paths the agent is strictly restricted to modifying (all other paths are prohibited).

CI/CD & Release Engineering

VERA applies verification principles to its own development process. The project enforces an adversarial, automated CI/CD pipeline in .github/workflows/.

The pipeline enforces:

Go Formatting & Vet checks
Gosec Security Scanning
TruffleHog Secret Scanning (with dynamic PR/Push branch resolution)
Race-enabled Go tests
Cross-platform Rust sandbox tests (Ubuntu, Windows, macOS)
Nightly Go Fuzz testing
Cross-platform release compilation (Linux, macOS, Windows; AMD64 & ARM64)
Automated Checksum generation & SBOM (Software Bill of Materials) generation
Strict artifact integrity checks

Project Structure

vera/
├── cmd/
│   ├── vera/           # CLI entrypoint
│   └── mutator/        # Security mutator
├── pkg/
│   ├── contracts/      # Deterministic verification logic
│   ├── evidence/       # Integrity-protected SQLite recording
│   └── orchestrator/   # Core execution loop
├── verabox/
│   └── src/            # Rust isolation sandbox
├── scripts/            # Certification and test scripts
├── docs/               # Technical documentation hub
├── .github/
│   └── workflows/      # CI/CD and release pipelines
├── go.mod
├── Cargo.toml
└── README.md

Documentation

The project includes an extensive library of architectural and validation documents in the docs/ directory:

Architecture & Design

Release & Certification

Benchmarks

Integrations

Integrations Hub

Validation & Benchmarks

VERA has undergone rigorous internal validation to guarantee reliability under adversarial conditions, processing over 50,000 continuous operations without a single evidence failure. Refer to the Final V1 Certification and Official Benchmark for detailed performance, security, and verification throughput metrics.

Limitations

As a serious infrastructure product, VERA openly documents its limitations:

Windows Sandbox Isolation: The V1 VeraBox relies on Windows Job Objects, which provide robust CPU/Memory bounding but do not provide strict filesystem virtualization. Agents on Windows can read/write files accessible to the host user unless run inside a secondary VM.
Evidence Storage: The HMAC evidence database relies on a local key. If the user account is fully compromised, the evidence chain can theoretically be manipulated.
Native Interfaces: Native plugin integrations for tools like Claude Code are not yet implemented; VERA relies on CLI wrapping for these agents.

Roadmap

Current:

V1 Core (Orchestrator, VeraBox, Local HMAC Evidence, Basic Contracts)
Cross-Platform Binary Availability

Planned (V2 & Beyond):

Strict filesystem virtualization on Windows (e.g., via specialized kernel drivers or hypervisor layers)
Remote attestation of evidence chains
Deep native plugin integrations with proprietary LLM code agents
Advanced syntactic and semantic code-level contracts

FAQ

What is VERA? VERA is an adversarial verification layer that ensures autonomous AI software agents complete tasks based on deterministic contracts rather than their own self-reported success.

Why do AI coding agents need verification? Agents often suffer from "false success" where they satisfy an LLM prompt by breaking tests, skipping steps, or altering requirements. VERA ensures the objective requirements are strictly satisfied.

Is VERA an AI coding agent? No. VERA wraps and verifies agents rather than replacing them.

Does VERA prevent an agent from making mistakes? VERA does not make the agent intelligent. It verifies whether predefined requirements were satisfied. If the agent makes a mistake that violates a contract, VERA catches it.

Can VERA detect an agent modifying tests? Yes. By using the readonly contract, you can explicitly prohibit the agent from touching test files. If the agent attempts to modify them, verification will fail.

Is VERA a sandbox? VeraBox provides the execution sandbox (isolating memory, processes, and network), but the overall VERA system is broader, encompassing the contracts, evidence generation, and the cryptographic verification engine.

Does VERA work with Claude Code? Yes. You can use the CLI workflow (vera record claude ...) to wrap Claude Code execution. Native plugin support is not currently available.

Does VERA support MCP? Yes. Antigravity can be used via the CLI or via MCP integration. See MCP Integration.

Is VERA production-ready? VERA V1 has achieved its official certification thresholds for release readiness. However, developers running on Windows should be acutely aware of filesystem isolation limitations. Review the Release Readiness and Security Model documents before deploying.

Where is evidence stored? Locally in a .vera/vera-evidence.db SQLite database, secured via an HMAC chained hashing model.

Can I contribute? Yes. Please see our Contributing Guide.

Development

Prerequisites

Go 1.22+
Rust Stable
make (optional, for scripting)

Build

To build the Go orchestrator:

go build -o vera ./cmd/vera

To build the Rust sandbox:

cd verabox
cargo build --release

Test

Run Go tests with the race detector:

go test -v -race ./pkg/... ./cmd/...

Run Rust tests:

cd verabox
cargo test

Security Checks

gosec -exclude=G204,G304 ./...
go vet ./...

Contributing

VERA is open source. We welcome issues, PRs, and architectural discussions. Please review our Contributing Guidelines and Code of Conduct.

If you discover a security vulnerability, please follow the disclosure instructions in SECURITY.md. Do not publicly disclose vulnerabilities in GitHub Issues.

License

Licensed under the Apache License 2.0. See LICENSE for details.

VERA
Verification & Reliability Architecture

Built for a world where autonomous software agents need to prove what they did—not merely say they did it.

Documentation · Security · Contributing · Releases

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd		cmd
docs		docs
pkg		pkg
scripts		scripts
verabox		verabox
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md
go.mod		go.mod
go.sum		go.sum

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

VERA

Verification & Reliability Architecture

Table of Contents

The Problem: False Success in Autonomous Coding

The VERA Model

How VERA Works

Architecture

Orchestrator (Go)

VeraBox (Rust)

Evidence Database

Verification Contracts

Quick Start

1. Installation

2. Initialize VERA

3. Record Agent Execution

4. Verify Execution

Example

Security Model

Evidence & Integrity

Agent Integrations

Configuration

CI/CD & Release Engineering

Project Structure

Documentation

Validation & Benchmarks

Limitations

Roadmap

FAQ

Development

Prerequisites

Build

Test

Security Checks

Contributing

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages