compose-anything/builds/microsandbox/README.md

MicroSandbox

中文文档

MicroSandbox is a KVM-based secure sandbox environment developed by Zerocore AI. It provides isolated, lightweight virtual machines for running untrusted code safely using hardware-level virtualization.

Features

• KVM-Based Virtualization: Leverages hardware virtualization for strong isolation
• Lightweight: Minimal overhead compared to traditional VMs
• Secure: Hardware-level isolation protects the host system
• Fast Startup: Quick VM initialization for rapid testing
• Multi-Architecture: Support for both x86_64 (amd64) and ARM64 (aarch64) platforms

Prerequisites

• Docker and Docker Compose installed
• Hardware virtualization support (KVM):
  • Intel VT-x or AMD-V enabled in BIOS
  • /dev/kvm device available on the host
• Linux host system (KVM is Linux-specific)
• Privileged container access (required for KVM)

Check KVM Support

Before running MicroSandbox, verify that your system supports KVM:

# Check if KVM device exists
ls -l /dev/kvm

# Check CPU virtualization support
grep -E 'vmx|svm' /proc/cpuinfo

If /dev/kvm doesn't exist, ensure virtualization is enabled in your BIOS and the KVM kernel module is loaded:

# Load KVM module (Intel)
sudo modprobe kvm_intel

# Or for AMD
sudo modprobe kvm_amd

Quick Start

1. Copy the example environment file:

   cp .env.example .env
   

2. (Optional) Edit .env to customize resource limits:

   # Adjust CPU and memory as needed
   MICROSANDBOX_CPU_LIMIT=4.00
   MICROSANDBOX_MEMORY_LIMIT=4G
   

3. Build the Docker image:

   docker compose build
   

4. Run MicroSandbox:

   docker compose run --rm microsandbox
   

Usage Examples

Interactive Session

Start an interactive session with MicroSandbox:

docker compose run --rm microsandbox

Run a Command in Sandbox

Execute a specific command inside the sandbox:

docker compose run --rm microsandbox run "echo Hello from sandbox"

Get Help

View available commands and options:

docker compose run --rm microsandbox --help

Configuration

Environment Variables

Variable	Description	Default
MICROSANDBOX_VERSION	MicroSandbox version	latest
DEBIAN_VERSION	Debian base image version	13.2-slim
MICROSANDBOX_AUTO_PULL_IMAGES	Auto pull base images on build	true
MICROSANDBOX_DEV_MODE	Enable dev mode (no API key required)	true
MICROSANDBOX_PORT	Internal container port	5555
MICROSANDBOX_PORT_OVERRIDE	External host port mapping	5555
TZ	Container timezone	UTC
MICROSANDBOX_CPU_LIMIT	Maximum CPU cores	4
MICROSANDBOX_CPU_RESERVATION	Reserved CPU cores	1
MICROSANDBOX_MEMORY_LIMIT	Maximum memory allocation	4G
MICROSANDBOX_MEMORY_RESERVATION	Reserved memory	1G

Volume Mounts

• microsandbox_namespaces: MicroSandbox namespace configurations and VM state
• microsandbox_workspace: Working directory for sandbox operations

Security Considerations

Privileged Mode

MicroSandbox requires privileged: true to access KVM devices. This is necessary for hardware virtualization but grants the container elevated privileges. Consider the following:

• Only run MicroSandbox on trusted systems
• Review the code you plan to execute in the sandbox
• Keep the MicroSandbox image updated with security patches
• Use network isolation if running untrusted code
• In production environments, disable dev mode by setting MICROSANDBOX_DEV_MODE=false

Why Privileged Mode?

MicroSandbox uses KVM (Kernel-based Virtual Machine) to provide hardware-level isolation. Unlike Docker containers, which share the host kernel, MicroSandbox creates true virtual machines with their own kernels. This provides much stronger security boundaries, even though the Docker container itself runs in privileged mode.

The privileged container is only the orchestrator - the actual untrusted code runs inside isolated VMs with hardware-enforced boundaries. This architecture is specifically designed for running untrusted code safely.

KVM Device Access

The container requires access to /dev/kvm for hardware virtualization. This is mapped as:

devices:
  - /dev/kvm:/dev/kvm

Ensure your host system's KVM device has appropriate permissions.

Architecture Support

MicroSandbox supports both major architectures:

• amd64 (x86_64): Intel and AMD processors
• arm64 (aarch64): ARM-based processors (e.g., AWS Graviton, Apple Silicon via Linux VM)

The correct binary is automatically selected during the build process based on your target platform.

Troubleshooting

KVM Not Available

If you see errors about KVM not being available:

1. Verify hardware virtualization is enabled in BIOS
2. Check if KVM kernel module is loaded: lsmod | grep kvm
3. Ensure /dev/kvm exists and has correct permissions
4. Confirm you're running on a Linux host (not WSL2 or macOS)

Permission Denied on /dev/kvm

# Add your user to the kvm group
sudo usermod -aG kvm $USER

# Or run with sudo
sudo docker compose run --rm microsandbox

Performance Issues

If you experience slow performance:

• Increase CPU and memory limits in .env
• Verify KVM acceleration is working: dmesg | grep kvm
• Check host system resource availability

References

• MicroSandbox GitHub Repository
• Zerocore AI
• KVM Documentation

License

MicroSandbox is an open-source project by Zerocore AI. Please refer to the upstream repository for license information.