quicksand README

The project's README from github.com/microsoft/quicksand. As one markdown file: README.md.

Quicksand

PyPI Changelog Docs License: MIT

Quicksand

Quicksand is an async Python API to launch, control, and snapshot QEMU virtual machines with a particular focus on sandboxing AI agents. Quicksand provides pre-built Linux VMs for Ubuntu and Alpine distros and supports x86_64 and ARM64 across macOS, Linux, and Windows. Running sandboxes needs no root privileges or Docker; install the QEMU and image extras for a bundled runtime on supported platforms.

Installation

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

Or install the core package and add QEMU/images separately:

pip install quick-sandbox
quicksand install qemu alpine

Usage

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())

Run commands

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

Mount host directories

Share host directories into the VM at boot or on the fly.

# 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)

Configure networking

Sandboxes are network-isolated by default. Opt in to internet access with NetworkMode.FULL. Port forwards work in either direction: Forward(Host(...), Guest(...)) exposes a guest port on the host, and Forward(Guest(...), Host(...)) exposes a host service inside the guest, even when the sandbox is otherwise offline.

async with Sandbox(
    image="ubuntu",
    network_mode=NetworkMode.FULL,
    port_forwards=[
        Forward(Host(8080), Guest(80)),    # host:8080 -> guest:80
        Forward(Guest(3128), Host(8080)),  # guest 10.0.2.101:3128 -> host:8080
    ],
) as sb:
    ...

Multiple Linux users

Give multiple agents independent Linux user accounts in a single sandbox VM.

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)

Save and load

Save the VM's disk state to a directory. Load it later, even on a different machine.

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__)'")

Checkpoint and revert

Capture the full VM state and roll back if something goes wrong.

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

Control a desktop

Desktop images provide a full Xfce4 graphical environment with a browser. Install one with quicksand install ubuntu-desktop or 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")

Configuration

Here are all of the Sandbox configuration options:

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 TCP ports in either direction (host -> guest, guest -> host)
    port_forwards=[Forward(Host(8080), Guest(80)), Forward(Guest(3128), Host(8080))],
    # 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",
)

Available images

Image Type Wheel size Install command What is it
ubuntu Base ~309-357 MB quicksand install ubuntu Ubuntu 24.04 headless
alpine Base ~82-85 MB quicksand install alpine Alpine 3.23 headless (faster boot)
ubuntu-desktop Overlay (ubuntu) ~273-281 MB quicksand install ubuntu-desktop Ubuntu 24.04 + Xfce4 + Firefox
alpine-desktop Overlay (alpine) ~346-363 MB quicksand install alpine-desktop Alpine 3.23 + Xfce4 + Chromium
quicksand-agent Overlay (ubuntu) ~306-335 MB quicksand install quicksand-agent Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown
quicksand-cua Overlay (quicksand-agent) ~489-500 MB quicksand install quicksand-cua Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium

Sizes are approximate full image-wheel downloads for the September 14, 2026 releases and vary by architecture. Overlay sizes exclude their base images.

Building from source

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

Documentation

Topic Guide Under the Hood
Installation Installing packages QEMU binaries, kernels, qcow2 disks
Sandbox Lifecycle Creating and configuring sandboxes -m, -smp, -accel, machine types
Running Commands execute(), streaming, exit codes Kernel boot, agent tokens, hostfwd
File Exchange Mounts, hot-mounts, getting data in/out CIFS via guestfwd, 9p via -fsdev
Save and Rollback Checkpoints, reverts, persistent saves qcow2 overlays, savevm, blockdev-snapshot-sync
Desktop Control Screenshots, keyboard, mouse VNC, GPU, USB tablet, QMP input injection
Network and Isolation Network modes, port forwarding SLIRP NAT, restrict=on, guestfwd
Performance What makes it fast io_uring, IOThreads, TCG vs KVM

Contributing

Guide When to use
Creating Images Build a new base or overlay image package
Extending the Sandbox Add a method, OS, architecture, or QEMU flag
Testing Run or write tests
Releasing Cut a release

Full guides: User Guide | Under the Hood | Contributor Guide

quicksand (microsoft/quicksand)

Searching Database…

246 ·GitHub
Quicksand
Что это такое?Quicksand — это асинхронная Python-библиотека для запуска, управления и создания снимков виртуальных машин QEMU, созданная специально для песочниц ИИ-агентов.
Это отдельное приложение или библиотека, которую я подключаю в свой код?Это Python-библиотека/API, которую вы устанавливаете в свой проект и управляете ею из кода, а не отдельное приложение.
Как его запустить?Установите основной пакет, затем добавьте extras для QEMU и образов, чтобы получить готовую среду исполнения (или поставьте их отдельно). Образы виртуальных машин (например, Ubuntu или Alpine) скачиваются командами вроде `quicksand install ubuntu`.
Нужны ли Docker или права root, чтобы запускать песочницы?Нет, для запуска песочниц не нужны ни права root, ни Docker — виртуализацию берёт на себя входящий в комплект рантайм QEMU.
Есть ли у песочниц доступ в интернет по умолчанию?Нет, по умолчанию песочницы изолированы от сети; доступ нужно явно включить через NetworkMode.FULL, а для более тонкого контроля есть направленный проброс портов.
Это работает только на Linux или ещё и на macOS и Windows?Поддерживаются архитектуры x86_64 и ARM64 на macOS, Linux и Windows.
Может ли агент управлять полноценным графическим рабочим столом внутри песочницы?Да. Образы с рабочим столом, например ubuntu-desktop и alpine-desktop, дают полную среду Xfce4 с браузером (Firefox или Chromium); управлять можно через VNC, снимки экрана и ввод через QMP.
Можно ли сохранять и восстанавливать состояние песочницы?Да: можно сохранить состояние диска виртуальной машины в каталог и позже загрузить его даже на другой машине, а кроме того, отдельно делать контрольные точки полного состояния ВМ и откатываться к ним, если что-то пошло не так.
Для чего нужен образ quicksand-cua?Это надстройка над образом агента, которая добавляет Xvfb, x11vnc, noVNC, Playwright и Chromium; она предназначена для computer-use агентов, которым нужно управлять браузером или рабочим столом.
Могут ли несколько агентов безопасно делить одну песочницу?Да, quicksand позволяет выдать нескольким агентам независимые учётные записи пользователей Linux внутри одной виртуальной машины-песочницы.
What are similar projects?nvx, smolvm, CubeSandbox, agentbox, coop, macos, UTM, webvm
Which topics is it in?hypervisor, agent-sandbox, vm, sandboxing, virtual-machine, computer-use, emulator, arm64, virtualization, python-library, playwright, sandbox
Creator
microsoft
Size
6.6 MB
Stars
246
Updated
CommitOct 17Releasequick-sandbox/v0.13.0Oct 14
Age
6mo
Commits · 90 Days