microsoft/quicksand

来源: https://github.com/microsoft/quicksand

Quicksand

PyPI (https://pypi.org/project/quick-sandbox/) 变更日志 (https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md) 文档 (https://microsoft.github.io/quicksand/) 许可证: MIT

Quicksand

Quicksand 是一个异步 Python API，用于启动、控制和快照 QEMU (https://www.qemu.org) 虚拟机，特别专注于为 AI 智能体提供沙箱环境。Quicksand 提供了预构建的 Ubuntu 和 Alpine 发行版 Linux 虚拟机，支持 x86_64 和 ARM64 架构，可运行在 macOS、Linux 和 Windows 上。运行沙箱不需要 root 权限或 Docker；在支持的平台上安装 QEMU 和镜像扩展包即可获得内置运行时。

安装

pip install 'quick-sandbox[qemu,alpine]'

或者安装核心包，再单独添加 QEMU 和镜像：

pip install quick-sandbox
quicksand install qemu alpine

使用

Hello, World!

import asyncio
from quicksand import Sandbox

async def main():
    async with Sandbox(image="ubuntu") as sb:
        result = await sb.execute("echo 'Hello from the sandbox!'")
        print(result.stdout)

asyncio.run(main())

运行命令

result = await sb.execute("apt update && apt install -y python3")
print(result.stdout, result.exit_code)

挂载宿主机目录

可以在启动时或运行时将宿主机目录共享到虚拟机中。

# 启动时挂载
async with Sandbox(
    image="ubuntu",
    mounts=[Mount("./workspace", "/mnt/workspace")],
) as sb:
    ...

# 或在运行中的沙箱上动态挂载
handle = await sb.mount("/tmp/data", "/mnt/data")
await sb.execute("ls /mnt/data")
await sb.unmount(handle)

配置网络

沙箱默认网络隔离。通过 NetworkMode.FULL 选择启用互联网访问和端口转发。

async with Sandbox(
    image="ubuntu",
    network_mode=NetworkMode.FULL,
    port_forwards=[PortForward(host=8080, guest=80)],
) as sb:
    ...

多 Linux 用户

在单个沙箱虚拟机中为多个智能体分配独立的 Linux 用户账户。

async with Sandbox(image="ubuntu") as sb:
    alice = await sb.create_user("alice")
    bob = await sb.create_user("bob")

    await alice.execute("cat > hello.txt", stdin="Hello from Alice!\n")
    await bob.execute("cat > hello.txt", stdin="Hello from Bob!\n")

    for user in (alice, bob):
        result = await user.execute("whoami && pwd && cat hello.txt")
        print(result.stdout)
        await sb.delete_user(user.name)

保存与加载

将虚拟机的磁盘状态保存到目录中。之后可以加载，即使在不同的机器上。

await sb.execute("pip install numpy pandas")
await sb.save("my-env")  # 虚拟机继续运行

# 之后加载
async with Sandbox(image="my-env") as sb:
    await sb.execute("python3 -c 'import numpy; print(numpy.__version__)'")

检查点与回滚

捕获完整的虚拟机状态，出错时可以回滚。

await sb.checkpoint("before-experiment")
await sb.execute("apt install -y something-risky")
await sb.revert("before-experiment")  # 虚拟机回滚到检查点状态

控制桌面

桌面镜像提供完整的 Xfce4 图形环境和浏览器。使用 quicksand install ubuntu-desktop 或 quicksand install alpine-desktop 安装。

async with Sandbox(image="ubuntu-desktop", enable_display=True) as sb:
    await sb.screenshot("screen.png")
    await sb.type_text("hello world")
    await sb.press_key(Key.RET)
    await sb.mouse_move(500, 300)
    await sb.mouse_click("left")

配置

以下是所有 Sandbox 配置选项：

Sandbox(
    # 要启动的镜像或保存名称
    image="ubuntu",
    # 客户机内存（默认："512M"）
    memory="2G",
    # 虚拟 CPU 核心数（默认：1）
    cpus=4,
    # 启动时共享到虚拟机的宿主机目录
    mounts=[Mount("/host", "/guest")],
    # NONE、MOUNTS_ONLY（默认）或 FULL 互联网访问
    network_mode=NetworkMode.FULL,
    # 将宿主机 TCP 端口转发到客户机
    port_forwards=[PortForward(host=8080, guest=80)],
    # 启动时扩展客户机文件系统
    disk_size="10G",
    # 挂载虚拟 GPU、键盘和鼠标，用于截图/输入文字/鼠标控制
    enable_display=True,
    # 停止时自动保存虚拟机状态
    save="my-save-name",
)

可用镜像

大小为 2026 年 9 月 14 日发布的完整镜像包下载大小的近似值，因架构而异。叠加镜像的大小不包含其基础镜像。

从源码构建

git clone https://github.com/microsoft/quicksand.git
cd quicksand
uv sync
uv run uvr build --all-packages

文档

贡献指南

完整指南：用户指南 | 底层原理 | 贡献者指南