Quicksand

Launch, control, and snapshot QEMU virtual machines through an async Python API. No root, no Docker, no cloud.

$ pip install quick-sandbox

⚡ Run Commands

Execute shell commands inside a VM and get stdout, stderr, and exit code back.

💾 Save & Rollback

Checkpoint before risky operations and revert on failure. Save progress to disk and resume later.

🖥️ Desktop Control

Take screenshots, type text, click buttons, and move the mouse through a full graphical desktop.

🔒 Network Isolation

VMs are isolated by default. Opt in to internet access and port forwarding when you need it.

📁 File Sharing

Mount host directories into the VM at boot or on the fly. CIFS and 9p protocols supported.

🌍 Cross-Platform

Works on macOS, Linux, and Windows with hardware acceleration. No system dependencies.

Example: Ubuntu Hello, World

Install quicksand with QEMU and an Ubuntu VM image. Everything you need in one line.

bash

pip install 'quicksand[qemu,ubuntu]'

Launch a sandbox, install a package, and use it. All inside an isolated VM that boots in ~2 seconds.

python

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.