npx proof-ai check ./generated.py
# ✓ Verification passed — 1/1 blocks, no issues

The Problem

Every AI coding tool — Cursor, Copilot, Devin, ChatGPT — generates code that looks right but might:

• Not run — missing imports, wrong syntax, hallucinated packages
• Be insecure — hardcoded API keys, eval(), SQL injection
• Be incomplete — pass, // TODO, placeholder values

You shouldn't ship code you haven't tested. Proof tests it for you.

Why Proof

| | Proof | Guardrails AI | Manual review | |---|---|---|---| | Runs the code | Yes (Docker sandbox) | No | Sometimes | | Catches runtime errors | Yes | No | Maybe | | Free & local | Yes (just Docker) | Cloud API | Yes | | Zero API keys | Yes | Requires key | Yes | | CI-native | Exit code 0/1 | SDK only | Manual | | AI-specific rules | 10 built-in | Structured output | None |

Quick Start

Prerequisites

• Node.js >= 18
• Docker (for sandbox execution) — Install Docker

Docker is optional. Without it, Proof still runs 10 built-in rules + syntax checks. Docker adds actual code execution in isolated containers.

Install

npm install proof-ai

CLI

# Verify a file
npx proof-ai check ./script.py

# Verify a code string
npx proof-ai verify --code 'print("hello")' --language python

# Verify an LLM response (all code blocks)
npx proof-ai verify --text "$(cat response.md)"

# Pipe from stdin
echo 'console.log("hi")' | npx proof-ai verify --stdin --language javascript

# JSON output (for CI)
npx proof-ai check ./script.py --json

# Skip sandbox (rules + syntax only)
npx proof-ai check ./script.py --sandbox none

# Only security rules
npx proof-ai check ./script.py --rules security

API

import { verify } from "proof-ai";

// Verify a code string
const result = await verify({
  code: 'import pandas as pd\ndf = pd.read_csv("data.csv")',
  language: "python",
});

if (!result.passed) {
  for (const issue of result.issues) {
    console.log(`[${issue.severity}] ${issue.message}`);
  }
}

// Verify all code blocks in an LLM response
const result = await verify({
  text: llmResponse,
  sandbox: "docker",
  rules: "all",
});

console.log(`${result.stats.passedBlocks}/${result.stats.totalBlocks} blocks passed`);

// Verify a file
const result = await verify({ file: "./generated.py" });

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | code | string | — | Code string to verify | | text | string | — | Markdown/text containing fenced code blocks | | file | string | — | Path to a file to verify | | language | string | auto-detect | python, javascript, typescript | | sandbox | boolean \| "docker" \| "e2b" | true | Sandbox provider (auto-detect, force Docker/E2B, or disable) | | rules | string \| Rule[] \| false | "all" | "all", "security", "ai-mistakes", "code-quality", custom array, or false | | install | string[] | — | Packages to install in sandbox (e.g., ["pandas"]) | | env | Record<string, string> | — | Environment variables for sandbox | | timeout | number | 30 | Sandbox timeout in seconds |

Rules

Proof ships with 10 built-in rules across 3 categories:

Security (3 rules)

| Rule | What it catches | |------|----------------| | security/no-hardcoded-secrets | API keys, tokens, passwords in code | | security/no-dangerous-operations | eval(), exec(), os.system(), rm -rf | | security/no-sql-injection | SQL built with string concatenation |

AI Mistakes (4 rules)

| Rule | What it catches | |------|----------------| | ai-mistakes/no-placeholder-values | YOUR_API_KEY, REPLACE_ME, example.com | | ai-mistakes/no-incomplete-code | # rest of implementation, standalone ..., pass | | ai-mistakes/no-mixed-syntax | Python def in JS, const in Python, console.log in Python | | ai-mistakes/no-hallucinated-imports | Commonly hallucinated package names |

Code Quality (3 rules)

| Rule | What it catches | |------|----------------| | code-quality/balanced-brackets | Unclosed (), [], {} | | code-quality/no-unused-imports | Imported names not used in code | | code-quality/no-empty-blocks | Empty function bodies, empty catch blocks |

Custom Rules

import { verify, defineRule } from "proof-ai";

const noFetch = defineRule({
  id: "custom/no-fetch",
  name: "No fetch calls",
  pattern: /\bfetch\s*\(/,
  message: "Direct fetch() calls are not allowed — use the API client",
  severity: "error",
  suggestion: "Use apiClient.get() instead of fetch()",
});

const result = await verify({
  code: myCode,
  language: "typescript",
  rules: [noFetch],
});

List all rules from the CLI:

npx proof-ai rules list

Sandbox Security

When Docker is available, Proof runs code with hardened security defaults:

• No network access — containers run with --network=none
• Memory limit — 256MB max (--memory=256m)
• CPU limit — 0.5 CPUs (--cpus=0.5)
• Process limit — 64 PIDs (--pids-limit=64)
• Read-only filesystem — --read-only with tmpfs for /tmp
• No privilege escalation — --security-opt=no-new-privileges
• Auto-cleanup — containers are created with --rm

Network access is only enabled temporarily when install packages are specified.

CI Integration

GitHub Actions

name: Verify AI Code
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm install proof-ai

      - name: Verify generated code
        run: npx proof-ai check ./src/generated/*.py --json

Pre-commit Hook

# .husky/pre-commit
npx proof-ai check ./src/generated/ --sandbox none

In Your AI Pipeline

import { verify } from "proof-ai";

async function generateAndVerify(prompt: string) {
  const llmResponse = await callLLM(prompt);

  const result = await verify({
    text: llmResponse,
    sandbox: "docker",
    rules: "all",
  });

  if (!result.passed) {
    // Retry, flag for review, or use a different model
    console.log("Issues found:", result.issues);
    return null;
  }

  return llmResponse;
}

E2B Cloud Sandbox (Optional)

For serverless environments (Vercel, Cloudflare Workers) where Docker isn't available, Proof supports E2B as a cloud sandbox:

npm install @e2b/code-interpreter
export E2B_API_KEY=your_key

const result = await verify({
  code: myCode,
  language: "python",
  sandbox: "e2b",
});

System Check

npx proof-ai doctor

  Proof Doctor
  ─────────────────────────────────

  ✓ Docker is available
  ○ E2B not configured (optional)
  ✓ Node.js v20.10.0

  ✓ Ready to verify code!

Architecture

proof-ai/
├── src/
│   ├── index.ts          # Public API exports
│   ├── verify.ts         # Main verification pipeline
│   ├── extract.ts        # Code block extraction from markdown
│   ├── syntax.ts         # Offline syntax checking
│   ├── report.ts         # Terminal output formatting
│   ├── cli.ts            # CLI (proof verify, check, rules, doctor)
│   ├── sandbox/
│   │   ├── docker.ts     # Docker sandbox (default)
│   │   ├── e2b.ts        # E2B cloud sandbox (optional)
│   │   └── index.ts      # Auto-detection
│   └── rules/
│       ├── engine.ts     # Rule matching engine
│       ├── define.ts     # defineRule() helper
│       └── builtin/      # 10 built-in rules
│           ├── security.ts
│           ├── ai-mistakes.ts
│           └── code-quality.ts
├── test/                 # 72 tests
├── bin/proof.js          # CLI entry point
└── package.json          # 2 dependencies (chalk, commander)

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE