AI Agent MicroVM Sandbox

October 2, 2025 · View on GitHub

To quote Solomon Hykes:

An AI agent is an LLM wrecking its environment in a loop.

🛡️ The AI Agent Security Crisis You Can't Ignore

Your AI agents are one command away from disaster. Here are three critical risks that traditional "YOLO mode" AI deployment exposes you to:

🚨 Destructive Shell Commands - Bad scripts deleting or corrupting critical files, databases, or entire systems
🕵️ Data Exfiltration Attacks - Malicious actors stealing source code, secrets, or sensitive data from environment variables
🎯 Proxy Attacks - Your infrastructure hijacked for DDoS attacks or to mask the origin of cyber attacks against other targets

This open source MicroVM solution eliminates these risks with hardware-level isolation that traditional containers simply cannot provide.

A production-ready AI agent microVM sandbox system using Cloud Hypervisor and Python, providing hardware-level isolation through MicroVMs while maintaining lightweight resource usage. Supports both Linux and Windows guest operating systems.

🚀 Features

Hardware-Level Isolation: KVM-based MicroVMs for strong security boundaries
Multi-OS Support: Linux (kernel boot) and Windows (UEFI boot) guest VMs
REST API: FastAPI-based management interface with OpenAPI documentation
Guest Communication: Bidirectional host-guest communication via HTTP agents
Snapshot & Restore: Full VM state management for quick provisioning
Network Management: Automated TAP devices, bridging, and port forwarding
Resource Management: CPU, memory quotas and system resource monitoring
Production Ready: Monitoring, scaling, security hardening, and deployment automation

📦 Python SDK

The MicroVM Sandbox includes a lightweight Python SDK for easy integration:

# Install from PyPI
pip install py-microvm

Quick Usage:

from microvm_client import MicroVMClient

async with MicroVMClient("http://localhost:8000") as client:
    # Create and start a VM
    vm = await client.start_vm("my-vm", {"template": "linux-default"})
    
    # Execute commands
    result = await client.exec_command(vm.id, "python --version")
    print(result.output)
    
    # Upload files
    await client.upload_file(vm.id, "script.py", "/tmp/script.py")
    
    # Clean up
    await client.destroy_vm(vm.id)

Package Information:

PyPI: https://pypi.org/project/py-microvm/
Version: 1.0.1
License: MIT
Dependencies: httpx, pydantic

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐
│   Python SDK    │    │   Management CLI │
└─────────┬───────┘    └────────┬─────────┘
          │ REST API             │ REST API
          └─────────┬───────────────────┬────────────
                    │                   │
                    ▼                   ▼
          ┌─────────────────────────────────────────┐
          │       Python REST Server (FastAPI)     │
          │      (Cloud Hypervisor Manager)        │
          └─────────────────┬───────────────────────┘
                            │ HTTP API
                            ▼
          ┌─────────────────────────────────────────┐
          │        Cloud Hypervisor VMM             │
          │         (Multi-OS Support)              │
          └─────────────────┬───────────────────────┘
                            │ KVM/Hardware
          ┌─────────────────┼─────────────────┐
          │                 ▼                 │
          │        ┌─────────────────┐        │
          │        │    /dev/kvm     │        │
          │        └─────────────────┘        │
          │                                   │
    ┌─────┴─────────────┐           ┌─────────────────┴─────┐
    │   Linux MicroVM   │           │   Windows MicroVM     │
    │                   │           │                       │
    │ ┌───────────────┐ │           │ ┌───────────────────┐ │
    │ │ Guest Services│ │           │ │  Guest Services   │ │
    │ │ & Agent       │ │           │ │  & Agent          │ │
    │ └───────────────┘ │           │ └───────────────────┘ │
    │  Secure Sandbox   │           │   Secure Sandbox     │
    └───────────────────┘           └───────────────────────┘

📋 System Requirements

Host System

OS: Ubuntu 20.04+ or RHEL 8+
CPU: 4+ cores with VT-x/AMD-V support
Memory: 8GB+ RAM (32GB recommended)
Storage: 50GB+ SSD (200GB NVMe recommended)
Network: 1Gbps+ interface

Software Dependencies

Python >=3.9
Cloud Hypervisor >=34.0
KVM (kernel 5.4+)
Docker (optional, for containerized deployment)

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox.git
cd codeduet-microvm-ai-agent-sandbox

# Install system dependencies
sudo ./scripts/setup/install-dependencies.sh

# Install Cloud Hypervisor
sudo ./scripts/setup/install-cloud-hypervisor.sh

# Setup networking
sudo ./scripts/setup/setup-networking.sh

# Install Python dependencies
pip install -r requirements.txt

2. Configuration

# Copy default configuration
cp config/config.yaml.example config/config.yaml

# Edit configuration as needed
nano config/config.yaml

3. Start the Service

# Development mode
make dev-server

# Or manually
uvicorn src.api.server:app --host 0.0.0.0 --port 8000 --reload

4. Create Your First VM

# Using the CLI
python -m src.cli vm create --name my-vm --template linux-default

# Using the REST API
curl -X POST http://localhost:8000/api/v1/vms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-vm",
    "template": "linux-default",
    "vcpus": 2,
    "memory_mb": 512
  }'

📚 Documentation

🚀 Getting Started

Quick Start Guide - Get up and running in minutes
Installation & Setup - Complete installation instructions
Your First VM - Create and manage your first VM

📖 User Guides

VM Management Guide - Complete VM lifecycle management
- Creating, starting, stopping VMs
- Command execution and file transfer
- Resource allocation and monitoring
- Windows and Linux VM operations
Troubleshooting Guide - Common issues and solutions
- VM startup problems
- Network connectivity issues
- Performance optimization
- Debug and recovery procedures

🔧 API Reference

Complete API Documentation - Comprehensive REST API reference
- All endpoints with examples
- Authentication and authorization
- Error codes and responses
- WebSocket endpoints
Interactive API Docs: Visit http://localhost:8000/docs when server is running
Alternative Docs: Visit http://localhost:8000/redoc for ReDoc interface

🚀 Deployment Guides

Docker Deployment - Containerized deployment
- Single container setup
- Multi-service docker-compose
- Production configurations
- Monitoring and security
Kubernetes Deployment - Cloud-native deployment
- Complete manifests and Helm charts
- High availability setup
- Auto-scaling configuration
- Monitoring integration
Bare Metal Deployment - Direct server installation
- System optimization
- Performance tuning
- Security hardening
- Maintenance procedures

⚡ How-To Guides

🧪 Testing Documentation

Integration Tests - VM lifecycle and security integration tests
Performance Tests - Boot time, resource usage, and load testing
Load Testing Guide - API load testing framework
Test Validation - Test syntax and import validation

🔍 Advanced Topics

High Availability: See Kubernetes Deployment - High Availability
Auto-scaling: See Kubernetes Deployment - Scaling and Autoscaling
Monitoring Setup: See Docker Deployment - Monitoring
Backup & Recovery: See Bare Metal Deployment - Backup and Recovery

🛠️ Development

Environment Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Setup pre-commit hooks
pre-commit install

# Run in development mode
make dev-server

Testing

# Run core functionality tests (most reliable)
python scripts/testing/run-core-tests.py

# Run all unit tests
pytest tests/unit/ -v

# Run integration tests (requires VM infrastructure)
pytest tests/integration/ -v

# Run performance tests
pytest tests/performance/ -v

# Validate test syntax and imports
python scripts/testing/validate-tests.py

# Run load testing against API
python scripts/testing/load-test.py --users 10 --operations 5

# Run with coverage
pytest --cov=src tests/unit/

Code Quality

# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/

🐳 Deployment

Docker

# Build image
docker build -t microvm-sandbox:latest .

# Run with docker-compose
docker-compose up -d

Kubernetes

# Deploy to Kubernetes
kubectl apply -f scripts/deployment/kubernetes/

Production

# Install as system service
sudo ./scripts/deployment/install-systemd-service.sh
sudo systemctl enable microvm-sandbox
sudo systemctl start microvm-sandbox

📊 Monitoring & Observability

The system includes enterprise-grade monitoring and observability:

Prometheus Metrics: VM performance, resource usage, API metrics
Grafana Dashboards: Pre-built dashboards for system visualization
Health Checks: Built-in health endpoints for load balancers
Structured Logging: JSON logs with correlation IDs
Performance Testing: Load testing and benchmarking tools

# Access monitoring endpoints
http://localhost:9090  # Prometheus metrics
http://localhost:3000  # Grafana dashboards  
http://localhost:8000/health  # Health check
http://localhost:8000/status  # Detailed status
http://localhost:8000/api/v1/system/metrics  # System metrics API

# Performance testing
python scripts/testing/load-test.py --users 50 --operations 10

For complete monitoring setup guides, see:

🔧 Configuration

VM Templates

Create custom VM templates in config/vm-templates/:

# config/vm-templates/my-template.yaml
my_template:
  vcpus: 4
  memory_mb: 2048
  kernel: "images/linux/vmlinux.bin"
  rootfs: "images/linux/rootfs.ext4"
  boot_args: "console=ttyS0 reboot=k panic=1"
  guest_agent:
    enabled: true
    port: 8080

Network Configuration

# config/networks/custom-network.yaml
networking:
  bridge_name: "mybr0"
  subnet: "10.0.0.0/24"
  port_range:
    start: 20000
    end: 30000

🔒 Security & Compliance

Enterprise-grade security with comprehensive compliance support:

VM Isolation: Hardware-level isolation via KVM
Network Security: Separate network namespaces per VM
Input Validation: Comprehensive request validation and sanitization
Authentication & RBAC: JWT-based authentication with role-based access control
Audit Logging: Security events and compliance logging
Security Scanning: Vulnerability scanning and risk assessment
Compliance Frameworks: SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR support