quick-sandbox 0.11.1__py3-none-any.whl

quick_sandbox-0.11.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+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

quick_sandbox-0.11.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+quicksand/__init__.py,sha256=hwdfDVORlg5ZmCRpbEwWaxdPQwVo4Qdxd0x-YjUAzF4,4450
+quicksand/__main__.py,sha256=l56FIy4SIE8GBMQCYIzHqIo3m1CKat1RArihLJN3gsg,39
+quicksand/benchmark.py,sha256=fut9Fwxv3UYGwpEAHSS62_mOgdDo0OABcusEYHxkxU0,7960
+quicksand/cli/__init__.py,sha256=iRq95BmJGr1Eal3W_z_0kJNB_lFwKroOlNoJxrl8M74,1511
+quicksand/cli/clean.py,sha256=YUvemKj-4RzltKVxnCOt4XAs4d3Zz9Gm3jgPTKZgdzs,1805
+quicksand/cli/dev.py,sha256=huscVWozDCzht05Ha2YEvER8IR-ukFeWuHIqyy_Yq38,4431
+quicksand/cli/images.py,sha256=vyeoky_YyNlfY7slwZaKt5bbOUsbxvahXn0kwKTtIOk,5790
+quicksand/cli/install.py,sha256=3QwXDdXTSH_bucihk9bB6lMFcRGwrG117QBCjaCK4MI,21977
+quicksand/cli/qemu.py,sha256=H7RdlVvBMWDAKFiNQjBTcZ8JepggtXvGLJOD9Cnmz60,2065
+quicksand/cli/release_save.py,sha256=x4GGzKccuYfpwdSwozQpF8KQYnpvCqA4-cggAM1gJ2Q,8725
+quicksand/cli/run.py,sha256=jDTYvBVfQjj88q1W1wk7ot3KcuzirHMzn0d5V8TOiG4,8584
+quicksand/cli/uninstall.py,sha256=YAqQrLQJuKvbBBNuhQkE0fpSR_K2_32eVgP_REWF1JU,2408
+quick_sandbox-0.11.1.dist-info/METADATA,sha256=FO9gFROHvZa8-bgCwaU8-un4mZv84xJ9SluoyMitqoU,4443
+quick_sandbox-0.11.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+quick_sandbox-0.11.1.dist-info/entry_points.txt,sha256=a2k3tA0k2ebK1AC8O5qkKbbTHCU7Q49d9LtAd5D3qtc,49
+quick_sandbox-0.11.1.dist-info/RECORD,,

quick_sandbox-0.11.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

quick_sandbox-0.11.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quicksand = quicksand.cli:main

quicksand/__init__.py

@@ -0,0 +1,158 @@
+"""
+Quicksand is a VM harness for AI agents.
+
+It gives agents a real computer to work with. They can install packages, run
+scripts, browse the web, and manipulate files inside a sandboxed VM.
+
+Quick start (pip install quick-sandbox[ubuntu]):
+    import asyncio
+    from quicksand import Sandbox
+
+    async def main():
+        async with Sandbox(image="ubuntu") as sb:
+            result = await sb.execute("ls -la /")
+            print(result.stdout)
+
+    asyncio.run(main())
+
+Or with Alpine (pip install quick-sandbox[alpine]):
+    from quicksand import Sandbox
+
+    async with Sandbox(image="alpine") as sb:
+        result = await sb.execute("cat /etc/os-release")
+
+Or with custom configuration:
+    from quicksand import Sandbox
+
+    async with Sandbox(image="ubuntu", memory="2G", cpus=4) as sb:
+        result = await sb.execute("cat /etc/os-release")
+
+Install extras:
+    pip install quick-sandbox[ubuntu]   # Bundled Ubuntu image (~341MB)
+    pip install quick-sandbox[alpine]   # Bundled Alpine image (~78MB, faster boot)
+    pip install quick-sandbox[dev]      # Build custom images from Dockerfiles
+"""
+
+# Re-export everything from quicksand-core
+from quicksand_core import (
+    OS,
+    Accelerator,
+    AcceleratorStatus,
+    Architecture,
+    BootTiming,
+    ExecuteResult,
+    Key,
+    MachineType,
+    Mount,
+    MountType,
+    NetworkMode,
+    PlatformConfig,
+    PortForward,
+    RuntimeInfo,
+    Sandbox,
+    SandboxConfig,
+    SandboxConfigParams,
+    SaveManifest,
+    detect_accelerator,
+    ensure_runtime,
+    get_accelerator,
+    get_machine_type,
+    get_platform_config,
+    get_runtime,
+    install_qemu,
+    is_runtime_available,
+)
+
+from quicksand.cli.install import install
+
+
+class _MissingOptionalSandbox:
+    """Placeholder for optional sandbox types that aren't installed."""
+
+    def __init__(self, install_extra: str, sandbox_type: str):
+        self._install_extra = install_extra
+        self._sandbox_type = sandbox_type
+
+    def __call__(self, *args, **kwargs):
+        raise ImportError(
+            f"{self._sandbox_type} requires the '{self._install_extra}' extra.\n"
+            f"Install with: pip install 'quicksand[{self._install_extra}]'"
+        )
+
+    def __repr__(self):
+        return f"<{self._sandbox_type}: not installed>"
+
+
+# Conditionally import image extras if available
+try:
+    from quicksand_ubuntu import UbuntuSandbox
+except ImportError:
+    UbuntuSandbox = _MissingOptionalSandbox("ubuntu", "UbuntuSandbox")  # type: ignore[misc, assignment]  # ty: ignore[invalid-assignment]
+
+try:
+    from quicksand_alpine import AlpineSandbox
+except ImportError:
+    AlpineSandbox = _MissingOptionalSandbox("alpine", "AlpineSandbox")  # type: ignore[misc, assignment]  # ty: ignore[invalid-assignment]
+
+try:
+    from quicksand_alpine_desktop import AlpineDesktopSandbox
+except ImportError:
+    AlpineDesktopSandbox = _MissingOptionalSandbox("alpine-desktop", "AlpineDesktopSandbox")  # type: ignore[misc, assignment]  # ty: ignore[invalid-assignment]
+
+try:
+    from quicksand_ubuntu_desktop import UbuntuDesktopSandbox
+except ImportError:
+    UbuntuDesktopSandbox = _MissingOptionalSandbox("ubuntu-desktop", "UbuntuDesktopSandbox")  # type: ignore[misc, assignment]  # ty: ignore[invalid-assignment]
+
+__all__ = [  # noqa: RUF022
+    # Core
+    "Sandbox",
+    "SandboxConfig",
+    "SandboxConfigParams",
+    "Mount",
+    "MountType",
+    "PortForward",
+    "ExecuteResult",
+    # Boot timing
+    "BootTiming",
+    # Save
+    "SaveManifest",
+    # Runtime management
+    "get_runtime",
+    "RuntimeInfo",
+    "is_runtime_available",
+    "get_machine_type",
+    "ensure_runtime",
+    "install_qemu",
+    # Accelerator
+    "get_accelerator",
+    "detect_accelerator",
+    "AcceleratorStatus",
+    # Platform
+    "get_platform_config",
+    "PlatformConfig",
+    # Types
+    "Key",
+    "Accelerator",
+    "Architecture",
+    "MachineType",
+    "NetworkMode",
+    "OS",
+    # Install API
+    "install",
+    # Ubuntu extras (available with quicksand[ubuntu])
+    "UbuntuSandbox",
+    # Alpine extras (available with quicksand[alpine])
+    "AlpineSandbox",
+    # Alpine Desktop extras (available with quicksand[alpine-desktop])
+    "AlpineDesktopSandbox",
+    # Ubuntu Desktop extras (available with quicksand[ubuntu-desktop])
+    "UbuntuDesktopSandbox",
+]
+
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("quicksand")
+except Exception:
+    __version__ = "0.0.0"

quicksand/__main__.py

@@ -0,0 +1,3 @@
+from quicksand.cli import main
+
+main()

quicksand/benchmark.py

@@ -0,0 +1,256 @@
+"""Benchmark sandbox boot times.
+
+Usage::
+
+    import asyncio
+    from quicksand.benchmark import benchmark
+
+    result = asyncio.run(benchmark("ubuntu", iterations=5))
+    print(result)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import math
+import sys
+import time
+
+from pydantic import BaseModel, ConfigDict
+
+from quicksand import BootTiming, Mount, Sandbox, install
+
+
+class BootSample(BaseModel):
+    """A single boot-time measurement."""
+
+    model_config = ConfigDict(frozen=True)
+
+    iteration: int
+    boot_time_s: float
+
+
+class BenchmarkResult(BaseModel):
+    """Aggregate result of a boot-time benchmark run."""
+
+    model_config = ConfigDict(frozen=True)
+
+    image: str
+    iterations: int
+    qemu_command: list[str]
+    samples: list[BootSample]
+    boot_timing: BootTiming | None
+    min_s: float
+    p50_s: float
+    p90_s: float
+    p95_s: float
+    p99_s: float
+    max_s: float
+
+    def __str__(self) -> str:
+        lines = [
+            "Quicksand Boot Benchmark",
+            f"  Image:       {self.image}",
+            f"  Iterations:  {self.iterations}",
+            "",
+            "QEMU Command:",
+            self._format_qemu_command(),
+            "",
+        ]
+        for s in self.samples:
+            bar_len = int(min(s.boot_time_s / self.max_s, 1.0) * 20)
+            bar = "█" * bar_len + "░" * (20 - bar_len)
+            lines.append(f"  #{s.iteration + 1:<3} {bar} {s.boot_time_s:>7.3f}s")
+        lines.append("")
+        for label, val in [
+            ("min", self.min_s),
+            ("p50", self.p50_s),
+            ("p90", self.p90_s),
+            ("p95", self.p95_s),
+            ("p99", self.p99_s),
+            ("max", self.max_s),
+        ]:
+            lines.append(f"  {label:<4} {val:>7.3f}s")
+        if self.boot_timing:
+            lines.append("")
+            lines.append("Boot Phase Breakdown (last run):")
+            lines.append(str(self.boot_timing))
+        return "\n".join(lines)
+
+    def _format_qemu_command(self) -> str:
+        """Format the QEMU command as a readable, arg-per-line shell command."""
+        if not self.qemu_command:
+            return "  (not captured)"
+        parts = list(self.qemu_command)
+        result_lines: list[str] = [f"  {parts[0]}"]
+        i = 1
+        while i < len(parts):
+            arg = parts[i]
+            if arg.startswith("-") and i + 1 < len(parts) and not parts[i + 1].startswith("-"):
+                result_lines.append(f"    {arg} {parts[i + 1]} \\")
+                i += 2
+            else:
+                result_lines.append(f"    {arg} \\")
+                i += 1
+        # Remove trailing backslash from last line
+        if result_lines:
+            result_lines[-1] = result_lines[-1].rstrip(" \\")
+        return "\n".join(result_lines)
+
+
+async def benchmark(
+    image: str,
+    *,
+    iterations: int = 5,
+    install_extras: list[str] | None = None,
+    mounts: list[Mount] | None = None,
+) -> BenchmarkResult:
+    """Measure boot time over *iterations* runs.
+
+    Args:
+        image: Image name to benchmark (e.g. ``"ubuntu"``).
+        iterations: Number of boot cycles.
+        install_extras: Extras to ``quicksand.install()`` before benchmarking.
+            Pass an explicit list to install packages (e.g. ``["qemu", "ubuntu"]``).
+            By default nothing is installed, so a system QEMU is used.
+        mounts: Optional list of :class:`Mount` specs to include during boot.
+
+    Returns:
+        A :class:`BenchmarkResult` with per-iteration samples and summary stats.
+    """
+    if install_extras:
+        install(*install_extras)
+
+    samples: list[BootSample] = []
+    qemu_command: list[str] = []
+    boot_timing: BootTiming | None = None
+
+    for i in range(iterations):
+        _print_progress(i, iterations)
+
+        sandbox = Sandbox(image=image, mounts=mounts or [])
+        t0 = time.perf_counter()
+        await sandbox.start()
+        boot_time = time.perf_counter() - t0
+
+        if not qemu_command:
+            qemu_command = sandbox.qemu_command or []
+        boot_timing = sandbox.boot_timing
+
+        await sandbox.stop()
+
+        samples.append(
+            BootSample(
+                iteration=i,
+                boot_time_s=round(boot_time, 4),
+            )
+        )
+
+    _print_progress(iterations, iterations)
+    sys.stdout.write("\n")
+
+    times = sorted(s.boot_time_s for s in samples)
+    return BenchmarkResult(
+        image=image,
+        iterations=iterations,
+        qemu_command=qemu_command,
+        boot_timing=boot_timing,
+        samples=samples,
+        min_s=times[0],
+        p50_s=_percentile(times, 50),
+        p90_s=_percentile(times, 90),
+        p95_s=_percentile(times, 95),
+        p99_s=_percentile(times, 99),
+        max_s=times[-1],
+    )
+
+
+def _percentile(sorted_values: list[float], p: float) -> float:
+    """Compute the p-th percentile from a sorted list (nearest-rank)."""
+    k = (p / 100) * (len(sorted_values) - 1)
+    f = math.floor(k)
+    c = math.ceil(k)
+    if f == c:
+        return sorted_values[int(k)]
+    return round(sorted_values[f] * (c - k) + sorted_values[c] * (k - f), 4)
+
+
+# ── CLI integration ───────────────────────────────────────────────────
+
+
+def _print_progress(completed: int, total: int) -> None:
+    """Print a cross-platform progress bar matching the install download style."""
+    bar_width = 30
+    filled = int(bar_width * completed / total) if total > 0 else 0
+    bar = "#" * filled + "-" * (bar_width - filled)
+    percent = (completed / total * 100) if total > 0 else 0
+    sys.stdout.write(f"\r  {bar} {percent:5.1f}% ({completed}/{total} iterations)")
+    sys.stdout.flush()
+
+
+def _parse_mount(value: str) -> Mount:
+    """Parse ``HOST:GUEST[:TYPE]`` into a :class:`Mount`."""
+    parts = value.split(":")
+    if len(parts) < 2:
+        raise argparse.ArgumentTypeError(
+            f"Invalid mount format: {value} (expected HOST:GUEST[:TYPE])"
+        )
+    host, guest = parts[0], parts[1]
+    mount_type = parts[2] if len(parts) > 2 else "cifs"
+    if mount_type not in ("cifs", "9p"):
+        raise argparse.ArgumentTypeError(f"Invalid mount type: {mount_type} (expected cifs or 9p)")
+    from typing import cast
+
+    from quicksand import MountType
+
+    return Mount(host=host, guest=guest, type=cast(MountType, mount_type))
+
+
+def register_args(parser: argparse.ArgumentParser) -> None:
+    """Add benchmark arguments to a parser."""
+    parser.add_argument("image", help="Image to benchmark (e.g. ubuntu)")
+    parser.add_argument(
+        "-n", "--iterations", type=int, default=5, help="Number of boot iterations (default: 5)"
+    )
+    parser.add_argument(
+        "-v",
+        "--mount",
+        action="append",
+        metavar="HOST:GUEST[:TYPE]",
+        help="Mount host directory into sandbox during boot (repeatable)",
+    )
+    parser.add_argument(
+        "--json", action="store_true", dest="json_output", help="Output results as JSON"
+    )
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the benchmark subcommand."""
+    parser = subparsers.add_parser(
+        "benchmark",
+        help="Benchmark sandbox boot times",
+    )
+    register_args(parser)
+
+
+def cmd(args: argparse.Namespace) -> int:
+    """Run the benchmark CLI command."""
+    mounts = [_parse_mount(m) for m in args.mount] if args.mount else None
+    result = asyncio.run(benchmark(args.image, iterations=args.iterations, mounts=mounts))
+    if args.json_output:
+        print(result.model_dump_json(indent=2))
+    else:
+        print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    import argparse as _argparse
+
+    _parser = _argparse.ArgumentParser(description="Benchmark quicksand boot times")
+    register_args(_parser)
+    _args = _parser.parse_args()
+
+    _result = asyncio.run(benchmark(_args.image, iterations=_args.iterations))
+    print(_result)

quicksand/cli/__init__.py

@@ -0,0 +1,58 @@
+"""Quicksand CLI - run sandboxes from the command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import clean, dev, install, qemu, release_save, run, uninstall
+
+
+def main() -> int:
+    """Main entry point for the quicksand CLI."""
+    parser = argparse.ArgumentParser(
+        prog="quicksand",
+        description="A VM harness for AI agents.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Register subcommands
+    run.register(subparsers)
+    install.register(subparsers)
+    uninstall.register(subparsers)
+    clean.register(subparsers)
+    release_save.register(subparsers)
+    qemu.register(subparsers)
+    dev.register(subparsers)
+
+    from .. import benchmark as benchmark_mod
+
+    benchmark_mod.register(subparsers)
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        return run.cmd(args)
+    elif args.command == "install":
+        return install.cmd(args)
+    elif args.command == "uninstall":
+        return uninstall.cmd(args)
+    elif args.command == "release":
+        return release_save.cmd(args)
+    elif args.command == "qemu":
+        return qemu.cmd(args)
+    elif args.command == "clean":
+        return clean.cmd(args)
+    elif args.command == "dev":
+        return dev.cmd(args)
+    elif args.command == "benchmark":
+        from .. import benchmark as benchmark_mod
+
+        return benchmark_mod.cmd(args)
+    else:
+        parser.print_help()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())