Microsoft Quicksand: Sandbox your AI agent without Docker or WSL

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. It works on x86_64 and ARM64 across macOS, Linux, and Windows with no root privileges, no Docker, and no system dependencies. Just pip install quick-sandbox

.

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

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

pip install quick-sandbox
quicksand install qemu alpine
python
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)

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

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)

Sandboxes are network-isolated by default. Opt in to internet access and port forwarding with NetworkMode.FULL

.

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

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

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

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

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

Here are all of the Sandbox configuration options:

Sandbox(
    image="ubuntu",
    memory="2G",
    cpus=4,
    mounts=[Mount("/host", "/guest")],
    network_mode=NetworkMode.FULL,
    port_forwards=[PortForward(host=8080, guest=80)],
    disk_size="10G",
    enable_display=True,
    save="my-save-name",
)

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

QEMU binaries, kernels, qcow2 disksCreating and configuring sandboxes-m

, -smp

, -accel

, machine typesexecute()

, streaming, exit codesKernel boot, agent tokens,hostfwd

Mounts, hot-mounts, getting data in/outCIFS viaguestfwd

, 9p via -fsdev

Checkpoints, reverts, persistent savesqcow2 overlays,savevm

, blockdev-snapshot-sync

Screenshots, keyboard, mouseVNC, GPU, USB tablet, QMP input injectionNetwork modes, port forwardingSLIRP NAT,restrict=on

, guestfwd

What makes it fastio_uring

, IOThreads, TCG vs KVM| Guide | When to use | |---|---| |

Extending the SandboxTestingReleasingFull guides: User Guide | Under the Hood | Contributor Guide