Quicksand Core

This package provides the core implementation for the quicksand VM harness.

It includes the abstractions for running VMs that AI agents can interact with, including command execution, file operations, and state checkpointing. Most users should install quick-sandbox with QEMU and image extras instead.

Installation

For most users, install the main package:

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

For core-only (no bundled images):

pip install quicksand-core

Core Exports

This package exports the core building blocks:

from quicksand_core import (
    # Main classes
    Sandbox,
    SandboxUser,
    Mount,
    ExecuteResult,
    # Save support
    SaveManifest,
    # Image resolution
    ResolvedImage,
    # Runtime management
    get_runtime,
    RuntimeInfo,
    is_runtime_available,
    # Accelerator detection
    get_accelerator,
    detect_accelerator,
    AcceleratorStatus,
    Accelerator,
    # Platform configuration
    get_platform_config,
    PlatformConfig,
    # Architecture/OS types
    Architecture,
    MachineType,
    OS,
)

Usage with Custom Image

import asyncio
from quicksand_core import Sandbox

async def main():
    async with Sandbox(image="your-image-name", memory="1G", cpus=2) as sb:
        result = await sb.execute("cat /etc/os-release")
        print(result.stdout)

asyncio.run(main())

Features

• Real VM isolation: Hypervisor-level isolation (KVM, HVF, WHPX)
• Cross-platform: Linux, macOS, Windows
• Streaming commands: Incremental stdin and output, with backpressure, EOF, and cancellation
• Guest users: Create/delete OS accounts and run commands with user-specific identity and home directories inside one VM
• Platform abstraction: Automatic detection of accelerators and machine types
• Save and load: Save VM disk state to a directory and load it on any machine
• File sharing: CIFS mounts via quicksand-smb (pure-Python SMB3 server — a subprocess via QEMU guestfwd on macOS/Linux, an in-process loopback TCP listener on Windows with no admin rights required)
• Performance optimizations:
  • io_uring disk AIO (~50% lower latency on Linux)
  • IOThreads for better concurrent disk I/O (all platforms)

Streaming stdin and guest-user APIs require quicksand-ubuntu or quicksand-alpine 0.10.0 or newer, or a custom image rebuilt with the updated guest agent. Updating the host package does not update saved guest images.

For Most Users

Install quick-sandbox with a bundled image for zero-configuration usage:

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

import asyncio
from quicksand import UbuntuSandbox

async def main():
    async with UbuntuSandbox() as sb:
        result = await sb.execute("ls -la /")
        print(result.stdout)

asyncio.run(main())

License

MIT