AgentSafe - Secure Micro-VM Platform for AI Agents

AgentSafe is a secure sandbox execution platform designed specifically for AI agents and code generation tools. It provides per-request isolation using micro-VMs with capability-based policies, ensuring untrusted code runs safely without compromising your infrastructure.

Why AgentSafe?

AI agents and code generation tools increasingly execute arbitrary code on behalf of users. Traditional containers share the host kernel, making them vulnerable to container escapes and privilege escalation attacks. Virtual machines provide better isolation but are too slow and resource-heavy for short-lived agent tasks.

AgentSafe bridges this gap by using micro-VMs that combine:

• Security: Hardware virtualization with separate kernels per workload
• Speed: Sub-200ms boot times with minimal memory overhead
• Control: Fine-grained capability policies with default-deny semantics
• Observability: Complete audit trails and metrics for compliance

What We've Built

Core Components (Ready to Show)

• QEMU Runtime: Fast KVM-based micro-VM execution with QMP management
• Policy Engine: YAML-based capability policies with validation
• CLI Tool: agent-run command for executing agents with policies
• Go SDK: Programmatic API for integration
• Metrics: Prometheus integration for monitoring VM performance
• VM Configuration: Declarative resource allocation (CPU, memory, storage)

Current Status

Our MVP demonstrates the core concept with working components. You can:

• Run agents in isolated QEMU micro-VMs
• Define and enforce capability policies
• Monitor execution with Prometheus metrics
• Use the Go SDK for programmatic access

Coming Soon

Beta Release Features

• Firecracker Integration: Production-ready micro-VM runtime with jailer
• VM Supervisor: Request queuing, pooling, and scale-to-zero semantics
• Image Builder: Minimal rootfs creation with metadata and signing
• Secrets Service: Secure metadata injection via vsock
• Deployment Tools: Terraform modules and Kubernetes DaemonSets

Production Features

• Network Control: eBPF-based egress filtering and DNS interception
• Security Hardening: Advanced seccomp profiles and isolation
• Evidence Bundles: Cryptographically signed audit trails
• Performance Optimization: Warm pools and copy-on-write snapshots
• Comprehensive Testing: Integration and performance test suites

Quick Start

Prerequisites

• Linux host with KVM support
• Go 1.21+
• QEMU installed

Installation

# Clone the repository
git clone https://github.com/your-org/agentsafe
cd agentsafe

# Build the CLI
go build -o bin/agent-run ./cmd/agent-run

# Install QEMU (Ubuntu/Debian)
sudo apt-get install qemu-kvm qemu-utils

# Install QEMU (macOS)
brew install qemu

Basic Usage

1. Create a simple policy (examples/policies/development.yaml):

metadata:
  name: "development-policy"
  version: "1.0"

resources:
  cpu_limit: 1
  memory_limit: "512Mi"
  timeout: "5m"

network:
  allow_egress: true
  allowed_domains:
    - "httpbin.org"
    - "api.github.com"

filesystem:
  writable_paths:
    - "/tmp"

2. Run an agent:

# Execute a simple command
./bin/agent-run --policy examples/policies/development.yaml \
  --cmd "curl -s https://httpbin.org/json"

# Run with environment variables
./bin/agent-run --policy examples/policies/development.yaml \
  --env "API_KEY=your-key" \
  --cmd "python3 /app/agent.py"

3. Monitor with metrics:

# Start the metrics demo
cd examples/metrics-demo
go run main.go

# View Grafana dashboard at http://localhost:3000

Using the Go SDK

package main

import (
    "context"
    "fmt"
    "github.com/your-org/agentsafe/sdk/go"
)

func main() {
    client := agentsafe.NewClient("localhost:8080")
    
    result, err := client.Execute(context.Background(), &agentsafe.ExecuteRequest{
        Policy: "examples/policies/development.yaml",
        Command: []string{"python3", "/app/agent.py"},
        Environment: map[string]string{
            "API_KEY": "your-secret-key",
        },
    })
    
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Exit Code: %d\n", result.ExitCode)
    fmt.Printf("Output: %s\n", result.Stdout)
}

Documentation

Examples and Demos

• Agent Run Demo - Basic CLI usage examples
• Multi-Agent Demo - Concurrent agent execution
• Metrics Demo - Prometheus monitoring setup
• QEMU Development - Local development with QEMU
• Configuration Examples - Policy configuration samples

SDK and Tools

• Go SDK - Go client library documentation
• Scripts - Setup and utility scripts
• QEMU VMM - Virtual machine manager documentation

Security

AgentSafe is designed with security-first principles:

• Each execution runs in a separate micro-VM with its own kernel
• Default-deny policies require explicit capability grants
• Network egress is controlled and auditable
• Resource limits prevent denial-of-service attacks
• All executions generate signed audit trails

For security issues, please contact sarthakdeshwal@duck.com

License

Apache 2.0 - see LICENSE file for details.

Support

• GitHub Issues: Report bugs and request features
• Documentation: Comprehensive guides in /examples