{"id":50101823,"url":"https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox","last_synced_at":"2026-06-08T23:01:13.335Z","repository":{"id":317707349,"uuid":"1067560126","full_name":"CodeDuet/codeduet-microvm-ai-agent-sandbox","owner":"CodeDuet","description":"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.","archived":false,"fork":false,"pushed_at":"2025-10-02T15:06:58.000Z","size":479,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-02T15:33:40.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CodeDuet.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T03:22:15.000Z","updated_at":"2025-10-02T15:07:02.000Z","dependencies_parsed_at":"2025-10-02T15:33:46.742Z","dependency_job_id":null,"html_url":"https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox","commit_stats":null,"previous_names":["codeduet/codeduet-microvm-ai-agent-sandbox"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/CodeDuet/codeduet-microvm-ai-agent-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDuet%2Fcodeduet-microvm-ai-agent-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDuet%2Fcodeduet-microvm-ai-agent-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDuet%2Fcodeduet-microvm-ai-agent-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDuet%2Fcodeduet-microvm-ai-agent-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CodeDuet","download_url":"https://codeload.github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CodeDuet%2Fcodeduet-microvm-ai-agent-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34083848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-23T08:00:31.591Z","updated_at":"2026-06-08T23:01:13.322Z","avatar_url":"https://github.com/CodeDuet.png","language":"Python","funding_links":[],"categories":["📦 Sandboxing and Isolation"],"sub_categories":["Anthropic Engineering \u0026 Blog"],"readme":"# AI Agent MicroVM Sandbox\nTo quote Solomon Hykes:\n\u003e An AI agent is an LLM wrecking its environment in a loop.\n\n## 🛡️ The AI Agent Security Crisis You Can't Ignore\n\n**Your AI agents are one command away from disaster.** Here are three critical risks that traditional \"YOLO mode\" AI deployment exposes you to:\n\n🚨 **Destructive Shell Commands** - Bad scripts deleting or corrupting critical files, databases, or entire systems  \n🕵️ **Data Exfiltration Attacks** - Malicious actors stealing source code, secrets, or sensitive data from environment variables  \n🎯 **Proxy Attacks** - Your infrastructure hijacked for DDoS attacks or to mask the origin of cyber attacks against other targets  \n\n**This open source MicroVM solution eliminates these risks with hardware-level isolation that traditional containers simply cannot provide.**\n\nA 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.\n\n## 🚀 Features\n\n- **Hardware-Level Isolation**: KVM-based MicroVMs for strong security boundaries\n- **Multi-OS Support**: Linux (kernel boot) and Windows (UEFI boot) guest VMs\n- **REST API**: FastAPI-based management interface with OpenAPI documentation\n- **Guest Communication**: Bidirectional host-guest communication via HTTP agents\n- **Snapshot \u0026 Restore**: Full VM state management for quick provisioning\n- **Network Management**: Automated TAP devices, bridging, and port forwarding\n- **Resource Management**: CPU, memory quotas and system resource monitoring\n- **Production Ready**: Monitoring, scaling, security hardening, and deployment automation\n\n## 📦 Python SDK\n\nThe MicroVM Sandbox includes a lightweight Python SDK for easy integration:\n\n```bash\n# Install from PyPI\npip install py-microvm\n```\n\n**Quick Usage:**\n```python\nfrom microvm_client import MicroVMClient\n\nasync with MicroVMClient(\"http://localhost:8000\") as client:\n    # Create and start a VM\n    vm = await client.start_vm(\"my-vm\", {\"template\": \"linux-default\"})\n    \n    # Execute commands\n    result = await client.exec_command(vm.id, \"python --version\")\n    print(result.output)\n    \n    # Upload files\n    await client.upload_file(vm.id, \"script.py\", \"/tmp/script.py\")\n    \n    # Clean up\n    await client.destroy_vm(vm.id)\n```\n\n**Package Information:**\n- **PyPI**: https://pypi.org/project/py-microvm/\n- **Version**: 1.0.1\n- **License**: MIT\n- **Dependencies**: httpx, pydantic\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐\n│   Python SDK    │    │   Management CLI │\n└─────────┬───────┘    └────────┬─────────┘\n          │ REST API             │ REST API\n          └─────────┬───────────────────┬────────────\n                    │                   │\n                    ▼                   ▼\n          ┌─────────────────────────────────────────┐\n          │       Python REST Server (FastAPI)     │\n          │      (Cloud Hypervisor Manager)        │\n          └─────────────────┬───────────────────────┘\n                            │ HTTP API\n                            ▼\n          ┌─────────────────────────────────────────┐\n          │        Cloud Hypervisor VMM             │\n          │         (Multi-OS Support)              │\n          └─────────────────┬───────────────────────┘\n                            │ KVM/Hardware\n          ┌─────────────────┼─────────────────┐\n          │                 ▼                 │\n          │        ┌─────────────────┐        │\n          │        │    /dev/kvm     │        │\n          │        └─────────────────┘        │\n          │                                   │\n    ┌─────┴─────────────┐           ┌─────────────────┴─────┐\n    │   Linux MicroVM   │           │   Windows MicroVM     │\n    │                   │           │                       │\n    │ ┌───────────────┐ │           │ ┌───────────────────┐ │\n    │ │ Guest Services│ │           │ │  Guest Services   │ │\n    │ │ \u0026 Agent       │ │           │ │  \u0026 Agent          │ │\n    │ └───────────────┘ │           │ └───────────────────┘ │\n    │  Secure Sandbox   │           │   Secure Sandbox     │\n    └───────────────────┘           └───────────────────────┘\n```\n\n## 📋 System Requirements\n\n### Host System\n- **OS**: Ubuntu 20.04+ or RHEL 8+\n- **CPU**: 4+ cores with VT-x/AMD-V support\n- **Memory**: 8GB+ RAM (32GB recommended)\n- **Storage**: 50GB+ SSD (200GB NVMe recommended)\n- **Network**: 1Gbps+ interface\n\n### Software Dependencies\n- Python \u003e=3.9\n- Cloud Hypervisor \u003e=34.0\n- KVM (kernel 5.4+)\n- Docker (optional, for containerized deployment)\n\n## 🚀 Quick Start\n\n### 1. Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox.git\ncd codeduet-microvm-ai-agent-sandbox\n\n# Install system dependencies\nsudo ./scripts/setup/install-dependencies.sh\n\n# Install Cloud Hypervisor\nsudo ./scripts/setup/install-cloud-hypervisor.sh\n\n# Setup networking\nsudo ./scripts/setup/setup-networking.sh\n\n# Install Python dependencies\npip install -r requirements.txt\n```\n\n### 2. Configuration\n\n```bash\n# Copy default configuration\ncp config/config.yaml.example config/config.yaml\n\n# Edit configuration as needed\nnano config/config.yaml\n```\n\n### 3. Start the Service\n\n```bash\n# Development mode\nmake dev-server\n\n# Or manually\nuvicorn src.api.server:app --host 0.0.0.0 --port 8000 --reload\n```\n\n### 4. Create Your First VM\n\n```bash\n# Using the CLI\npython -m src.cli vm create --name my-vm --template linux-default\n\n# Using the REST API\ncurl -X POST http://localhost:8000/api/v1/vms \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-vm\",\n    \"template\": \"linux-default\",\n    \"vcpus\": 2,\n    \"memory_mb\": 512\n  }'\n```\n\n## 📚 Documentation\n\n### 🚀 Getting Started\n- **[Quick Start Guide](docs/user-guide/quickstart.md)** - Get up and running in minutes\n- **[Installation \u0026 Setup](docs/user-guide/quickstart.md#installation)** - Complete installation instructions\n- **[Your First VM](docs/user-guide/quickstart.md#create-your-first-vm)** - Create and manage your first VM\n\n### 📖 User Guides\n- **[VM Management Guide](docs/user-guide/vm-management.md)** - Complete VM lifecycle management\n  - Creating, starting, stopping VMs\n  - Command execution and file transfer\n  - Resource allocation and monitoring\n  - Windows and Linux VM operations\n- **[Troubleshooting Guide](docs/user-guide/troubleshooting.md)** - Common issues and solutions\n  - VM startup problems\n  - Network connectivity issues\n  - Performance optimization\n  - Debug and recovery procedures\n\n### 🔧 API Reference\n- **[Complete API Documentation](docs/api/reference.md)** - Comprehensive REST API reference\n  - All endpoints with examples\n  - Authentication and authorization\n  - Error codes and responses\n  - WebSocket endpoints\n- **Interactive API Docs**: Visit `http://localhost:8000/docs` when server is running\n- **Alternative Docs**: Visit `http://localhost:8000/redoc` for ReDoc interface\n\n### 🚀 Deployment Guides\n- **[Docker Deployment](docs/deployment/docker.md)** - Containerized deployment\n  - Single container setup\n  - Multi-service docker-compose\n  - Production configurations\n  - Monitoring and security\n- **[Kubernetes Deployment](docs/deployment/kubernetes.md)** - Cloud-native deployment\n  - Complete manifests and Helm charts\n  - High availability setup\n  - Auto-scaling configuration\n  - Monitoring integration\n- **[Bare Metal Deployment](docs/deployment/bare-metal.md)** - Direct server installation\n  - System optimization\n  - Performance tuning\n  - Security hardening\n  - Maintenance procedures\n\n### ⚡ How-To Guides\n\n#### VM Operations\n- **Creating VMs**: See [VM Management - Creating VMs](docs/user-guide/vm-management.md#creating-vms)\n- **Managing Snapshots**: See [VM Management - Snapshot Management](docs/user-guide/vm-management.md#snapshot-management)\n- **File Transfer**: See [VM Management - File Transfer](docs/user-guide/vm-management.md#file-transfer)\n- **Command Execution**: See [VM Management - Command Execution](docs/user-guide/vm-management.md#command-execution)\n\n#### Network Configuration\n- **Basic Networking**: See [VM Management - Network Configuration](docs/user-guide/vm-management.md#network-configuration)\n- **Port Forwarding**: See [VM Management - Port Forwarding](docs/user-guide/vm-management.md#port-forwarding)\n- **Network Isolation**: See [VM Management - Network Isolation](docs/user-guide/vm-management.md#network-isolation)\n\n#### Performance \u0026 Monitoring\n- **Resource Monitoring**: See [VM Management - Resource Management](docs/user-guide/vm-management.md#resource-management)\n- **Performance Tuning**: See [Bare Metal Deployment - Performance Optimization](docs/deployment/bare-metal.md#performance-optimization)\n- **Load Testing**: See [Load Testing Script](scripts/testing/load-test.py)\n\n#### Security \u0026 Compliance\n- **Authentication Setup**: See [API Reference - Authentication](docs/api/reference.md#authentication)\n- **Security Hardening**: See [Bare Metal Deployment - Security Hardening](docs/deployment/bare-metal.md#security-hardening)\n- **Audit Logging**: See [API Reference - Security Management](docs/api/reference.md#security-management)\n\n#### Troubleshooting\n- **VM Won't Start**: See [Troubleshooting - VM Creation Failures](docs/user-guide/troubleshooting.md#vm-creation-failures)\n- **Network Issues**: See [Troubleshooting - Network Connectivity](docs/user-guide/troubleshooting.md#network-connectivity-problems)\n- **Performance Issues**: See [Troubleshooting - Performance Issues](docs/user-guide/troubleshooting.md#performance-issues)\n- **Debug Mode**: See [Troubleshooting - Advanced Diagnostics](docs/user-guide/troubleshooting.md#advanced-diagnostics)\n\n### 🧪 Testing Documentation\n- **[Integration Tests](tests/integration/)** - VM lifecycle and security integration tests\n- **[Performance Tests](tests/performance/)** - Boot time, resource usage, and load testing\n- **[Load Testing Guide](scripts/testing/load-test.py)** - API load testing framework\n- **[Test Validation](scripts/testing/validate-tests.py)** - Test syntax and import validation\n\n### 🔍 Advanced Topics\n- **High Availability**: See [Kubernetes Deployment - High Availability](docs/deployment/kubernetes.md#high-availability-setup)\n- **Auto-scaling**: See [Kubernetes Deployment - Scaling and Autoscaling](docs/deployment/kubernetes.md#scaling-and-autoscaling)\n- **Monitoring Setup**: See [Docker Deployment - Monitoring](docs/deployment/docker.md#monitoring-and-logging)\n- **Backup \u0026 Recovery**: See [Bare Metal Deployment - Backup and Recovery](docs/deployment/bare-metal.md#backup-and-recovery)\n\n## 🛠️ Development\n\n### Environment Setup\n\n```bash\n# Install development dependencies\npip install -r requirements-dev.txt\n\n# Setup pre-commit hooks\npre-commit install\n\n# Run in development mode\nmake dev-server\n```\n\n### Testing\n\n```bash\n# Run core functionality tests (most reliable)\npython scripts/testing/run-core-tests.py\n\n# Run all unit tests\npytest tests/unit/ -v\n\n# Run integration tests (requires VM infrastructure)\npytest tests/integration/ -v\n\n# Run performance tests\npytest tests/performance/ -v\n\n# Validate test syntax and imports\npython scripts/testing/validate-tests.py\n\n# Run load testing against API\npython scripts/testing/load-test.py --users 10 --operations 5\n\n# Run with coverage\npytest --cov=src tests/unit/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/\n\n# Lint code\nflake8 src/\n\n# Type checking\nmypy src/\n```\n\n## 🐳 Deployment\n\n### Docker\n\n```bash\n# Build image\ndocker build -t microvm-sandbox:latest .\n\n# Run with docker-compose\ndocker-compose up -d\n```\n\n### Kubernetes\n\n```bash\n# Deploy to Kubernetes\nkubectl apply -f scripts/deployment/kubernetes/\n```\n\n### Production\n\n```bash\n# Install as system service\nsudo ./scripts/deployment/install-systemd-service.sh\nsudo systemctl enable microvm-sandbox\nsudo systemctl start microvm-sandbox\n```\n\n## 📊 Monitoring \u0026 Observability\n\nThe system includes enterprise-grade monitoring and observability:\n\n- **[Prometheus Metrics](docs/api/reference.md#system-metrics)**: VM performance, resource usage, API metrics\n- **[Grafana Dashboards](docs/deployment/docker.md#monitoring-and-logging)**: Pre-built dashboards for system visualization\n- **[Health Checks](docs/api/reference.md#health-and-status)**: Built-in health endpoints for load balancers\n- **[Structured Logging](docs/deployment/bare-metal.md#monitoring-setup)**: JSON logs with correlation IDs\n- **[Performance Testing](docs/user-guide/troubleshooting.md#performance-issues)**: Load testing and benchmarking tools\n\n```bash\n# Access monitoring endpoints\nhttp://localhost:9090  # Prometheus metrics\nhttp://localhost:3000  # Grafana dashboards  \nhttp://localhost:8000/health  # Health check\nhttp://localhost:8000/status  # Detailed status\nhttp://localhost:8000/api/v1/system/metrics  # System metrics API\n\n# Performance testing\npython scripts/testing/load-test.py --users 50 --operations 10\n```\n\nFor complete monitoring setup guides, see:\n- **[Docker Monitoring Setup](docs/deployment/docker.md#monitoring-and-logging)**\n- **[Kubernetes Monitoring](docs/deployment/kubernetes.md#monitoring-and-observability)**\n- **[Bare Metal Monitoring](docs/deployment/bare-metal.md#monitoring-setup)**\n\n## 🔧 Configuration\n\n### VM Templates\n\nCreate custom VM templates in `config/vm-templates/`:\n\n```yaml\n# config/vm-templates/my-template.yaml\nmy_template:\n  vcpus: 4\n  memory_mb: 2048\n  kernel: \"images/linux/vmlinux.bin\"\n  rootfs: \"images/linux/rootfs.ext4\"\n  boot_args: \"console=ttyS0 reboot=k panic=1\"\n  guest_agent:\n    enabled: true\n    port: 8080\n```\n\n### Network Configuration\n\n```yaml\n# config/networks/custom-network.yaml\nnetworking:\n  bridge_name: \"mybr0\"\n  subnet: \"10.0.0.0/24\"\n  port_range:\n    start: 20000\n    end: 30000\n```\n\n## 🔒 Security \u0026 Compliance\n\nEnterprise-grade security with comprehensive compliance support:\n\n- **[VM Isolation](docs/user-guide/vm-management.md#network-isolation)**: Hardware-level isolation via KVM\n- **[Network Security](docs/api/reference.md#network-management)**: Separate network namespaces per VM\n- **[Input Validation](docs/api/reference.md#error-responses)**: Comprehensive request validation and sanitization\n- **[Authentication \u0026 RBAC](docs/api/reference.md#authentication)**: JWT-based authentication with role-based access control\n- **[Audit Logging](docs/api/reference.md#security-management)**: Security events and compliance logging\n- **[Security Scanning](docs/api/reference.md#security-management)**: Vulnerability scanning and risk assessment\n- **[Compliance Frameworks](docs/user-guide/troubleshooting.md#compliance-logging)**: SOC 2, ISO 27001, HIPAA, PCI DSS, GDPR support\n\nSecurity setup guides:\n- **[Security Hardening](docs/deployment/bare-metal.md#security-hardening)**\n- **[Network Security](docs/deployment/kubernetes.md#security-configuration)**\n- **[Docker Security](docs/deployment/docker.md#security-hardening)**\n\n## 🚀 Performance\n\nTarget performance metrics:\n\n- **VM Boot Time**: \u003c3s for Linux, \u003c10s for Windows\n- **API Response**: \u003c100ms for management operations\n- **Concurrent VMs**: 50+ VMs per host\n- **Resource Overhead**: \u003c5% host CPU and memory usage\n\n## 📝 Use Cases\n\n- **Secure Code Execution**: Isolate untrusted code execution\n- **Multi-Tenant Environments**: Provide isolated environments for multiple users\n- **CI/CD Pipelines**: Isolate build and test environments\n- **Security Testing**: Safe environment for malware analysis\n- **Development Environments**: Quickly provision development sandboxes\n- **Cross-Platform Testing**: Test applications on multiple OS environments\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](docs/development/contributing.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Links\n\n- [Cloud Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor)\n- [FastAPI Documentation](https://fastapi.tiangolo.com/)\n- [KVM Documentation](https://www.linux-kvm.org/)\n\n## 📞 Support \u0026 Help\n\n### 📖 Documentation \u0026 Guides\n- **[Quick Start Guide](docs/user-guide/quickstart.md)** - Get started in minutes\n- **[Troubleshooting Guide](docs/user-guide/troubleshooting.md)** - Common issues and solutions\n- **[Complete API Reference](docs/api/reference.md)** - Full API documentation\n- **[Deployment Guides](docs/deployment/)** - Docker, Kubernetes, and bare metal\n\n### 🔧 Self-Help Resources\n- **[FAQ \u0026 Common Issues](docs/user-guide/troubleshooting.md#common-issues)**\n- **[Performance Tuning](docs/user-guide/troubleshooting.md#performance-issues)**\n- **[Debug Procedures](docs/user-guide/troubleshooting.md#advanced-diagnostics)**\n- **[Recovery Procedures](docs/user-guide/troubleshooting.md#recovery-procedures)**\n\n### 💬 Community Support\n- **Issues**: [GitHub Issues](https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/CodeDuet/codeduet-microvm-ai-agent-sandbox/discussions)\n- **Documentation**: [Complete Documentation](docs/)\n\n### 🚨 Getting Help\nWhen reporting issues, please include:\n1. **System Information**: OS, hardware specs, Cloud Hypervisor version\n2. **Configuration**: Relevant config files (redact sensitive data)\n3. **Logs**: Error logs and debug output\n4. **Steps to Reproduce**: Clear reproduction steps\n5. **Expected vs Actual**: What you expected vs what happened\n\nSee our **[Bug Reporting Guide](docs/user-guide/troubleshooting.md#getting-help)** for detailed instructions.\n\n---\n\nBuilt with ❤️ for secure, lightweight virtualization.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeDuet%2Fcodeduet-microvm-ai-agent-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCodeDuet%2Fcodeduet-microvm-ai-agent-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCodeDuet%2Fcodeduet-microvm-ai-agent-sandbox/lists"}