Skip to content

CodeDuet/codeduet-microvm-ai-agent-sandbox

BranchesTags

Repository files navigation

AI Agent MicroVM Sandbox

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:

🏗️ 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

📖 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

VM Operations

Network Configuration

Performance & Monitoring

Security & Compliance

Troubleshooting

🧪 Testing Documentation

🔍 Advanced Topics

🛠️ 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:

# 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:

Security setup guides:

🚀 Performance

Target performance metrics:

  • VM Boot Time: <3s for Linux, <10s for Windows
  • API Response: <100ms for management operations
  • Concurrent VMs: 50+ VMs per host
  • Resource Overhead: <5% host CPU and memory usage

📝 Use Cases

  • Secure Code Execution: Isolate untrusted code execution
  • Multi-Tenant Environments: Provide isolated environments for multiple users
  • CI/CD Pipelines: Isolate build and test environments
  • Security Testing: Safe environment for malware analysis
  • Development Environments: Quickly provision development sandboxes
  • Cross-Platform Testing: Test applications on multiple OS environments

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

📞 Support & Help

📖 Documentation & Guides

🔧 Self-Help Resources

💬 Community Support

🚨 Getting Help

When reporting issues, please include:

  1. System Information: OS, hardware specs, Cloud Hypervisor version
  2. Configuration: Relevant config files (redact sensitive data)
  3. Logs: Error logs and debug output
  4. Steps to Reproduce: Clear reproduction steps
  5. Expected vs Actual: What you expected vs what happened

See our Bug Reporting Guide for detailed instructions.

Built with ❤️ for secure, lightweight virtualization.

About

MicroVM AI agent sandbox system using Cloud Hypervisor and Python with support for both Linux and Windows guest operating systems. The system provides hardware-level isolation through MicroVMs while maintaining lightweight resource usage.

Resources

Readme

License

View license
Activity

Stars

8 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1

Languages