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)

agent-sandbox
Searching Database…

246 ·GitHub
Quicksand
What is this?Quicksand is an async Python API for launching, controlling, and snapshotting QEMU virtual machines, built specifically for sandboxing AI agents.
Is this a standalone app or a library I import into my code?It's a Python library/API you install into your project and drive programmatically, not a standalone application.
How do I get it running?Install the core package then add the QEMU and image extras for a bundled runtime, or install them separately; VM images (like Ubuntu or Alpine) are pulled with commands such as `quicksand install ubuntu`.
Do I need Docker or root access to run sandboxes?No, running sandboxes needs no root privileges or Docker since the bundled QEMU runtime handles virtualization directly.
Do sandboxes have internet access by default?No, sandboxes are network-isolated by default; you must explicitly opt in with NetworkMode.FULL, and directional port forwarding is available for more controlled access.
Does this only work on Linux, or also macOS and Windows?It supports both x86_64 and ARM64 architectures across macOS, Linux, and Windows.
Can an agent control a full desktop GUI inside the sandbox?Yes. Desktop images like ubuntu-desktop and alpine-desktop provide a full Xfce4 environment with a browser (Firefox or Chromium), controllable via VNC, screenshots, and QMP input injection.
Can I save and restore a sandbox's state?Yes, you can save the VM's disk state to a directory and load it later even on a different machine, and separately checkpoint/revert the full VM state to roll back if something goes wrong.
What is the quicksand-cua image for?It's an overlay on top of the agent image that adds Xvfb, x11vnc, noVNC, Playwright, and Chromium, aimed at computer-use agents that need to drive a browser or desktop.
Can multiple agents share one sandbox safely?Yes, quicksand lets you give multiple agents independent Linux user accounts inside a single sandbox VM.
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