Microsoft Quicksand: Sandbox your AI agent without Docker or WSL

Microsoft has released Quicksand, an async Python API for launching, controlling, and snapshotting QEMU virtual machines designed to sandbox AI agents without requiring Docker, WSL, or root privileges. The tool provides pre-built Linux VMs for Ubuntu and Alpine distros, supports x86_64 and ARM64 across macOS, Linux, and Windows, and can be installed via pip. Quicksand offers features such as network isolation, disk state saving, checkpointing, and desktop images with graphical environments.

Quicksand is an async Python API to launch, control, and snapshot QEMU https://www.qemu.org 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. 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 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 Load later 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 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", | Image | Type | Wheel size | Install command | What is it | |---|---|---|---|---| ubuntu | Base | ~341 MB | quicksand install ubuntu | Ubuntu 24.04 headless | alpine | Base | ~78 MB | quicksand install alpine | Alpine 3.23 headless faster boot | ubuntu-desktop | Overlay ubuntu | ~263 MB | quicksand install ubuntu-desktop | Ubuntu 24.04 + Xfce4 + Firefox | alpine-desktop | Overlay alpine | ~310 MB | quicksand install alpine-desktop | Alpine 3.23 + Xfce4 + Chromium | quicksand-agent | Overlay ubuntu | ~304 MB | quicksand install quicksand-agent | Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown | quicksand-cua | Overlay quicksand-agent | ~445 MB | quicksand install quicksand-cua | Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium | git clone https://github.com/microsoft/quicksand.git cd quicksand uv sync uv run uvr build --all-packages | Topic | Guide | Under the Hood | |---|---|---| | Installation | | QEMU binaries, kernels, qcow2 disks /microsoft/quicksand/blob/main/docs/under-the-hood/01-installation.md Creating and configuring sandboxes /microsoft/quicksand/blob/main/docs/user-guide/02-sandbox-lifecycle.md -m , -smp , -accel , machine types execute , streaming, exit codes Kernel boot, agent tokens, /microsoft/quicksand/blob/main/docs/under-the-hood/03-running-commands.md hostfwd Mounts, hot-mounts, getting data in/out /microsoft/quicksand/blob/main/docs/user-guide/04-file-exchange.md CIFS via /microsoft/quicksand/blob/main/docs/under-the-hood/04-file-exchange.md guestfwd , 9p via -fsdev Checkpoints, reverts, persistent saves /microsoft/quicksand/blob/main/docs/user-guide/05-save-and-rollback.md qcow2 overlays, /microsoft/quicksand/blob/main/docs/under-the-hood/05-save-and-rollback.md savevm , blockdev-snapshot-sync Screenshots, keyboard, mouse /microsoft/quicksand/blob/main/docs/user-guide/06-desktop-control.md VNC, GPU, USB tablet, QMP input injection /microsoft/quicksand/blob/main/docs/under-the-hood/06-desktop-control.md Network modes, port forwarding /microsoft/quicksand/blob/main/docs/user-guide/07-network-and-isolation.md SLIRP NAT, /microsoft/quicksand/blob/main/docs/under-the-hood/07-network-and-isolation.md restrict=on , guestfwd What makes it fast /microsoft/quicksand/blob/main/docs/user-guide/08-performance.md io uring , IOThreads, TCG vs KVM| Guide | When to use | |---|---| | Extending the Sandbox /microsoft/quicksand/blob/main/docs/contributor-guide/02-extending-the-sandbox.md Testing /microsoft/quicksand/blob/main/docs/contributor-guide/03-testing.md Releasing /microsoft/quicksand/blob/main/docs/contributor-guide/04-releasing.md Full guides: User Guide /microsoft/quicksand/blob/main/docs/user-guide | Under the Hood /microsoft/quicksand/blob/main/docs/under-the-hood | Contributor Guide /microsoft/quicksand/blob/main/docs/contributor-guide