# MicroSandbox

[中文文档](README.zh.md)

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:

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

```bash
# Load KVM module (Intel)
sudo modprobe kvm_intel

# Or for AMD
sudo modprobe kvm_amd
```

## Quick Start

1. Copy the example environment file:

    ```bash
    cp .env.example .env
    ```

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

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

3. Build the Docker image:

    ```bash
    docker compose build
    ```

4. Run MicroSandbox:

    ```bash
    docker compose run --rm microsandbox
    ```

## Usage Examples

### Interactive Session

Start an interactive session with MicroSandbox:

```bash
docker compose run --rm microsandbox
```

### Run a Command in Sandbox

Execute a specific command inside the sandbox:

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

### Get Help

View available commands and options:

```bash
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:

```yaml
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

```bash
# 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](https://github.com/zerocore-ai/microsandbox)
- [Zerocore AI](https://zerocore.ai/)
- [KVM Documentation](https://www.linux-kvm.org/)

## License

MicroSandbox is an open-source project by Zerocore AI. Please refer to the [upstream repository](https://github.com/zerocore-ai/microsandbox) for license information.