From nothing to a recorded verdict.

Quickstart

Cirvix runs as a control plane process. Your agent asks it for a decision before it acts, and the decision is recorded whether the answer is yes or no.

Four steps. Nothing here needs an account.

• Install the control plane and the SDK for your runtime.
• Write one policy file.
• Wrap the call you want governed.
• Read back the audit block it wrote.

Install

The local control plane has no external dependencies. Node 20 or later, or Python 3.9 or later.

# Node
npm install @cirvix_ai/agent-control

# Python
pip install cirvix

# Start the local control plane
npx @cirvix_ai/agent-control runtime

By default the control plane listens on a local Unix domain socket rather than a network port, so a local run adds no network hop and nothing is exposed outside the machine.

For zero-dependency deployment, use the single-binary installer via install.sh (or install.ps1 on Windows) or Homebrew: brew tap cirvix/tap && brew install cirvix. The shell scripts auto-detect your CPU architecture and install the compiled standalone daemon (Go/Rust), with automatic fallback to npm if preferred.

For instant 10-second developer setup in Claude Code, Cursor/VS Code, or Python multi-agent frameworks, see Pre-built Ecosystem Plugins.

Write a first policy

A policy is JSON. Match on the action and the resource, return a verdict, and give a reason that will still make sense in six months.

{
  "name": "deny-dotenv-read",
  "effect": "forbid",
  "actions": ["fs.read"],
  "resources": ["**/.env", "**/.env.*"],
  "reason": "secrets are brokered, not read",
  "remediation": "Request the value as a handle: secrets.get(\"STRIPE_KEY\")"
}

Two behaviours are worth knowing before you write more rules. An explicit deny is terminal — no later rule lifts it. And no match means deny: the absence of a rule is never treated as permission.

Send an execution and verify it

You do not ask for a decision and then act on it — you wrap the tools, and the call cannot leave without being decided. A denial and a hold arrive as exceptions, so there is no verdict to forget to check.

import { guard, CirvixDenied, CirvixHeld, STARTER_RULES } from "@cirvix_ai/agent-control";

const tools = guard.wrap(myTools, {
  agent:       "pr-triage",
  environment: process.env.CIRVIX_ENV ?? "local",
  rules:       STARTER_RULES,
});

try {
  await agent.invoke(input);
} catch (err) {
  if (err instanceof CirvixHeld) {
    console.log(err.approvers);   // ["platform-oncall"] — a person can release this
  } else if (err instanceof CirvixDenied) {
    console.log(err.policy);      // "deny-dotenv-read"
    console.log(err.remediation); // secrets.get("STRIPE_KEY")
    console.log(err.decisionId);  // pass to `cirvix why`
  }
  throw err;
}

Then read the decision back. cirvix why tells you which rule produced the verdict and what the request looked like at the time.

$ npx @cirvix_ai/agent-control why req_8a91

  CIRVIX DECISION ANALYSIS

  Decision     DENY
  Risk         HIGH

  Tool         fs.read
  Target       ./.env
  Matched policy deny-dotenv-read
  Reason       secrets are brokered, not read
  Agent        pr-triage
  When         2026-09-02T14:22:07.481Z
  Run          run_4c07e2

  Decision path
    secret detection
      ↓
    risk classification
      ↓
    policy evaluation
      ↓
    BLOCK

  considered  1 of 3 matched
    → deny        deny-dotenv-read
      permit      allow-workspace-read
      permit      allow-repo-metadata

  cirvix replay run_4c07e2 --diff

If you want to know what today's rules would decide about that same request, use cirvix replay. It re-evaluates and never re-executes, so it cannot repeat the original side effect.

Where to go next

• Claude Code guide — install, connect, first protected decision.
• Cursor guide — the same boundary for Cursor's agent.
• MCP guide — put MCP servers behind the gateway.
• Local agent guide — wrap any Node agent's tools with guard.wrap().
• How rules resolve — verdicts, ordering, and why audit_only never authorizes.
• API reference — the HTTP surface if your runtime is not Node or Python.
• Deployment — Docker Compose, Helm, or bare Node inside your own boundary.