"Claude is AI and can make mistakes. Please double-check responses." — Every AI company says this. SOVR does the double-checking for you.

The Problem

AI agents are powerful but unreliable. Every time you delegate a task to an AI, you spend more time verifying the output than it took to generate. This is the double-check dilemma — the hidden cost that breaks the promise of AI automation.

SOVR solves this by placing a sovereign verification layer between AI intent and execution. One daemon. Every AI agent on your machine — audited, judged, governed.

┌─────────────────────────────────────────────────────┐
│                   Your Computer                      │
│                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │  Codex   │ │  Claude  │ │  Cursor  │  ...        │
│  │   CLI    │ │   Code   │ │   IDE    │             │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘            │
│       │             │             │                   │
│  ═════╪═════════════╪═════════════╪══════════════    │
│       │       SOVR DAEMON        │                   │
│       ▼             ▼             ▼                   │
│  ┌──────────────────────────────────────────┐        │
│  │  Agent Detector → File Watcher           │        │
│  │  Shell Hook     → MCP Proxy              │        │
│  │  Policy Engine  → Judgment Engine         │        │
│  │  Audit Logger   → Cloud Connector         │        │
│  └──────────────────────────────────────────┘        │
│                      │                                │
│  ════════════════════╪════════════════════════════    │
│                      ▼                                │
│              ┌──────────────┐                         │
│              │  SOVR Cloud  │  Billing & Compliance   │
│              └──────────────┘                         │
└─────────────────────────────────────────────────────┘

Installation

Option A — Global Install (Recommended)

Global install registers the sovr command in your PATH so you can use it directly:

npm i -g sovr-ai

After global install, all commands work directly:

sovr init                              # Initialize SOVR
sovr start                             # Start the daemon
sovr check delete_file /etc/passwd     # Gate check
sovr status                            # Daemon status
sovr setup claude-code                 # Hook into Claude Code

Option B — Local Install + npx

If you prefer not to install globally, use npx to run commands:

npm i sovr-ai

Then prefix all commands with npx:

npx sovr init
npx sovr start
npx sovr check delete_file /etc/passwd
npx sovr status
npx sovr setup claude-code

Option C — One-shot with npx (No Install)

Run SOVR without installing at all:

npx sovr-ai                           # Shows banner + onboarding guide
npx sovr-ai init                      # Initialize directly

Note: npx sovr works after local/global install. For one-shot without install, use npx sovr-ai (the full package name).

Quick Start

# Step 1 — Install globally
npm i -g sovr-ai

# Step 2 — See the onboarding guide
sovr
#  ███████╗  ██████╗  ██╗   ██╗ ██████╗
#  ██╔════╝ ██╔═══██╗ ██║   ██║ ██╔══██╗
#  ███████╗ ██║   ██║ ██║   ██║ ██████╔╝
#  ╚════██║ ██║   ██║ ╚██╗ ██╔╝ ██╔══██╗
#  ███████║ ╚██████╔╝  ╚████╔╝  ██║  ██║
#  ╚══════╝  ╚═════╝    ╚═══╝   ╚═╝  ╚═╝
#  🛡️ SOVR v2.2.2 — The Responsibility Layer for AI Agents

# Step 3 — Initialize (creates ~/.sovr/ config, detects agents, installs hooks)
sovr init

# Step 4 — (Optional) Add your API key for cloud features
sovr init --api-key sovr_live_xxx

# Step 5 — Start the daemon
sovr start
# ✅ SOVR daemon running on port 19876
#    Agents detected: 5
#    Policy rules: 7
#    Cloud: connected

# Step 6 — Hook into your AI agent
sovr setup claude-code
sovr setup codex
sovr setup openclaw

# Step 7 — Test gate checks
sovr check delete_file /etc/passwd
# → 🔐 REQUIRE_APPROVAL

sovr check read_file /tmp/test.txt
# → ✅ ALLOW

sovr check execute_command . 'rm -rf /tmp'
# → 🚫 BLOCK

What Gets Installed

SOVR is a single unified package that provides a complete AI governance stack:

| Capability | Description | |:-----------|:------------| | Gate Engine | Policy-based gate checks with 30+ built-in danger patterns | | Agent Detector | Auto-discovers Codex, Claude Code, Cursor, Copilot, Windsurf, Aider, OpenClaw, Manus | | File Watcher | Monitors project directories, attributes changes to responsible AI agents | | Shell Hook | Intercepts shell commands via bash/zsh preexec hooks | | MCP Proxy | Transparent proxy for MCP tool calls with policy filtering | | Audit Chain | HMAC-signed, tamper-proof, chain-linked audit log | | Kill-Switch | Emergency stop with 5-level severity escalation | | Trust Scoring | Quantified trust assessment per agent and per action | | Policy Engine | Flexible rule-based system with custom JSON/YAML policies | | Cloud Billing | API key-based usage tracking with quota management |

CLI Reference

| Command | Description | |:--------|:------------| | sovr | Show banner + onboarding guide (or quick reference if already initialized) | | sovr init [--api-key KEY] | Interactive onboarding — creates ~/.sovr/ config, detects agents, installs hooks | | sovr start [-f] | Start the daemon (-f for foreground mode) | | sovr stop | Stop the daemon | | sovr status | Show daemon status + detected agents + version info | | sovr check <action> <resource> [detail] | Check if an action is allowed by policy | | sovr agents | List detected AI agents on this machine | | sovr setup <agent> | Hook SOVR into an AI agent (claude-code, codex, cline, openclaw, cursor, windsurf) | | sovr audit [limit] | Show recent audit entries from the chain | | sovr doctor | Run system health diagnostics | | sovr install-hooks | Install shell hooks for bash/zsh | | sovr config [show\|set KEY VALUE] | View or modify configuration | | sovr version | Show current version | | sovr help | Show full command reference |

SDK Usage

import { gateCheck, getDefaultPolicy, SovrDaemon } from 'sovr-ai';

// --- Stateless gate check (no daemon needed) ---
const policy = getDefaultPolicy();
const result = gateCheck(
  { action: 'execute_command', resource: '.', command: 'rm -rf /' },
  policy
);

if (result.verdict === 'BLOCK') {
  console.error(`Blocked: ${result.reason}`);
}

// --- Full daemon with file watcher + MCP proxy ---
const daemon = new SovrDaemon({
  port: 19876,
  watchPaths: ['/home/user/projects'],
  apiKey: 'sovr_live_xxx',
});
await daemon.start();

Sub-path Imports

SOVR exposes 15 sub-system modules for tree-shaking. Import only what you need:

import { ... } from 'sovr-ai/security';        // KillSwitch, Honeypot, Crypto
import { ... } from 'sovr-ai/governance';       // Policy engine, approval workflows
import { ... } from 'sovr-ai/audit-evidence';   // Immutable audit chain, trust bundles
import { ... } from 'sovr-ai/trust';            // Trust score calculation
import { ... } from 'sovr-ai/degradation';      // Circuit breaker, graceful fallback
import { ... } from 'sovr-ai/memory-context';   // Session memory, context assembly
import { ... } from 'sovr-ai/cost-budget';      // Usage metering, budget alerts
import { ... } from 'sovr-ai/identity';         // API key management, tenant isolation
import { ... } from 'sovr-ai/observability';    // Metrics, logging, tracing
import { ... } from 'sovr-ai/queue';            // Async job processing
import { ... } from 'sovr-ai/decision';         // Decision execution engine
import { ... } from 'sovr-ai/compensation';     // Rollback and compensation logic
import { ... } from 'sovr-ai/vectordb';         // Embedding storage helpers
import { ... } from 'sovr-ai/verification';     // Result verification router
import { ... } from 'sovr-ai/exec-proxy';       // Sandboxed command execution

REST API

When the daemon is running (default port 19876):

# Health check
curl http://localhost:19876/health

# Gate check
curl -X POST http://localhost:19876/api/check \
  -H "Content-Type: application/json" \
  -d '{"action":"execute_command","resource":".","command":"rm -rf /"}'

# Status
curl http://localhost:19876/api/status

# Detected agents
curl http://localhost:19876/api/agents

# Audit log
curl http://localhost:19876/api/audit

# Current policy
curl http://localhost:19876/api/policy

Agent Detection

SOVR automatically discovers AI agents running on your machine:

| Agent | Detection Method | |:------|:----------------| | Claude Code | Process scanning + ~/.claude config | | Codex CLI | Process scanning + ~/.codex config | | Cursor | Process scanning + Application Support | | VS Code + Copilot | Process scanning + extension detection | | Windsurf | Process scanning + Codeium config | | Aider | Process scanning + config detection | | Continue.dev | Config directory detection | | OpenClaw | Process scanning | | Manus | Environment variable detection |

Built-in Danger Patterns

The default policy includes 30+ patterns across 5 risk levels:

| Risk Level | Examples | |:-----------|:---------| | Critical | rm -rf /, DROP DATABASE, curl \| bash, fork bombs | | High | chmod 777, iptables -F, write to /etc/passwd | | Medium | npm publish, git push --force, docker rm | | Low | Large file writes, bulk operations | | None | Read operations, status checks |

Configuration

Config file: ~/.sovr/config.json

{
  "port": 19876,
  "apiKey": "sovr_live_xxx",
  "watchPaths": ["/home/user/projects"],
  "excludePatterns": ["**/node_modules/**", "**/.git/**"],
  "mcpProxy": true,
  "mcpProxyPort": 19877,
  "shellHook": true,
  "fileWatcher": true,
  "cloudSync": true,
  "logLevel": "info"
}

Custom Policies

Create ~/.sovr/policy.json:

{
  "name": "my-team-policy",
  "version": "1.0.0",
  "rules": [
    {
      "id": "block-production-db",
      "name": "Block production database access",
      "match": {
        "commands": ["psql.*production", "mysql.*prod"],
        "actions": ["execute_command"]
      },
      "action": "BLOCK",
      "priority": 100,
      "enabled": true
    },
    {
      "id": "approve-npm-publish",
      "name": "Require approval for npm publish",
      "match": {
        "commands": ["npm publish"],
        "actions": ["execute_command"]
      },
      "action": "REQUIRE_APPROVAL",
      "priority": 90,
      "enabled": true
    }
  ]
}

Billing & Quotas

SOVR uses a tiered subscription model. The SUBSCRIPTION_PLANS export provides programmatic access:

import { SUBSCRIPTION_PLANS } from 'sovr-ai';

const starter = SUBSCRIPTION_PLANS.find(p => p.id === 'starter');
console.log(starter.monthlyPrice);                     // 300
console.log(starter.quota.gateChecksPerMonth);          // 50000
console.log(starter.quota.irreversibleAllowedPerMonth); // 1000

| Plan | Price | Gate Checks/mo | Irreversible/mo | Trust Bundles/mo | Audit Retention | |:-----|:------|:--------------|:----------------|:-----------------|:----------------| | Free | $0 | 5,000 | 0 | 0 | 7 days | | Personal | $10/mo | 10,000 | 1,000 | 0 | 30 days | | Starter | $300/mo | 50,000 | 1,000 | 5 | 90 days | | Pro | $2,000/mo | 500,000 | 20,000 | 50 | 90 days | | Enterprise | $15,000/mo | 5,000,000 | 200,000 | 200 | 365 days |

Overage pricing (all paid tiers): $0.40 / 1K gate checks, $8.00 / 1K irreversible actions.

Architecture

SOVR implements a three-layer defense model:

L0 — Pattern Matching: 97 built-in OpenGuard rules scan every request for known dangerous patterns (SQL injection, path traversal, prompt injection, etc.).

L1 — Policy Engine: Configurable rule-based system evaluates actions against custom policies with priority-based matching and 4-tier approval levels (auto / human / escalate / emergency).

L2 — Behavioral Analysis: Trust scoring, anomaly detection, and adaptive thresholds learn from historical patterns to flag suspicious deviations.

Troubleshooting

zsh: command not found: sovr

This means SOVR was installed locally (not globally). Fix with:

# Option 1: Install globally
npm i -g sovr-ai

# Option 2: Use npx prefix
npx sovr start

sovr-shell-hook.sh: parse error near '*'

The shell hook file has a syntax issue. Regenerate it:

sovr install-hooks

Then restart your terminal or run source ~/.zshrc.

Daemon won't start

# Check if another instance is running
sovr status

# Force stop and restart
sovr stop
sovr start -f    # Foreground mode to see errors

API Key missing warnings

SOVR works in offline mode without an API key. To add one:

sovr config set apiKey sovr_live_xxx

Or set the environment variable:

export SOVR_API_KEY='sovr_live_xxx'

Related Packages

| Package | Description | |:--------|:------------| | sovr-mcp-proxy | Standalone MCP proxy with OpenGuard scanning | | sovr-ai | This package — the unified responsibility layer |

License

BSL-1.1 — Free for non-production use. Converts to Apache 2.0 on 2030-02-28.

Links

• SOVR Cloud Dashboard
• GitHub
• npm