VMware for AI Agents — runtime isolation, execution rings, and governance for autonomous agents
Just as VMware isolates virtual machines, Agent Hypervisor isolates AI agent sessions
and enforces governance boundaries with a kill switch, blast radius containment, and accountability.
⭐ If this project helps you, please star it! It helps others discover Agent Hypervisor.
📦 Install the full stack:
pip install ai-agent-governance[full]— PyPI | GitHub
Quick Start • Configuration • Why a Hypervisor? • Features • Architecture • Performance • Ecosystem
| Tests Passing | Execution Rings (Ring 0–3) |
Full Governance Pipeline Latency |
Saga Compensation Kill Switch · Rate Limits |
The problem: AI agents run with unlimited resources, no isolation, and no kill switch. A single rogue agent in a shared session can escalate privileges, corrupt state, or cascade failures across your entire system.
Our solution: A hypervisor that enforces execution rings, resource limits, saga compensation, and runtime governance — giving you a kill switch, blast radius containment, and joint liability for agent accountability.
| OS / VM Hypervisor | Agent Hypervisor | Why It Matters |
|---|---|---|
| CPU rings (Ring 0–3) | Execution Rings — privilege levels based on trust score | Graduated access, not binary allow/deny |
| Process isolation | Session isolation — VFS namespacing, DID-bound identity | Rogue agents can't corrupt other sessions |
| Memory protection | Liability protection — bonded reputation, collateral slash | Sponsors have skin in the game |
| System calls | Saga transactions — multi-step ops with automatic rollback | Failed workflows undo themselves |
| Watchdog timer | Kill switch — graceful termination with step handoff | Stop runaway agents without data loss |
| Audit logs | Hash-chained delta trail — tamper-evident forensic trail | Prove exactly what happened |
pip install agent-hypervisorfrom hypervisor import Hypervisor, SessionConfig, ConsistencyMode
hv = Hypervisor()
# Create an isolated session with governance
session = await hv.create_session(
config=SessionConfig(enable_audit=True),
creator_did="did:mesh:admin",
)
# Agent joins — ring assigned automatically by trust score
ring = await hv.join_session(
session.sso.session_id,
"did:mesh:agent-1",
sigma_raw=0.85,
)
# → RING_2_STANDARD (trusted agent)
# Activate and run a governed saga
await hv.activate_session(session.sso.session_id)
saga = session.saga.create_saga(session.sso.session_id)
step = session.saga.add_step(
saga.saga_id, "draft_email", "did:mesh:agent-1",
execute_api="/api/draft", undo_api="/api/undo-draft",
timeout_seconds=30, max_retries=2,
)
result = await session.saga.execute_step(
saga.saga_id, step.step_id, executor=draft_email,
)
# Terminate — returns tamper-evident audit hash
hash_root = await hv.terminate_session(session.sso.session_id)This section covers how to configure agents, sessions, sagas, security, and rate limiting.
Agents join sessions and are assigned an Execution Ring based on their trust score (eff_score). You can control ring assignment, resource limits, and timeouts.
from hypervisor import Hypervisor, SessionConfig, ConsistencyMode, ExecutionRing
# Initialize with optional liability cap and retention policy
hv = Hypervisor(
max_exposure=1000.0, # Max total liability per voucher
retention_policy=None, # Ephemeral GC rules (default: keep all)
)
# Create a session with resource limits
session = await hv.create_session(
config=SessionConfig(
consistency_mode=ConsistencyMode.EVENTUAL, # or STRONG
max_participants=10, # 1–1000
max_duration_seconds=3600, # 1–604,800 (7 days max)
min_eff_score=0.60, # Minimum trust score to join
enable_audit=True, # Hash-chained audit trail
enable_blockchain_commitment=False,
),
creator_did="did:mesh:admin",
)
# Agent joins — ring assigned by trust score
ring = await hv.join_session(
session.sso.session_id,
"did:mesh:agent-1",
sigma_raw=0.85, # Raw trust score [0.0–1.0]
)
# Ring assignment thresholds:
# eff_score > 0.95 + consensus → RING_1_PRIVILEGED
# eff_score > 0.60 → RING_2_STANDARD
# otherwise → RING_3_SANDBOX (default)Agents can request temporary privilege escalation with a TTL:
Note: Ring elevation is available in the Enterprise Edition. Community Edition includes the API surface but returns a denial response. See the architecture for how it works.
from hypervisor import RingElevationManager
elevation_mgr = RingElevationManager()
# Grant temporary Ring 1 access (max 3600s, default 300s)
elevation = elevation_mgr.elevate(
agent_did="did:mesh:agent-1",
session_id=session.sso.session_id,
target_ring=ExecutionRing.RING_1_PRIVILEGED,
ttl_seconds=300, # Auto-expires after 5 minutes
reason="deploy-approval",
attestation="signed-by-sre", # Optional proof
)
# Revoke early if needed
elevation_mgr.revoke(elevation.elevation_id)SessionConfig controls isolation, participant limits, and consistency:
from hypervisor import SessionConfig, ConsistencyMode
config = SessionConfig(
consistency_mode=ConsistencyMode.STRONG, # Requires consensus
max_participants=5,
max_duration_seconds=7200, # 2-hour session
min_eff_score=0.70, # Higher trust threshold
enable_audit=True,
enable_blockchain_commitment=True,
)
session = await hv.create_session(config=config, creator_did="did:mesh:admin")
await hv.activate_session(session.sso.session_id)
# Session lifecycle: CREATED → HANDSHAKING → ACTIVE → TERMINATING → ARCHIVEDDefine multi-step transactions with compensation using the DSL parser or programmatically:
from hypervisor import SagaDSLParser, SagaOrchestrator, FanOutPolicy
# Option 1: Define saga as a dict (or load from YAML)
definition = {
"name": "deploy-pipeline",
"session_id": "ss-a1b2c3d4",
"steps": [
{
"id": "provision",
"action_id": "provision-vm",
"agent": "did:mesh:agent-1",
"execute_api": "/infra/provision",
"undo_api": "/infra/deprovision", # Compensation endpoint
"timeout": 120, # Seconds (default: 300)
"retries": 2, # Retry count (default: 0)
},
{
"id": "deploy",
"action_id": "deploy-app",
"agent": "did:mesh:agent-2",
"execute_api": "/app/deploy",
"undo_api": "/app/undeploy",
"timeout": 60,
},
],
"fan_outs": [
{
"policy": "all_must_succeed", # or majority_must_succeed, any_must_succeed
"branch_step_ids": ["provision", "deploy"],
},
],
}
parser = SagaDSLParser()
errors = parser.validate(definition) # Returns [] if valid
saga_def = parser.parse(definition)
steps = parser.to_saga_steps(saga_def)
# Option 2: Build programmatically
saga = session.saga.create_saga(session.sso.session_id)
step = session.saga.add_step(
saga.saga_id, "draft_email", "did:mesh:agent-1",
execute_api="/api/draft",
undo_api="/api/undo-draft",
timeout_seconds=30,
max_retries=2,
)
result = await session.saga.execute_step(
saga.saga_id, step.step_id, executor=draft_email,
)
# On failure: automatic reverse-order compensation of committed stepsThe kill switch provides graceful agent termination with saga step handoff:
from hypervisor import KillSwitch
kill_switch = KillSwitch()
# Terminate a misbehaving agent
result = kill_switch.kill(
agent_did="did:mesh:rogue-agent",
session_id=session.sso.session_id,
reason="ring_breach", # behavioral_drift | rate_limit | ring_breach | manual
)
# result.handoffs — list of in-flight saga steps handed to substitute agents
# result.compensation_triggered — True if active sagas were compensatedKill reasons:
behavioral_drift— Agent behavior diverges from expected patternsrate_limit— Agent exceeded rate limit thresholdsring_breach— Agent attempted unauthorized ring accessmanual— Operator-initiated terminationquarantine_timeout— Quarantine period expired without resolutionsession_timeout— Session max duration exceeded
Per-ring token bucket rate limiting is applied automatically:
from hypervisor import AgentRateLimiter
from hypervisor.rings import ExecutionRing
limiter = AgentRateLimiter()
# Default per-ring limits (rate tokens/sec, burst capacity):
# Ring 0 (Root): 100.0 rate, 200.0 capacity
# Ring 1 (Privileged): 50.0 rate, 100.0 capacity
# Ring 2 (Standard): 20.0 rate, 40.0 capacity
# Ring 3 (Sandbox): 5.0 rate, 10.0 capacity
# Custom rate limits per ring
from hypervisor.security.rate_limiter import DEFAULT_RING_LIMITS
custom_limits = {
ExecutionRing.RING_0_ROOT: (200.0, 400.0),
ExecutionRing.RING_1_PRIVILEGED: (100.0, 200.0),
ExecutionRing.RING_2_STANDARD: (30.0, 60.0),
ExecutionRing.RING_3_SANDBOX: (2.0, 5.0),
}
limiter = AgentRateLimiter(ring_limits=custom_limits)The breach detector monitors agents for anomalous access patterns:
from hypervisor import RingBreachDetector, BreachSeverity
detector = RingBreachDetector()
# Breach events include:
# severity: NONE | LOW | MEDIUM | HIGH | CRITICAL
# anomaly_score: float — how far the behavior deviates
# actual_rate vs expected_rate — call frequency anomaly
# call_count_window — calls in the detection window
# Breach detection triggers automatic demotion or kill switchYou can define sagas and load them from YAML files:
# saga-deploy.yaml
name: deploy-pipeline
session_id: ss-a1b2c3d4
steps:
- id: provision
action_id: provision-vm
agent: "did:mesh:agent-1"
execute_api: /infra/provision
undo_api: /infra/deprovision
timeout: 120
retries: 2
- id: deploy
action_id: deploy-app
agent: "did:mesh:agent-2"
execute_api: /app/deploy
undo_api: /app/undeploy
timeout: 60
retries: 1
fan_outs:
- policy: all_must_succeed
branch_step_ids:
- provision
- deploy
metadata:
environment: production
owner: platform-teamimport yaml
from hypervisor import SagaDSLParser
with open("saga-deploy.yaml") as f:
definition = yaml.safe_load(f)
parser = SagaDSLParser()
errors = parser.validate(definition)
if not errors:
saga_def = parser.parse(definition)For production deployments with Redis-backed state:
# docker-compose.yml
services:
redis:
image: redis:7-alpine
ports:
- "6379:6379"
hypervisor-api:
build: .
environment:
- REDIS_URL=redis://redis:6379/0
- HYPERVISOR_CONFIG=/app/config/hypervisor.yaml
ports:
- "8000:8000"
volumes:
- ./config:/app/config| Parameter | Type | Default | Description |
|---|---|---|---|
| Hypervisor | |||
max_exposure |
float |
None |
Maximum total liability per voucher |
retention_policy |
RetentionPolicy |
None |
Ephemeral GC rules for audit data |
nexus |
adapter | None |
External trust scoring backend |
policy_check |
adapter | None |
Behavioral verification adapter |
iatp |
adapter | None |
Capability manifest parser |
| SessionConfig | |||
consistency_mode |
ConsistencyMode |
EVENTUAL |
STRONG (consensus) or EVENTUAL (gossip) |
max_participants |
int |
10 |
Max agents per session (1–1,000) |
max_duration_seconds |
int |
3600 |
Session timeout (1–604,800) |
min_eff_score |
float |
0.60 |
Minimum trust score to join (0.0–1.0) |
enable_audit |
bool |
True |
Enable hash-chained audit trail |
enable_blockchain_commitment |
bool |
False |
Commit audit hashes to blockchain |
| Execution Rings | |||
RING_0_ROOT |
int |
0 |
Hypervisor config & penalty (SRE Witness required) |
RING_1_PRIVILEGED |
int |
1 |
Non-reversible actions (eff_score > 0.95 + consensus) |
RING_2_STANDARD |
int |
2 |
Reversible actions (eff_score > 0.60) |
RING_3_SANDBOX |
int |
3 |
Read-only / research (default) |
| Ring Elevation | |||
ttl_seconds |
int |
300 |
Elevation duration (max 3,600s) |
reason |
str |
"" |
Justification for elevation |
attestation |
str |
None |
Signed proof from authorizer |
| Saga Steps | |||
timeout |
int |
300 |
Step timeout in seconds |
retries |
int |
0 |
Max retry attempts |
execute_api |
str |
— | Endpoint for step execution |
undo_api |
str |
None |
Endpoint for compensation |
checkpoint_goal |
str |
None |
Checkpoint description for replay |
| Fan-Out Policy | |||
ALL_MUST_SUCCEED |
— | ✓ | All branches must complete |
MAJORITY_MUST_SUCCEED |
— | — | >50% of branches must complete |
ANY_MUST_SUCCEED |
— | — | At least one branch must complete |
| Rate Limits (tokens/sec, burst) | |||
| Ring 0 (Root) | (float, float) |
(100.0, 200.0) |
Highest throughput for admin ops |
| Ring 1 (Privileged) | (float, float) |
(50.0, 100.0) |
High throughput for trusted agents |
| Ring 2 (Standard) | (float, float) |
(20.0, 40.0) |
Moderate throughput |
| Ring 3 (Sandbox) | (float, float) |
(5.0, 10.0) |
Restricted throughput |
| Kill Switch | |||
reason |
KillReason |
— | behavioral_drift, rate_limit, ring_breach, manual, quarantine_timeout, session_timeout |
| Breach Detection | |||
severity |
BreachSeverity |
— | NONE, LOW, MEDIUM, HIGH, CRITICAL |
graph TD
R0["🔴 Ring 0 — Root<br/>Hypervisor config & penalty<br/>Requires SRE Witness"]
R1["🟠 Ring 1 — Privileged<br/>Non-reversible actions<br/>eff_score > 0.95 + consensus"]
R2["🟡 Ring 2 — Standard<br/>Reversible actions<br/>eff_score > 0.60"]
R3["🟢 Ring 3 — Sandbox<br/>Read-only / research<br/>Default for unknown agents"]
R0 -->|"supervises"| R1
R1 -->|"supervises"| R2
R2 -->|"supervises"| R3
stateDiagram-v2
[*] --> Ring3 : Agent joins session
Ring3 --> Ring2 : eff_score rises above 0.60
Ring2 --> Ring1 : eff_score > 0.95 + consensus
Ring1 --> Ring0 : SRE Witness approval
Ring0 --> Ring1 : Trust drops / TTL expires
Ring1 --> Ring2 : Trust drops below 0.95
Ring2 --> Ring3 : Trust drops below 0.60
Ring3 --> [*] : Terminated / expelled
Ring2 --> Ring1 : Sudo elevation (TTL)
Ring1 --> Ring2 : TTL expires
note right of Ring3 : Ring breach detection\ntriggers immediate demotion
flowchart LR
Create["Create Saga"] --> AddSteps["Add Steps"]
AddSteps --> Execute["Execute Steps"]
Execute --> Success{"All steps\nsucceed?"}
Success -- Yes --> Complete["✅ Saga Complete"]
Success -- No --> Compensate["Compensate\n(reverse order)"]
Compensate --> CompOk{"Compensation\nsucceeds?"}
CompOk -- Yes --> Rolled["↩️ Saga Rolled Back"]
CompOk -- No --> Escalate["⚠️ Escalate\nLiability Penalty"]
flowchart TD
Sponsor["🛡️ Sponsor Agent<br/>eff_score: 0.92<br/>Bonds reputation"]
Sponsored["🤖 Sponsored Agent<br/>eff_score: 0.45<br/>Gains Ring 2 access"]
Action["Agent performs action"]
Check{"Intent\nviolation?"}
Safe["✅ No penalty"]
Penalty["🔻 Both penalized<br/>Sponsor collateral slashed<br/>Sponsored demoted"]
Sponsor -->|"vouches for"| Sponsored
Sponsored --> Action
Action --> Check
Check -- No --> Safe
Check -- Yes --> Penalty
Penalty -->|"collateral slash"| Sponsor
Penalty -->|"demotion + quarantine"| Sponsored
flowchart TD
Violation["🚨 Violation Detected"]
Attr["Fault Attribution<br/>Identify responsible agent"]
Primary["Primary Agent<br/>Full penalty applied"]
Sponsor1["Sponsor A<br/>Collateral slashed"]
Sponsor2["Sponsor B<br/>Collateral slashed"]
Quarantine["Quarantine Agent<br/>Before termination"]
Demote["Demote to Ring 3"]
Ledger["Record in<br/>Liability Ledger"]
Violation --> Attr
Attr --> Primary
Primary --> Sponsor1
Primary --> Sponsor2
Primary --> Quarantine
Quarantine --> Demote
Sponsor1 --> Ledger
Sponsor2 --> Ledger
Primary --> Ledger
|
Hardware-inspired privilege model (Ring 0–3). Agents earn ring access based on trust score. Real-time demotion on trust drops. Sudo elevation with TTL. Breach detection with circuit breakers. |
Graceful termination with saga step handoff to substitute agents. Rate limiting per agent per ring (sandbox: 5 rps, root: 100 rps). Stop runaway agents without data loss. |
|
Multi-step transactions with timeout enforcement, retry with backoff, reverse-order compensation, and escalation to liability. Parallel execution with ALL/MAJORITY/ANY policies. |
High-trust agents sponsor low-trust agents by bonding reputation. If the sponsored agent violates intent, both are penalized. Fault attribution, quarantine-before-terminate, persistent ledger. |
|
Forensic-grade delta trails — semantic diffs, hash-chained entries, summary commitment at session end. Garbage collection preserves forensic artifacts. |
Structured event bus emits typed events for every action. Causal trace IDs with full delegation tree encoding. Version counters for causal consistency. |
📖 Feature details (click to expand)
Ring 0 (Root) — Hypervisor config & penalty — requires SRE Witness
Ring 1 (Privileged) — Non-reversible actions — requires eff_score > 0.95 + consensus
Ring 2 (Standard) — Reversible actions — requires eff_score > 0.60
Ring 3 (Sandbox) — Read-only / research — default for unknown agents
v2.0 additions: Dynamic ring elevation (sudo with TTL), ring breach detection with circuit breakers, ring inheritance for spawned agents.
- Timeout enforcement — steps that hang are automatically cancelled
- Retry with backoff — transient failures retry with exponential delay
- Reverse-order compensation — on failure, all committed steps are undone
- Escalation — if compensation fails, Joint Liability penalty is triggered
- Parallel execution — ALL_MUST_SUCCEED / MAJORITY / ANY policies
- Execution checkpoints — partial replay without re-running completed effects
- Declarative DSL — define sagas via YAML or dict
- Version counters — causal consistency for shared VFS state
- Resource locks — READ/WRITE/EXCLUSIVE with lock timeout
- Isolation levels — SNAPSHOT, READ_COMMITTED, SERIALIZABLE per saga
| Operation | Mean Latency | Throughput |
|---|---|---|
| Ring computation | 0.3μs | 3.75M ops/s |
| Delta audit capture | 27μs | 26K ops/s |
| Session lifecycle | 54μs | 15.7K ops/s |
| 3-step saga | 151μs | 5.3K ops/s |
| Full governance pipeline | 268μs | 2,983 ops/s |
Full pipeline = session create + agent join + 3 audit deltas + saga step + terminate with audit log root
pip install agent-hypervisor| Module | Description | Tests |
|---|---|---|
hypervisor.session |
Shared Session Object lifecycle + VFS | 52 |
hypervisor.rings |
4-ring privilege + elevation + breach detection | 34 |
hypervisor.liability |
Sponsorship, penalty, attribution, quarantine, ledger | 39 |
hypervisor.reversibility |
Execute/Undo API registry | 4 |
hypervisor.saga |
Saga orchestrator + fan-out + checkpoints + DSL | 41 |
hypervisor.audit |
Delta engine, audit log, GC, commitment | 10 |
hypervisor.verification |
DID transaction history verification | 4 |
hypervisor.observability |
Event bus, causal trace IDs | 22 |
hypervisor.security |
Rate limiter, kill switch | 16 |
hypervisor.integrations |
Nexus, Verification, IATP cross-module adapters | -- |
| Integration | End-to-end lifecycle, edge cases, security | 24 |
| Scenarios | Cross-module governance pipelines (7 suites) | 18 |
| Total | 457 |
# Run all tests
pytest tests/ -v
# Run only integration tests
pytest tests/integration/ -v
# Run benchmarks
python benchmarks/bench_hypervisor.pyThe Hypervisor supports optional integration with external trust scoring, behavioral verification, and capability manifest systems via adapters in hypervisor.integrations. See the adapter modules for usage examples.
Full FastAPI REST API with 22 endpoints and interactive Swagger docs:
pip install agent-hypervisor[api]
uvicorn hypervisor.api.server:app
# Open http://localhost:8000/docs for Swagger UIEndpoints: Sessions, Rings, Sagas, Liability, Events, Health.
Interactive Streamlit dashboard with 5 tabs:
cd examples/dashboard
pip install -r requirements.txt
streamlit run app.pyTabs: Session Overview | Execution Rings | Saga Orchestration | Liability & Trust | Event Stream
Agent Hypervisor is part of the Agent Governance Ecosystem — four specialized repos that work together:
graph TB
subgraph Ecosystem["Agent Governance Ecosystem"]
OS["🧠 Agent OS<br/>Policy Enforcement Kernel"]
Mesh["🔗 Agent Mesh<br/>Cryptographic Trust Network"]
SRE["📊 Agent SRE<br/>Reliability Platform"]
HV["⚡ Agent Hypervisor<br/>Runtime Governance"]
OS <-->|"policies"| HV
Mesh <-->|"trust scores"| HV
SRE <-->|"SLOs + chaos"| HV
OS <-->|"identity"| Mesh
end
style HV fill:#ff6b6b,stroke:#333,color:#fff
| Repo | Role | Stars |
|---|---|---|
| Agent OS | Policy enforcement kernel | 1,500+ tests |
| Agent Mesh | Cryptographic trust network | 1,400+ tests |
| Agent SRE | SLO, chaos, cost guardrails | 1,070+ tests |
| Agent Hypervisor | Session isolation & governance runtime | 457+ tests |
| Quarter | Milestone |
|---|---|
| Q1 2026 | ✅ v2.0 — Execution rings, saga orchestration, joint liability, shared sessions |
| Q2 2026 | Distributed hypervisor (multi-node), WebSocket real-time dashboard, Redis-backed sessions |
| Q3 2026 | Kubernetes operator for auto-scaling ring policies, CNCF Sandbox application |
| Q4 2026 | v3.0 — Federated hypervisor mesh, cross-org agent governance, SOC2 attestation |
Why use a hypervisor for AI agents? Just as OS hypervisors isolate virtual machines and enforce resource boundaries, an agent hypervisor isolates AI agent sessions and enforces governance boundaries. Without isolation, a misbehaving agent in a shared session can corrupt state, escalate privileges, or cascade failures across the entire system.
How do Execution Rings differ from traditional access control?
Traditional access control is static and binary (allowed/denied). Execution Rings are dynamic and graduated -- agents earn ring privileges based on their trust score, can request temporary elevation with TTL (like sudo), and are automatically demoted when trust drops. Ring breach detection catches anomalous behavior before damage occurs.
What happens when a multi-agent saga fails? The Saga Orchestrator triggers reverse-order compensation for all committed steps. For parallel execution sagas, the failure policy determines the response: ALL_MUST_SUCCEED compensates if any branch fails, MAJORITY allows minority failures, and ANY succeeds if at least one branch completes. Execution checkpoints enable partial replay without re-running completed effects.
How does fault attribution work? When a saga fails, the hypervisor identifies the agent responsible for the failure and triggers appropriate liability consequences.
We welcome contributions! Please see our Contributing Guide for details.
- 🐛 Report a Bug
- 💡 Request a Feature
- 💬 Join Discussions
- Look for issues labeled
good first issueto get started
MIT -- see LICENSE.
Agent OS | AgentMesh | Agent SRE | Agent Hypervisor
Built with ❤️ for the AI agent governance community
If Agent Hypervisor helps your work, please consider giving it a ⭐