Metadata-Version: 2.4
Name: quick-sandbox
Version: 0.11.1
Summary: A VM harness for AI agents that works on macOS, Linux, and Windows.
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: quicksand-core<0.12.0,>=0.11.1
Provides-Extra: all
Requires-Dist: quicksand-agent>=0.3.7; extra == 'all'
Requires-Dist: quicksand-alpine-desktop>=0.7.5; extra == 'all'
Requires-Dist: quicksand-alpine>=0.7.2; extra == 'all'
Requires-Dist: quicksand-cua>=0.2.7; extra == 'all'
Requires-Dist: quicksand-image-tools>=0.3.2; extra == 'all'
Requires-Dist: quicksand-qemu>=0.4.3; extra == 'all'
Requires-Dist: quicksand-ubuntu-desktop>=0.7.5; extra == 'all'
Requires-Dist: quicksand-ubuntu>=0.7.2; extra == 'all'
Provides-Extra: alpine
Requires-Dist: quicksand-alpine>=0.7.2; extra == 'alpine'
Provides-Extra: alpine-desktop
Requires-Dist: quicksand-alpine-desktop>=0.7.5; extra == 'alpine-desktop'
Provides-Extra: dev
Requires-Dist: quicksand-base-scaffold>=0.1.3; extra == 'dev'
Requires-Dist: quicksand-image-tools>=0.3.2; extra == 'dev'
Requires-Dist: quicksand-overlay-scaffold>=0.1.4; extra == 'dev'
Provides-Extra: qemu
Requires-Dist: quicksand-qemu>=0.4.3; extra == 'qemu'
Provides-Extra: quicksand-agent
Requires-Dist: quicksand-agent>=0.3.7; extra == 'quicksand-agent'
Provides-Extra: quicksand-cua
Requires-Dist: quicksand-cua>=0.2.7; extra == 'quicksand-cua'
Provides-Extra: ubuntu
Requires-Dist: quicksand-ubuntu>=0.7.2; extra == 'ubuntu'
Provides-Extra: ubuntu-desktop
Requires-Dist: quicksand-ubuntu-desktop>=0.7.5; extra == 'ubuntu-desktop'
Description-Content-Type: text/markdown

# Quicksand

Quicksand is a VM harness for AI agents that works on macOS, Linux, and Windows.

## Quick Start

**1. Install quicksand**

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

**2. Run the sandbox in python**

```python
import asyncio
from quicksand import UbuntuSandbox

async def main():
    async with UbuntuSandbox() as sb:
        result = await sb.execute("echo 'Hello from the sandbox!'")
        print(result.stdout)

asyncio.run(main())
```

That's it. Docker? Don't need it. WSL2? Nope. Batteries? Included.

## Usage

```python
import asyncio
from quicksand import Sandbox, Mount, NetworkMode

async def main():
    async with Sandbox(
        image="ubuntu",
        mounts=[Mount("./workspace", "/mnt/workspace")],
        network_mode=NetworkMode.FULL,  # Full internet access
    ) as sb:
        await sb.execute("pip install requests")
        await sb.execute("python /mnt/workspace/script.py")
        print((await sb.execute("cat /tmp/output.txt")).stdout)
        await sb.save("my-save")  # Save disk state, VM keeps running

asyncio.run(main())
```

See [examples/](examples/) for more. For implementation details, see [Under the Hood](../../docs/under-the-hood/).

## How It Works

```mermaid
graph LR
    subgraph Host["Host"]
        HostFiles["Host Files"]
        subgraph Process["Python Process"]
            Code["Your Code"]
            subgraph SB["quicksand.Sandbox"]
                TCP["TCP Client"]
                FileSync["FileSync (SMB/CIFS)"]
            end
        end
        subgraph QEMU["QEMU Process (bundled)"]
            subgraph Accel["KVM / HVF / WHPX (host)"]
                subgraph VM["Linux VM (bundled)"]
                    Agent["quicksand-guest-agent"]
                    Mount["/mnt/data"]
                end
            end
        end
    end

    Code <-->|".execute"| SB
    SB -->|launches| QEMU
    TCP <-->|commands| Agent
    HostFiles <--> FileSync
    FileSync <-.->|sync| Mount
```

Each sandbox runs in a real virtual machine with hypervisor-level isolation:

| Platform | Accelerator | Machine | File Sharing | Performance |
|----------|-------------|---------|--------------|-------------|
| Linux x86_64 | KVM | q35 | SMB/CIFS | io_uring + IOThreads |
| Linux ARM64 | KVM | virt | SMB/CIFS | io_uring + IOThreads |
| macOS | HVF | q35/virt | SMB/CIFS | IOThreads |
| Windows | WHPX | q35 | SMB/CIFS | IOThreads |

Key components:
- **Bundled QEMU**: No system installation required
- **Guest agent**: Lightweight TCP server for command execution
- **Disposable overlays**: Base image unchanged, writes go to temp overlay
- **SMB/CIFS mounts**: Mount host directories into the VM
- **Platform optimizations**: io_uring (~50% lower disk latency), IOThreads

## Requirements

- Python 3.11+
- No system dependencies (QEMU is bundled)
- For custom images: Docker
