@sovr/sovr

sovr

The Unified Responsibility Layer for AI Agents — sovereign gate checks, audit trails, and trust scoring.

One package. One daemon. Every AI Agent on your machine — audited, judged, governed.

What It Does

sovr is a local guardian daemon that automatically detects and governs all AI agents running on your computer (Codex, Claude Code, Cursor, VS Code Copilot, Windsurf, Aider, etc.). It intercepts their file operations, shell commands, and MCP tool calls, applies policy-based judgment, and reports everything to the SOVR Cloud for billing and compliance.

┌─────────────────────────────────────────────────────┐
│                   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  │  API Key Billing        │
│              └──────────────┘                         │
└─────────────────────────────────────────────────────┘

Quick Start

# Initialize SOVR in your project
npx @sovr/sovr init

# Start the daemon
npx @sovr/sovr start

# Check if an action is allowed
npx @sovr/sovr check "rm -rf node_modules"

# See detected AI agents
npx @sovr/sovr agents

# View audit log
npx @sovr/sovr audit

# Check daemon status
npx @sovr/sovr status

# Stop the daemon
npx @sovr/sovr stop

Installation

# Install (recommended)
npm i @sovr/sovr --legacy-peer-deps

# Or use npx (no install needed)
npx @sovr/sovr init

Features

1. Agent Auto-Detection

Automatically discovers AI agents running on your machine:

• Claude Code — Process scanning + ~/.claude config detection
• Codex CLI — Process scanning + ~/.codex config detection
• Cursor — Process scanning + Application Support detection
• VS Code + Copilot — Process scanning + extension detection
• Windsurf — Process scanning + Codeium config detection
• Aider — Process scanning + config detection
• Continue.dev — Config directory detection
• OpenClaw — Process scanning
• Manus — Environment variable detection

2. File System Monitoring

Watches project directories for all file operations:

• Create / Modify / Delete / Rename events
• Attributes changes to the responsible AI agent
• Configurable exclude patterns (node_modules, .git, etc.)

3. Shell Command Interception

Intercepts shell commands via bash preexec hooks:

• Detects 30+ dangerous patterns (rm -rf, DROP TABLE, curl|bash, etc.)
• 5-level risk assessment (none → low → medium → high → critical)
• Automatic blocking of critical-risk commands

4. MCP Protocol Proxy

Intercepts MCP tool calls from Claude Desktop, Cursor, Windsurf:

• Transparent proxy between MCP client and server
• Policy-based tool call filtering
• Full audit trail of all MCP interactions

5. Policy Engine

Flexible, rule-based policy system:

• Default policy with 30+ built-in danger patterns
• Custom policies via JSON/YAML files
• Policy merging (local + cloud)
• Priority-based rule matching

6. Audit Chain

HMAC-signed, tamper-proof audit log:

• Every judgment is logged with cryptographic chain
• Chain integrity verification
• Export to JSON/CSV for compliance

7. Cloud Billing

API Key-based usage tracking:

• Per-judgment billing
• Quota management with graceful degradation
• Policy sync from cloud
• Audit upload for compliance dashboards

CLI Commands

Command	Description
npx @sovr/sovr init	Initialize SOVR config in ~/.sovr/
npx @sovr/sovr start	Start the daemon (background)
npx @sovr/sovr stop	Stop the daemon
npx @sovr/sovr status	Show daemon status + detected agents
npx @sovr/sovr check <cmd>	Check if a command/action is allowed
npx @sovr/sovr agents	List detected AI agents
npx @sovr/sovr audit	Show recent audit entries
npx @sovr/sovr install-hooks	Install shell hooks (bash/zsh)

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

SDK Usage

import { SovrDaemon, gateCheck, getDefaultPolicy } from '@sovr/sovr';

// --- 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_sk_xxx',
});
await daemon.start();

Sub-path Imports

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

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

Billing & Quotas

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

import { SUBSCRIPTION_PLANS } from '@sovr/sovr';

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.

Configuration

Config file: ~/.sovr/config.json

{
  "port": 19876,
  "apiKey": "sovr_sk_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
    }
  ]
}

Relationship to Other SOVR Packages

sovr is the unified package that integrates capabilities from:

Package	Role	Still Available
sovr-mcp-proxy	MCP protocol interception	Yes (standalone)
sovr-agent	Policy evaluation engine	Yes (standalone)
sovr-local-agent	System-level monitoring	Yes (standalone)

Use sovr when you want everything. Use individual packages when you only need one capability.

Built-in Danger Patterns (30+)

Category	Examples
File System	rm -rf /, mkfs, dd of=/dev/
Database	DROP TABLE, TRUNCATE, DELETE FROM (no WHERE)
Network	curl | bash, wget | sh, chmod 777
Credentials	echo $SECRET >>, export PASSWORD=
System	kill -9 1, shutdown, reboot
Git	git push --force
Crypto	xmrig, cryptominer
npm	npm publish --access public

License

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

Links

• SOVR Cloud Dashboard
• GitHub
• npm
• Changelog