Core Concepts

Suvra is built on a small set of well-defined primitives. Understand these and every other part of the product — policy authoring, approvals, audit, nodes — is straightforward.

Danger classes

Every action the built-in classifier evaluates lands in one of three danger classes:

The classifier is a floor, not a ceiling

The classifier runs first, with no policy file and no setup. When a policy is also present, both evaluate the action and the more restrictive decision wins. You cannot write a policy rule that re-allows something the classifier calls catastrophic — the classifier is a floor under your policy, not a ceiling you can raise past.

Deterministic guarantees, for both the classifier and policy evaluation:

• No LLM in the decision path.
• No network calls to reach a decision.
• Sub-millisecond evaluation.
• Every decision is explainable — you can see exactly which rule fired and why.

Actions

An action is the unit of work Suvra evaluates: a type, params, and an identity context.

Executable action types (Suvra can run these itself, with rollback capture):

• fs.write_file — supports dry_run, captures a rollback payload, enforces a workspace jail (SUVRA_WORKSPACE_DIR, default workspace/) and max_bytes.
• fs.delete_file — supports dry_run, captures the original file bytes/mode for rollback, enforces the workspace jail and symlink checks.
• http.request — GET only, redirects blocked at the executor (prevents SSRF via redirect), applies allow-domain and timeout constraints.

MCP-wrapped action types — mcp.<tool_name> (e.g. mcp.read_file), generated from the upstream server's tool names when you run suvra mcp wrap. Policies match them with mcp.* for blanket coverage or per-tool ids.

Policy/simulation-only action types — shell.exec, email.delete, secrets.read. These are evaluated by the classifier and policy engine (this is what agent-runtime hooks use) but Suvra never executes them itself; they fail closed at the executor boundary in every mode.

Decisions

Every evaluation produces one of three decisions:

• allow — the action proceeds immediately.
• deny — the action is rejected. No execution, no approval path.
• needs_approval — execution pauses until a human approves or denies. See Human approvals & Slack.

When no rule matches, the decision is always deny. Deny-by-default is a hard guarantee, not a configurable setting.

Enforcement modes

SUVRA_MODE controls runtime behavior:

• strict (default) — full enforcement plus approval gating.
• monitor — policy is evaluated for observability only; actions execute, audit records the would-be decision, no approvals are created.
• disabled — policy evaluation is skipped; audit records decision="disabled".

Executor-level safety (workspace jail, HTTP method/domain enforcement, fail-closed guard-boundary types) applies in all modes, and the simulator always runs strict regardless of SUVRA_MODE.

Identity-aware context

Every action carries identity context that policy rules can match against:

• Request-supplied: agent, user, role, environment, workspace_dir, labels
• Registry-derived (filled from the Agent Registry when agent_id is present): agent_id, risk_tier, approval_profile, runtime_type, owner, purpose, integration

Explicit request values always win field-by-field; registry metadata fills only missing fields. The same context feeds policy matching and approval integrity hashing. See Agents for the full registration schema.

Rollback

Executors capture rollback payloads at execution time: fs.write_file stores the original content (or a delete-on-rollback marker for new files); fs.delete_file stores the deleted file's bytes and mode. Payloads persist to the audit database and survive process restarts — any rollback-capable audit row can be replayed later from the Audit Explorer or the API.

Two runtime roles

Suvra runs as one process locally, and splits into two roles when you scale:

• Control Plane — dashboard, policy administration, approvals, central audit, node registry, policy bundle distribution. suvra serve on your laptop is a control plane with a local SQLite backend.
• Enforcement Node — a lightweight runtime near your agents. It enforces policy locally against a cached last-known-good bundle and forwards approvals and audit events to the control plane.

Nodes fail closed when the control plane is unreachable: validate may proceed from the cached policy, execute may proceed only for cached allow decisions, and approval-gated actions never degrade to a local implicit allow — the node blocks with OFFLINE_APPROVAL_REQUIRED. See Deployment and Nodes.

Audit-first design

Every validate, execute, approval state transition, simulate, and rollback is persisted with its identity context, matched rule and policy, business-readable reasons, per-constraint checks, a structured decision_trace, and the rollback payload when available. Nothing passes through invisibly. See the Audit Explorer.

Where to go next

• Policy Model — write policy files, constraints, precedence, and the simulator
• Human approvals & Slack — the full approval lifecycle
• Agent Runtimes — wire Suvra into your runtime