# Agent Hypervisor β Community Edition
**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.*
[](https://github.com/imran-siddique/agent-hypervisor/stargazers)
[](https://github.com/sponsors/imran-siddique)
[](LICENSE)
[](https://python.org)
[](https://github.com/imran-siddique/agent-hypervisor/actions/workflows/ci.yml)
[](https://pypi.org/project/agent-hypervisor/)
[](https://pypi.org/project/agent-hypervisor/)
[](https://github.com/imran-siddique/agent-governance/blob/master/docs/OWASP-COMPLIANCE.md)
[](https://github.com/imran-siddique/agent-hypervisor)
[](benchmarks/)
[](https://github.com/imran-siddique/agent-hypervisor/discussions)
> β **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](https://pypi.org/project/ai-agent-governance/) | [GitHub](https://github.com/imran-siddique/agent-governance)
[Quick Start](#quick-start) β’ [Configuration](#configuration) β’ [Why a Hypervisor?](#-why-agent-hypervisor) β’ [Features](#key-features) β’ [Architecture](#architecture-diagrams) β’ [Performance](#performance) β’ [Ecosystem](#ecosystem)
---
### Integrated Into Major AI Frameworks
## π By The Numbers
457+Tests Passing |
4Execution Rings
(Ring 0β3) |
268ΞΌsFull Governance
Pipeline Latency |
v2.0Saga Compensation
Kill Switch Β· Rate Limits |
## π‘ Why Agent Hypervisor?
> **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.
### How It Maps to What You Already Know
| 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 |
## Quick Start
```bash
pip install agent-hypervisor
```
```python
from 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)
```
## Configuration
This section covers how to configure agents, sessions, sagas, security, and rate limiting.
### Agent Configuration
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.
```python
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)
```
### Temporary Ring Elevation (Sudo)
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.
```python
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)
```
### Session Configuration
`SessionConfig` controls isolation, participant limits, and consistency:
```python
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 β ARCHIVED
```
### Saga Configuration
Define multi-step transactions with compensation using the DSL parser or programmatically:
```python
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 steps
```
### Kill Switch
The kill switch provides graceful agent termination with saga step handoff:
```python
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 compensated
```
Kill reasons:
- `behavioral_drift` β Agent behavior diverges from expected patterns
- `rate_limit` β Agent exceeded rate limit thresholds
- `ring_breach` β Agent attempted unauthorized ring access
- `manual` β Operator-initiated termination
- `quarantine_timeout` β Quarantine period expired without resolution
- `session_timeout` β Session max duration exceeded
### Rate Limiting
Per-ring token bucket rate limiting is applied automatically:
```python
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)
```
### Ring Breach Detection
The breach detector monitors agents for anomalous access patterns:
```python
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 switch
```
### YAML Configuration
You can define sagas and load them from YAML files:
```yaml
# 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-team
```
```python
import 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)
```
### Docker Compose
For production deployments with Redis-backed state:
```yaml
# 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
```
## Configuration Reference
| 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` |
## Architecture Diagrams
### Execution Ring Hierarchy
```mermaid
graph TD
R0["π΄ Ring 0 β Root
Hypervisor config & penalty
Requires SRE Witness"]
R1["π Ring 1 β Privileged
Non-reversible actions
eff_score > 0.95 + consensus"]
R2["π‘ Ring 2 β Standard
Reversible actions
eff_score > 0.60"]
R3["π’ Ring 3 β Sandbox
Read-only / research
Default for unknown agents"]
R0 -->|"supervises"| R1
R1 -->|"supervises"| R2
R2 -->|"supervises"| R3
```
### Ring Promotion / Demotion Flow
```mermaid
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
```
### Saga Lifecycle
```mermaid
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"]
```
### Joint Liability Vouch Chain
```mermaid
flowchart TD
Sponsor["π‘οΈ Sponsor Agent
eff_score: 0.92
Bonds reputation"]
Sponsored["π€ Sponsored Agent
eff_score: 0.45
Gains Ring 2 access"]
Action["Agent performs action"]
Check{"Intent\nviolation?"}
Safe["β
No penalty"]
Penalty["π» Both penalized
Sponsor collateral slashed
Sponsored demoted"]
Sponsor -->|"vouches for"| Sponsored
Sponsored --> Action
Action --> Check
Check -- No --> Safe
Check -- Yes --> Penalty
Penalty -->|"collateral slash"| Sponsor
Penalty -->|"demotion + quarantine"| Sponsored
```
### Slash Cascade Propagation
```mermaid
flowchart TD
Violation["π¨ Violation Detected"]
Attr["Fault Attribution
Identify responsible agent"]
Primary["Primary Agent
Full penalty applied"]
Sponsor1["Sponsor A
Collateral slashed"]
Sponsor2["Sponsor B
Collateral slashed"]
Quarantine["Quarantine Agent
Before termination"]
Demote["Demote to Ring 3"]
Ledger["Record in
Liability Ledger"]
Violation --> Attr
Attr --> Primary
Primary --> Sponsor1
Primary --> Sponsor2
Primary --> Quarantine
Quarantine --> Demote
Sponsor1 --> Ledger
Sponsor2 --> Ledger
Primary --> Ledger
```
## Key Features
|
### π Execution Rings
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.
|
### π Kill Switch
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.
|
|
### π Saga Compensation
Multi-step transactions with timeout enforcement, retry with backoff, reverse-order compensation, and escalation to liability. Parallel execution with ALL/MAJORITY/ANY policies.
|
### π€ Joint Liability
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.
|
|
### π Hash-Chained Audit
Forensic-grade delta trails β semantic diffs, hash-chained entries, summary commitment at session end. Garbage collection preserves forensic artifacts.
|
### π‘ Observability
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)
### π Execution Rings β Deep Dive
```
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.
### π Saga Orchestrator β Deep Dive
- **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
### π Session Consistency
- **Version counters** β causal consistency for shared VFS state
- **Resource locks** β READ/WRITE/EXCLUSIVE with lock timeout
- **Isolation levels** β SNAPSHOT, READ_COMMITTED, SERIALIZABLE per saga
## Performance
| 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
## Installation
```bash
pip install agent-hypervisor
```
## Modules
| 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** |
## Test Suite
```bash
# Run all tests
pytest tests/ -v
# Run only integration tests
pytest tests/integration/ -v
# Run benchmarks
python benchmarks/bench_hypervisor.py
```
## Cross-Module Integrations
The 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.
### REST API
Full FastAPI REST API with 22 endpoints and interactive Swagger docs:
```bash
pip install agent-hypervisor[api]
uvicorn hypervisor.api.server:app
# Open http://localhost:8000/docs for Swagger UI
```
Endpoints: Sessions, Rings, Sagas, Liability, Events, Health.
### Visualization Dashboard
Interactive Streamlit dashboard with 5 tabs:
```bash
cd examples/dashboard
pip install -r requirements.txt
streamlit run app.py
```
Tabs: Session Overview | Execution Rings | Saga Orchestration | Liability & Trust | Event Stream
## Ecosystem
Agent Hypervisor is part of the **Agent Governance Ecosystem** β four specialized repos that work together:
```mermaid
graph TB
subgraph Ecosystem["Agent Governance Ecosystem"]
OS["π§ Agent OS
Policy Enforcement Kernel"]
Mesh["π Agent Mesh
Cryptographic Trust Network"]
SRE["π Agent SRE
Reliability Platform"]
HV["β‘ Agent Hypervisor
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](https://github.com/imran-siddique/agent-os) | Policy enforcement kernel | 1,500+ tests |
| [Agent Mesh](https://github.com/imran-siddique/agent-mesh) | Cryptographic trust network | 1,400+ tests |
| [Agent SRE](https://github.com/imran-siddique/agent-sre) | SLO, chaos, cost guardrails | 1,070+ tests |
| **Agent Hypervisor** | Session isolation & governance runtime | 457+ tests |
## πΊοΈ Roadmap
| 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 |
---
## Frequently Asked Questions
**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.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
- :bug: [Report a Bug](https://github.com/imran-siddique/agent-hypervisor/issues/new?labels=bug)
- :bulb: [Request a Feature](https://github.com/imran-siddique/agent-hypervisor/issues/new?labels=enhancement)
- :speech_balloon: [Join Discussions](https://github.com/imran-siddique/agent-hypervisor/discussions)
- Look for issues labeled [`good first issue`](https://github.com/imran-siddique/agent-hypervisor/labels/good%20first%20issue) to get started
## License
MIT -- see [LICENSE](LICENSE).
---
**[Agent OS](https://github.com/imran-siddique/agent-os)** | **[AgentMesh](https://github.com/imran-siddique/agent-mesh)** | **[Agent SRE](https://github.com/imran-siddique/agent-sre)** | **[Agent Hypervisor](https://github.com/imran-siddique/agent-hypervisor)**
*Built with :heart: for the AI agent governance community*
If Agent Hypervisor helps your work, please consider giving it a :star: