Microsoft 开源 Quicksand：面向 AI 智能体沙箱的异步 Python API

Quicksand 是一个异步 Python API，用于启动、控制和快照 QEMU 虚拟机，特别侧重于沙箱化 AI 智能体。Quicksand 为 Ubuntu 和 Alpine 发行版提供预构建的 Linux 虚拟机，并支持 macOS、Linux 和 Windows 上的 x86_64 和 ARM64。运行沙箱无需 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)

挂载主机目录

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

# At boot
async with Sandbox(
    image="ubuntu",
    mounts=[Mount("./workspace", "/mnt/workspace")],
) as sb:
    ...

# Or dynamically on a running sandbox
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")  # VM keeps running

# Load later
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")  # the VM snaps back to the checkpoint

控制桌面

桌面镜像提供完整的 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 or save name to boot
    image="ubuntu",
    # Guest RAM (default: "512M")
    memory="2G",
    # Virtual CPU cores (default: 1)
    cpus=4,
    # Host directories shared into the VM at boot
    mounts=[Mount("/host", "/guest")],
    # NONE, MOUNTS_ONLY (default), or FULL internet access
    network_mode=NetworkMode.FULL,
    # Forward host TCP ports into the guest
    port_forwards=[PortForward(host=8080, guest=80)],
    # Expand the guest filesystem on boot
    disk_size="10G",
    # Attach virtual GPU, keyboard, and mouse for screenshot/type_text/mouse control
    enable_display=True,
    # Auto-save VM state on stop
    save="my-save-name",
)

可用镜像

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

从源码构建

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

文档

贡献

完整指南：用户指南 | Under the Hood | 贡献者指南