Apply @appcypher's recommendations for microsandbox Docker configuration

Co-authored-by: Sun-ZhenXing <44517244+Sun-ZhenXing@users.noreply.github.com>
2026-01-15 07:43:19 +00:00
parent 3044032943
commit e263ddf084
5 changed files with 110 additions and 65 deletions
--- a/builds/microsandbox/.env.example
+++ b/builds/microsandbox/.env.example
@@ -2,29 +2,51 @@
 # KVM-based secure sandbox environment

 # Global registry prefix (optional)
-# Leave empty to pull from Docker Hub
+# Leave empty to use ghcr.io/zerocore-ai/microsandbox
 GLOBAL_REGISTRY=

 # MicroSandbox version
-# Default: 0.2.6
-MICROSANDBOX_VERSION=0.2.6
+# Default: latest (recommended to use latest stable version)
+# Set to empty string to always pull the latest version
+MICROSANDBOX_VERSION=latest

-# Auto pull base images on build
+# Debian base image version
+# Default: 13.2-slim
+DEBIAN_VERSION=13.2-slim
+
+# Auto pull base images on build (Python, Node.js SDKs)
 # Default: true
 MICROSANDBOX_AUTO_PULL_IMAGES=true

+# Development mode (disables API key requirements)
+# Default: true (for easier testing)
+# Set to false in production environments
+MICROSANDBOX_DEV_MODE=true
+
 # Timezone
 # Default: UTC
 TZ=UTC

+# ============================================
+# Port Configuration
+# ============================================
+
+# Internal port (inside container)
+# Default: 5555
+MICROSANDBOX_PORT=5555
+
+# External port (host machine)
+# Default: 5555
+MICROSANDBOX_PORT_OVERRIDE=5555
+
 # ============================================
 # Resource Limits
 # ============================================

 # CPU limits
 # MicroSandbox requires more CPU for KVM virtualization
-MICROSANDBOX_CPU_LIMIT=4.00
-MICROSANDBOX_CPU_RESERVATION=1.00
+MICROSANDBOX_CPU_LIMIT=4
+MICROSANDBOX_CPU_RESERVATION=1

 # Memory limits
 # MicroSandbox requires more memory for running VMs
--- a/builds/microsandbox/Dockerfile
+++ b/builds/microsandbox/Dockerfile
@@ -2,7 +2,7 @@ ARG DEBIAN_VERSION=13.2-slim
 FROM debian:${DEBIAN_VERSION}

 ARG DEBIAN_FRONTEND=noninteractive
-ARG MICROSANDBOX_VERSION=0.2.6
+ARG MICROSANDBOX_VERSION
 ARG TARGETARCH

 RUN apt update && \
@@ -12,32 +12,22 @@ RUN apt update && \
    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*
+# Install microsandbox using the official install script
+# This ensures we always get the latest version if MICROSANDBOX_VERSION is not set
+# and handles architecture detection automatically
+RUN VERSION="${MICROSANDBOX_VERSION:-}" \
+    curl -fsSL https://raw.githubusercontent.com/zerocore-ai/microsandbox/refs/heads/main/scripts/install_microsandbox.sh | sh

 # 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)
+# Set up environment variables
 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
+# Set working directory to match docker-compose working_dir
+WORKDIR /workspace

 ARG MICROSANDBOX_AUTO_PULL_IMAGES=true
 RUN if [ "${MICROSANDBOX_AUTO_PULL_IMAGES}" = "true" ]; then \
--- a/builds/microsandbox/README.md
+++ b/builds/microsandbox/README.md
@@ -101,20 +101,23 @@ docker compose run --rm microsandbox --help

 ### 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`    |
+| 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_config`: MicroSandbox configuration and state
+- `microsandbox_namespaces`: MicroSandbox namespace configurations and VM state
 - `microsandbox_workspace`: Working directory for sandbox operations

 ## Security Considerations
@@ -127,6 +130,13 @@ MicroSandbox requires `privileged: true` to access KVM devices. This is necessar
 - 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

--- a/builds/microsandbox/README.zh.md
+++ b/builds/microsandbox/README.zh.md
@@ -101,32 +101,42 @@ 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_VERSION`            | MicroSandbox 版本        | `latest`    |
+| `DEBIAN_VERSION`                  | Debian 基础镜像版本      | `13.2-slim` |
+| `MICROSANDBOX_AUTO_PULL_IMAGES`   | 构建时自动拉取基础镜像   | `true`      |
+| `MICROSANDBOX_DEV_MODE`           | 启用开发模式（无需 API 密钥） | `true`      |
+| `MICROSANDBOX_PORT`               | 容器内部端口             | `5555`      |
+| `MICROSANDBOX_PORT_OVERRIDE`      | 外部主机端口映射         | `5555`      |
+| `TZ`                              | 容器时区                 | `UTC`       |
+| `MICROSANDBOX_CPU_LIMIT`          | CPU 核心数上限           | `4`         |
+| `MICROSANDBOX_CPU_RESERVATION`    | CPU 核心数预留           | `1`         |
+| `MICROSANDBOX_MEMORY_LIMIT`       | 最大内存分配             | `4G`        |
+| `MICROSANDBOX_MEMORY_RESERVATION` | 内存预留                 | `1G`        |

 ### 卷挂载

- `microsandbox_config`：MicroSandbox 配置和状态
+- `microsandbox_namespaces`：MicroSandbox 命名空间配置和虚拟机状态
 - `microsandbox_workspace`：沙箱操作的工作目录

 ## 安全注意事项

 ### 特权模式

-MicroSandbox 需要 `privileged: true` 以访问 KVM 设备。这对于硬件虚拟化是必需的，但会授予容器提升的权限。请考虑以下事项：
+MicroSandbox 需要 `privileged: true` 以访问 KVM 设备。这对于硬件虚拟化是必需的，但会授予容器提升的权限。请考虑以下事项:

 - 仅在受信任的系统上运行 MicroSandbox
 - 审查您计划在沙箱中执行的代码
 - 保持 MicroSandbox 镜像更新以获取安全补丁
 - 如果运行不受信任的代码，请使用网络隔离
+- 在生产环境中，通过设置 `MICROSANDBOX_DEV_MODE=false` 禁用开发模式
+
+**为什么需要特权模式？**
+
+MicroSandbox 使用 KVM（基于内核的虚拟机）来提供硬件级隔离。与共享主机内核的 Docker 容器不同，MicroSandbox 创建具有自己内核的真实虚拟机。这提供了更强的安全边界，即使 Docker 容器本身以特权模式运行。
+
+特权容器只是协调器——实际的不受信任代码在具有硬件强制边界的隔离虚拟机内运行。此架构专门设计用于安全地运行不受信任的代码。

 ### KVM 设备访问

--- a/builds/microsandbox/docker-compose.yaml
+++ b/builds/microsandbox/docker-compose.yaml
@@ -8,7 +8,7 @@ x-defaults: &defaults
    driver: json-file
    options:
      max-size: 100m
-      max-file: 3
+      max-file: "3"

 services:
  microsandbox:
@@ -21,11 +21,14 @@ services:
        - linux/arm64
      args:
        - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim}
-        - MICROSANDBOX_VERSION=${MICROSANDBOX_VERSION:-0.2.6}
+        - MICROSANDBOX_VERSION=${MICROSANDBOX_VERSION:-}
        - MICROSANDBOX_AUTO_PULL_IMAGES=${MICROSANDBOX_AUTO_PULL_IMAGES:-true}
-    image: ${GLOBAL_REGISTRY:-}alexsuntop/microsandbox:${MICROSANDBOX_VERSION:-0.2.6}
+    image: ${GLOBAL_REGISTRY:-ghcr.io/zerocore-ai/}microsandbox:${MICROSANDBOX_VERSION:-latest}
    ports:
-      - ${MICROSANDBOX_PORT_OVERRIDE:-5555}:${MICROSANDBOX_PORT:-5555}
+      - "${MICROSANDBOX_PORT_OVERRIDE:-5555}:${MICROSANDBOX_PORT:-5555}"
+    # Privileged mode and relaxed security profiles are required for KVM access
+    # This provides hardware-level isolation inside the container
+    # See README.md for security considerations
    privileged: true
    security_opt:
      - apparmor=unconfined
@@ -34,31 +37,41 @@ services:
      - TZ=${TZ:-UTC}
      - MICROSANDBOX_HOME=/root/.microsandbox
    volumes:
-      - microsandbox_config:/root/.microsandbox/namespaces
+      # Store namespace configurations and VM state
+      - microsandbox_namespaces:/root/.microsandbox/namespaces
+      # Working directory for sandbox operations
      - microsandbox_workspace:/workspace
    devices:
+      # KVM device for hardware-accelerated virtualization
      - /dev/kvm:/dev/kvm
+      # TUN device for network tunneling (TAP/TUN interfaces)
      - /dev/net/tun:/dev/net/tun
    command:
-      [
-        "server",
-        "start",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        "${MICROSANDBOX_PORT:-5555}",
-        "--dev",
-      ]
+      - /bin/sh
+      - -c
+      - >
+        if [ "$${MICROSANDBOX_DEV_MODE:-true}" = "true" ]; then
+          DEV_FLAG="--dev";
+        else
+          DEV_FLAG="";
+        fi;
+        exec server start --host 0.0.0.0 --port $${MICROSANDBOX_PORT:-5555} $${DEV_FLAG};
    working_dir: /workspace
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:${MICROSANDBOX_PORT:-5555}/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
    deploy:
      resources:
        limits:
-          cpus: ${MICROSANDBOX_CPU_LIMIT:-4.00}
+          cpus: ${MICROSANDBOX_CPU_LIMIT:-4}
          memory: ${MICROSANDBOX_MEMORY_LIMIT:-4G}
        reservations:
-          cpus: ${MICROSANDBOX_CPU_RESERVATION:-1.00}
+          cpus: ${MICROSANDBOX_CPU_RESERVATION:-1}
          memory: ${MICROSANDBOX_MEMORY_RESERVATION:-1G}

 volumes:
-  microsandbox_config:
+  microsandbox_namespaces:
  microsandbox_workspace: