feat: add microsandbox

2026-01-03 17:10:41 +08:00
parent 25c618aa2e
commit 5b5ffed819
9 changed files with 551 additions and 2 deletions
--- a/builds/microsandbox/.env.example
+++ b/builds/microsandbox/.env.example
@@ -0,0 +1,32 @@
+# MicroSandbox Configuration
+# KVM-based secure sandbox environment
+
+# Global registry prefix (optional)
+# Leave empty to pull from Docker Hub
+GLOBAL_REGISTRY=
+
+# MicroSandbox version
+# Default: 0.2.6
+MICROSANDBOX_VERSION=0.2.6
+
+# Auto pull base images on build
+# Default: true
+MICROSANDBOX_AUTO_PULL_IMAGES=true
+
+# Timezone
+# Default: UTC
+TZ=UTC
+
+# ============================================
+# Resource Limits
+# ============================================
+
+# CPU limits
+# MicroSandbox requires more CPU for KVM virtualization
+MICROSANDBOX_CPU_LIMIT=4.00
+MICROSANDBOX_CPU_RESERVATION=1.00
+
+# Memory limits
+# MicroSandbox requires more memory for running VMs
+MICROSANDBOX_MEMORY_LIMIT=4G
+MICROSANDBOX_MEMORY_RESERVATION=1G
--- a/builds/microsandbox/Dockerfile
+++ b/builds/microsandbox/Dockerfile
@@ -0,0 +1,52 @@
+ARG DEBIAN_VERSION=13.2-slim
+FROM debian:${DEBIAN_VERSION}
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG MICROSANDBOX_VERSION=0.2.6
+ARG TARGETARCH
+
+RUN apt update && \
+    apt install -y --no-install-recommends \
+    ca-certificates \
+    curl && \
+    apt clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Download and install microsandbox binary based on architecture
+RUN ARCH=${TARGETARCH:-amd64} && \
+    case "${ARCH}" in \
+        amd64) MICROSANDBOX_ARCH="x86_64" ;; \
+        arm64) MICROSANDBOX_ARCH="aarch64" ;; \
+        *) echo "Unsupported architecture: ${ARCH}" && exit 1 ;; \
+    esac && \
+    curl -fsSL "https://github.com/zerocore-ai/microsandbox/releases/download/microsandbox-v${MICROSANDBOX_VERSION}/microsandbox-${MICROSANDBOX_VERSION}-linux-${MICROSANDBOX_ARCH}.tar.gz" \
+    -o /tmp/microsandbox.tar.gz && \
+    mkdir -p /usr/local/bin /usr/local/lib && \
+    tar -xzf /tmp/microsandbox.tar.gz -C /tmp && \
+    cd /tmp/microsandbox-${MICROSANDBOX_VERSION}-linux-${MICROSANDBOX_ARCH} && \
+    mv ms* /usr/local/bin/ && \
+    mv *.so.* /usr/local/lib/ && \
+    chmod +x /usr/local/bin/ms* && \
+    rm -rf /tmp/microsandbox*
+
+# Setup directories for root user
+RUN mkdir -p /root/.local/bin /root/.local/lib /root/.microsandbox
+
+# Set up environment variables (based on setup_env.sh)
+ENV PATH="/root/.local/bin:/usr/local/bin:${PATH}"
+ENV LD_LIBRARY_PATH="/root/.local/lib:/usr/local/lib:${LD_LIBRARY_PATH}"
+ENV HOME="/root"
+
+WORKDIR /root
+
+ARG MICROSANDBOX_AUTO_PULL_IMAGES=true
+RUN if [ "${MICROSANDBOX_AUTO_PULL_IMAGES}" = "true" ]; then \
+        msb pull microsandbox/python && \
+        msb pull microsandbox/node; \
+    fi
+
+VOLUME [ "/root/.microsandbox/namespaces" ]
+
+# Default to microsandbox CLI
+ENTRYPOINT ["/usr/local/bin/msb"]
+CMD ["server", "start", "--host", "0.0.0.0", "--port", "5555"]
--- a/builds/microsandbox/README.md
+++ b/builds/microsandbox/README.md
@@ -0,0 +1,188 @@
+# 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.
--- a/builds/microsandbox/README.zh.md
+++ b/builds/microsandbox/README.zh.md
@@ -0,0 +1,188 @@
+# MicroSandbox
+
+[English Documentation](README.md)
+
+MicroSandbox 是由 Zerocore AI 开发的基于 KVM 的安全沙箱环境。它使用硬件级虚拟化技术提供隔离的轻量级虚拟机，用于安全地运行不受信任的代码。
+
+## 特性
+
+- **基于 KVM 的虚拟化**：利用硬件虚拟化实现强隔离
+- **轻量级**：相比传统虚拟机开销更小
+- **安全**：硬件级隔离保护宿主系统
+- **快速启动**：虚拟机初始化快速，便于快速测试
+- **多架构支持**：支持 x86_64（amd64）和 ARM64（aarch64）平台
+
+## 前置要求
+
+- 已安装 Docker 和 Docker Compose
+- 硬件虚拟化支持（KVM）：
+  - 在 BIOS 中启用 Intel VT-x 或 AMD-V
+  - 宿主机上可用 `/dev/kvm` 设备
+- Linux 宿主系统（KVM 是 Linux 特有的）
+- 特权容器访问权限（KVM 需要）
+
+### 检查 KVM 支持
+
+在运行 MicroSandbox 之前，请验证您的系统支持 KVM：
+
+```bash
+# 检查 KVM 设备是否存在
+ls -l /dev/kvm
+
+# 检查 CPU 虚拟化支持
+grep -E 'vmx|svm' /proc/cpuinfo
+```
+
+如果 `/dev/kvm` 不存在，请确保在 BIOS 中启用了虚拟化，并加载了 KVM 内核模块：
+
+```bash
+# 加载 KVM 模块（Intel）
+sudo modprobe kvm_intel
+
+# 或者 AMD
+sudo modprobe kvm_amd
+```
+
+## 快速开始
+
+1. 复制示例环境文件：
+
+    ```bash
+    cp .env.example .env
+    ```
+
+2. （可选）编辑 `.env` 以自定义资源限制：
+
+    ```bash
+    # 根据需要调整 CPU 和内存
+    MICROSANDBOX_CPU_LIMIT=4.00
+    MICROSANDBOX_MEMORY_LIMIT=4G
+    ```
+
+3. 构建 Docker 镜像：
+
+    ```bash
+    docker compose build
+    ```
+
+4. 运行 MicroSandbox：
+
+    ```bash
+    docker compose run --rm microsandbox
+    ```
+
+## 使用示例
+
+### 交互式会话
+
+启动 MicroSandbox 交互式会话：
+
+```bash
+docker compose run --rm microsandbox
+```
+
+### 在沙箱中运行命令
+
+在沙箱内执行特定命令：
+
+```bash
+docker compose run --rm microsandbox run "echo Hello from sandbox"
+```
+
+### 获取帮助
+
+查看可用命令和选项：
+
+```bash
+docker compose run --rm microsandbox --help
+```
+
+## 配置
+
+### 环境变量
+
+| 变量                              | 描述                   | 默认值  |
+| --------------------------------- | ---------------------- | ------- |
+| `MICROSANDBOX_VERSION`            | MicroSandbox 版本      | `0.2.6` |
+| `MICROSANDBOX_AUTO_PULL_IMAGES`   | 构建时自动拉取基础镜像 | `true`  |
+| `MICROSANDBOX_PORT_OVERRIDE`      | MicroSandbox 端口映射  | `5555`  |
+| `TZ`                              | 容器时区               | `UTC`   |
+| `MICROSANDBOX_CPU_LIMIT`          | CPU 核心数上限         | `4.00`  |
+| `MICROSANDBOX_CPU_RESERVATION`    | CPU 核心数预留         | `1.00`  |
+| `MICROSANDBOX_MEMORY_LIMIT`       | 最大内存分配           | `4G`    |
+| `MICROSANDBOX_MEMORY_RESERVATION` | 内存预留               | `1G`    |
+
+### 卷挂载
+
+- `microsandbox_config`：MicroSandbox 配置和状态
+- `microsandbox_workspace`：沙箱操作的工作目录
+
+## 安全注意事项
+
+### 特权模式
+
+MicroSandbox 需要 `privileged: true` 以访问 KVM 设备。这对于硬件虚拟化是必需的，但会授予容器提升的权限。请考虑以下事项：
+
+- 仅在受信任的系统上运行 MicroSandbox
+- 审查您计划在沙箱中执行的代码
+- 保持 MicroSandbox 镜像更新以获取安全补丁
+- 如果运行不受信任的代码，请使用网络隔离
+
+### KVM 设备访问
+
+容器需要访问 `/dev/kvm` 以进行硬件虚拟化。映射方式如下：
+
+```yaml
+devices:
+  - /dev/kvm:/dev/kvm
+```
+
+确保宿主系统的 KVM 设备具有适当的权限。
+
+## 架构支持
+
+MicroSandbox 支持两种主要架构：
+
+- **amd64**（x86_64）：Intel 和 AMD 处理器
+- **arm64**（aarch64）：基于 ARM 的处理器（例如 AWS Graviton、通过 Linux VM 的 Apple Silicon）
+
+在构建过程中会根据目标平台自动选择正确的二进制文件。
+
+## 故障排除
+
+### KVM 不可用
+
+如果您看到关于 KVM 不可用的错误：
+
+1. 验证在 BIOS 中启用了硬件虚拟化
+2. 检查是否加载了 KVM 内核模块：`lsmod | grep kvm`
+3. 确保 `/dev/kvm` 存在并具有正确的权限
+4. 确认您在 Linux 宿主机上运行（而不是 WSL2 或 macOS）
+
+### /dev/kvm 权限被拒绝
+
+```bash
+# 将您的用户添加到 kvm 组
+sudo usermod -aG kvm $USER
+
+# 或使用 sudo 运行
+sudo docker compose run --rm microsandbox
+```
+
+### 性能问题
+
+如果您遇到性能缓慢的问题：
+
+- 在 `.env` 中增加 CPU 和内存限制
+- 验证 KVM 加速是否正常工作：`dmesg | grep kvm`
+- 检查宿主系统资源可用性
+
+## 参考资料
+
+- [MicroSandbox GitHub 仓库](https://github.com/zerocore-ai/microsandbox)
+- [Zerocore AI](https://zerocore.ai/)
+- [KVM 文档](https://www.linux-kvm.org/)
+
+## 许可证
+
+MicroSandbox 是 Zerocore AI 的开源项目。有关许可证信息，请参阅[上游仓库](https://github.com/zerocore-ai/microsandbox)。
--- a/builds/microsandbox/docker-compose.yaml
+++ b/builds/microsandbox/docker-compose.yaml
@@ -0,0 +1,69 @@
+# Docker Compose Configuration for MicroSandbox
+# KVM-based secure sandbox environment
+# https://github.com/zerocore-ai/microsandbox
+
+x-defaults: &defaults
+  restart: unless-stopped
+  logging:
+    driver: json-file
+    options:
+      max-size: 100m
+      max-file: 3
+
+services:
+  microsandbox:
+    <<: *defaults
+    build:
+      context: .
+      dockerfile: Dockerfile
+      platforms:
+        - linux/amd64
+        - linux/arm64
+      args:
+        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim}
+        - MICROSANDBOX_VERSION=${MICROSANDBOX_VERSION:-0.2.6}
+        - MICROSANDBOX_AUTO_PULL_IMAGES=${MICROSANDBOX_AUTO_PULL_IMAGES:-true}
+    image: ${GLOBAL_REGISTRY:-}alexsuntop/microsandbox:${MICROSANDBOX_VERSION:-0.2.6}
+    ports:
+      - ${MICROSANDBOX_PORT_OVERRIDE:-5555}:${MICROSANDBOX_PORT:-5555}
+    privileged: true
+    cap_add:
+      - SYS_ADMIN
+      - NET_ADMIN
+      - SYS_PTRACE
+      - SYS_RESOURCE
+    security_opt:
+      - apparmor=unconfined
+      - seccomp=unconfined
+    environment:
+      - TZ=${TZ:-UTC}
+      - MICROSANDBOX_HOME=/root/.microsandbox
+    volumes:
+      - microsandbox_config:/root/.microsandbox/namespaces
+      - microsandbox_workspace:/workspace
+    devices:
+      - /dev/kvm:/dev/kvm
+      - /dev/net/tun:/dev/net/tun
+    command:
+      [
+        "server",
+        "start",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "${MICROSANDBOX_PORT:-5555}",
+        "--dev",
+      ]
+    working_dir: /workspace
+    deploy:
+      resources:
+        limits:
+          cpus: ${MICROSANDBOX_CPU_LIMIT:-4.00}
+          memory: ${MICROSANDBOX_MEMORY_LIMIT:-4G}
+        reservations:
+          cpus: ${MICROSANDBOX_CPU_RESERVATION:-1.00}
+          memory: ${MICROSANDBOX_MEMORY_RESERVATION:-1G}
+
+volumes:
+  microsandbox_config:
+  microsandbox_workspace: