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

Copy the example environment file:
```
cp .env.example .env
```

(Optional) Edit .env to customize resource limits:

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

Build the Docker image:
```
docker compose build
```
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	`0.2.6`
`MICROSANDBOX_AUTO_PULL_IMAGES`	Auto pull base images on build	`true`
`MICROSANDBOX_PORT_OVERRIDE`	Port mapping for MicroSandbox	`5555`
`TZ`	Container timezone	`UTC`
`MICROSANDBOX_CPU_LIMIT`	Maximum CPU cores	`4.00`
`MICROSANDBOX_CPU_RESERVATION`	Reserved CPU cores	`1.00`
`MICROSANDBOX_MEMORY_LIMIT`	Maximum memory allocation	`4G`
`MICROSANDBOX_MEMORY_RESERVATION`	Reserved memory	`1G`

Volume Mounts

microsandbox_config: MicroSandbox configuration and 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

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:

Verify hardware virtualization is enabled in BIOS
Check if KVM kernel module is loaded: lsmod | grep kvm
Ensure /dev/kvm exists and has correct permissions
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

License

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