Microsoft releases Quicksand: Python API to sandbox AI agents via QEMU

Quicksand is an async Python library published by Microsoft for launching, controlling, and snapshotting QEMU virtual machines, with a specific focus on sandboxing AI agents. Installation is minimal: a single pip install 'quick-sandbox[qemu,alpine]' command handles everything, with no Docker, system dependencies, or root privileges required. The library runs on x86_64 and ARM64 processors and is compatible with macOS, Linux, and Windows.

Usage is straightforward. Developers import the Sandbox class, boot an image (e.g., ubuntu or alpine), and control it via async methods. The basic pattern is async with Sandbox(image="ubuntu") as sb:, followed by sb.execute() to run commands, sb.mount() to share host directories, and sb.screenshot() or sb.type_text() to control a graphical desktop if enabled. Results include stdout, stderr, and exit codes. Sandboxes are network-isolated by default; developers opt in to internet and port forwarding via NetworkMode.FULL and PortForward() configuration.

The library ships with five pre-built images. Base images are ubuntu (~341 MB, Ubuntu 24.04 headless) and alpine (~78 MB, Alpine 3.23 headless for faster boot). Overlay images add graphical environments: ubuntu-desktop (~263 MB) and alpine-desktop (~310 MB) both include Xfce4 and a browser (Firefox or Chromium). A specialized quicksand-agent image (~304 MB) provides Ubuntu with Python 3.12, uv, build-essential, requests, pyyaml, ddgs, and markitdown. The quicksand-cua image (~445 MB) extends quicksand-agent with Xvfb, x11vnc, noVNC, Playwright, and Chromium for advanced browser automation.

Key features include persistent snapshots (await sb.save("my-env") saves disk state and can be reloaded on a different machine), checkpointing and rollback (await sb.checkpoint("before-experiment") followed by await sb.revert() to undo risky changes), and desktop control (enable_display=True activates VNC and allows screenshots, keyboard input, and mouse control). Configuration options cover memory (default 512M), CPU cores (default 1), disk size, and port forwarding. The library is open-source; the full source code is available on GitHub at https://github.com/microsoft/quicksand with guides for installation, usage, and extending functionality.

Quicksand addresses a concrete pain point for AI agent developers: the need to safely execute untrusted or experimental code in isolation. By wrapping QEMU with a Python async API, Microsoft eliminates the typical barriers to VM-based sandboxing—no Docker daemon, no WSL layer, no root privileges. The library's pre-built images (ranging from Alpine at ~78 MB for fast boot to a full agent stack at ~445 MB) and snapshot/checkpoint capabilities make it possible to prototype, test, and roll back agent behavior without managing infrastructure.

The tool's flexibility—supporting both headless and desktop images, file mounts, port forwarding, and cross-machine snapshot restoration—suggests it is designed for both development workflows (where agents may need GUI access or browser control) and production-like scenarios (where state must be preserved and migrated). Network isolation by default aligns with security-first design; opt-in FULL mode lets developers test internet-dependent behaviors when needed.

No comments yet. Be the first to share your thoughts!