sovr-ai

sovr-ai

The Responsibility Layer for AI Agents
Sovereign gate checks · Immutable audit trails · Trust scoring · Policy engine

"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