Quickly sandbox your AI agent.
Python
layout: home
hero: name: Quicksand
text: Full Linux VMs from Python
tagline: Launch, control, and snapshot QEMU virtual machines through an async Python API. No root, no Docker, no cloud. actions: - theme: brand text: Get Started link: /user-guide/01-installation - theme: alt text: Go Under the Hood link: /under-the-hood/
features:
- title: β‘ Run Commands details: Execute shell commands inside a VM and get stdout, stderr, and exit code back. link: /user-guide/03-running-commands
- title: πΎ Save & Rollback details: Checkpoint before risky operations and revert on failure. Save progress to disk and resume later. link: /user-guide/05-save-and-rollback
- title: π₯οΈ Desktop Control details: Take screenshots, type text, click buttons, and move the mouse through a full graphical desktop. link: /user-guide/06-desktop-control
- title: π Network Isolation details: VMs are isolated by default. Opt in to internet access and port forwarding when you need it. link: /user-guide/07-network-and-isolation
- title: π File Sharing details: Mount host directories into the VM at boot or on the fly. CIFS and 9p protocols supported. link: /user-guide/04-file-exchange
- title: π Cross-Platform details: Works on macOS, Linux, and Windows with hardware acceleration. No system dependencies. link: /user-guide/08-performance
Example: Ubuntu Hello, World
Install quicksand with QEMU and an Ubuntu VM image. Everything you need in one line.
pip install 'quicksand[qemu,ubuntu]'
Launch a sandbox, install a package, and use it. All inside an isolated VM that boots in ~2 seconds.
import asyncio
from quicksand import Sandbox, Mount, NetworkMode
async def main():
# Each sandbox is a real Ubuntu VM with its own kernel
async with Sandbox(
image="ubuntu",
network_mode=NetworkMode.FULL, # Enable internet for apt
mounts=[Mount(".", "/mnt/workspace")], # Share your project into the VM
) as sb:
# Full apt ecosystem β install anything you'd install on a real machine
await sb.execute("apt-get update && apt-get install -y figlet")
# Your files are right there inside the VM
await sb.execute("ls /mnt/workspace")
# Run it just like you would in a terminal
result = await sb.execute("figlet Quicksand")
print(result.stdout)
# VM is gone β nothing left on the host
asyncio.run(main())
___ _ _ _
/ _ \ _ _(_) ___| | _____ __ _ _ __ __| |
| | | | | | | |/ __| |/ / __|/ _` | '_ \ / _` |
| |_| | |_| | | (__| <\__ \ (_| | | | | (_| |
\__\_\\__,_|_|\___|_|\_\___/\__,_|_| |_|\__,_|
That's it. No Docker, no root, no cloud account. Just a normal user process with hypervisor-level isolation.