Skip to content

Quickly sandbox your AI agent.

Python

Refresh release documentation and README highlights

Tyler Payne5a7bf7ef1472
diff --git a/README.md b/README.md
index ad797ee..56e720d 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,15 @@
![Quicksand](docs/banner-light.png)
-Quicksand is an async Python API to launch, control, and snapshot [QEMU](https://www.qemu.org) virtual machines with a particular focus on sandboxing AI agents. Quicksand provides pre-built Linux VMs for Ubuntu and Alpine distros. It works on x86_64 and ARM64 across macOS, Linux, and Windows with no root privileges, no Docker, and no system dependencies. Just `pip install quick-sandbox`.
+Quicksand is an async Python API to launch, control, and snapshot [QEMU](https://www.qemu.org) virtual machines with a particular focus on sandboxing AI agents. Quicksand provides pre-built Linux VMs for Ubuntu and Alpine distros and supports x86_64 and ARM64 across macOS, Linux, and Windows. Running sandboxes needs no root privileges or Docker; install the QEMU and image extras for a bundled runtime on supported platforms.
+
+## Recent releases
+
+- πŸš€ **2026-09-14 β€” [quick-sandbox 0.12.0](https://pypi.org/project/quick-sandbox/0.12.0/):** Streaming `stdin`, guest-user accounts, and guest-local `flock`/SQLite locking. Includes refreshed Ubuntu and Alpine images; upgrade your images alongside the host package.
+- πŸ”οΈ **2026-09-09 β€” [quicksand-alpine 0.9.12](https://pypi.org/project/quicksand-alpine/0.9.12/):** Rebuilt Alpine 3.23 images across the supported platforms and corrected the minimal-image package documentation.
+- πŸͺŸ **2026-07-07 β€” [quick-sandbox 0.11.15](https://pypi.org/project/quick-sandbox/0.11.15/):** Windows file sharing without Administrator rights. Also fixes CIFS remount hangs and adds a loopback TCP transport for the guest agent on Windows.
+
+See the [changelog](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md) for the full release history.
## Installation
@@ -143,12 +151,15 @@ Sandbox(
| Image | Type | Wheel size | Install command | What is it |
|-------|------|-----------|-----------------|------------|
-| `ubuntu` | Base | ~341 MB | `quicksand install ubuntu` | Ubuntu 24.04 headless |
-| `alpine` | Base | ~78 MB | `quicksand install alpine` | Alpine 3.23 headless (faster boot) |
-| `ubuntu-desktop` | Overlay (`ubuntu`) | ~263 MB | `quicksand install ubuntu-desktop` | Ubuntu 24.04 + Xfce4 + Firefox |
-| `alpine-desktop` | Overlay (`alpine`) | ~310 MB | `quicksand install alpine-desktop` | Alpine 3.23 + Xfce4 + Chromium |
-| `quicksand-agent` | Overlay (`ubuntu`) | ~304 MB | `quicksand install quicksand-agent` | Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown |
-| `quicksand-cua` | Overlay (`quicksand-agent`) | ~445 MB | `quicksand install quicksand-cua` | Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium |
+| `ubuntu` | Base | ~309-357 MB | `quicksand install ubuntu` | Ubuntu 24.04 headless |
+| `alpine` | Base | ~82-85 MB | `quicksand install alpine` | Alpine 3.23 headless (faster boot) |
+| `ubuntu-desktop` | Overlay (`ubuntu`) | ~273-281 MB | `quicksand install ubuntu-desktop` | Ubuntu 24.04 + Xfce4 + Firefox |
+| `alpine-desktop` | Overlay (`alpine`) | ~346-363 MB | `quicksand install alpine-desktop` | Alpine 3.23 + Xfce4 + Chromium |
+| `quicksand-agent` | Overlay (`ubuntu`) | ~306-335 MB | `quicksand install quicksand-agent` | Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown |
+| `quicksand-cua` | Overlay (`quicksand-agent`) | ~489-500 MB | `quicksand install quicksand-cua` | Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium |
+
+Sizes are approximate full image-wheel downloads for the September 14, 2026 releases
+and vary by architecture. Overlay sizes exclude their base images.
## Building from source
diff --git a/docs/contributor-guide/04-releasing.md b/docs/contributor-guide/04-releasing.md
index d527480..5a2659f 100644
--- a/docs/contributor-guide/04-releasing.md
+++ b/docs/contributor-guide/04-releasing.md
@@ -1,6 +1,6 @@
# Releasing
-Releases are managed via the `/release` Claude Code skill.
+Releases are managed by `uvr`, with the repository's `/release` skill as the workflow guide.
## Flow
@@ -72,3 +72,9 @@ failure normally requires a fresh dispatch.
## Changelog
Update `CHANGELOG.md` on the release branch before dispatch. Categories: Added, Changed, Deprecated, Removed, Fixed, Security.
+
+After publication, refresh the short **Recent releases** list before
+**Installation** in the root `README.md`. Use the PyPI publication date, a
+version-specific PyPI link, and one or two sentences about the release.
+The `sync-readme` pre-commit hook copies the root README to
+`packages/quicksand/README.md` for the package description.
diff --git a/docs/packages/quicksand-core.md b/docs/packages/quicksand-core.md
index 6ff4e7a..75069b1 100644
--- a/docs/packages/quicksand-core.md
+++ b/docs/packages/quicksand-core.md
@@ -2,7 +2,7 @@
This package provides the core implementation for the [quicksand](https://github.com/microsoft/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 `quicksand` instead, which includes pre-built images.
+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
@@ -15,7 +15,7 @@ pip install 'quick-sandbox[qemu,ubuntu]'
For core-only (no bundled images):
```bash
-pip install quick-sandbox
+pip install quicksand-core
```
## Core Exports
@@ -26,6 +26,7 @@ This package exports the core building blocks:
from quicksand_core import (
# Main classes
Sandbox,
+ SandboxUser,
Mount,
ExecuteResult,
# Save support
@@ -69,6 +70,8 @@ asyncio.run(main())
- **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)
@@ -76,9 +79,13 @@ asyncio.run(main())
- 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 `quicksand` with a bundled image for zero-configuration usage:
+Install `quick-sandbox` with a bundled image for zero-configuration usage:
```bash
pip install 'quick-sandbox[qemu,ubuntu]'
diff --git a/docs/under-the-hood/01-installation.md b/docs/under-the-hood/01-installation.md
index 0397fe9..5b77893 100644
--- a/docs/under-the-hood/01-installation.md
+++ b/docs/under-the-hood/01-installation.md
@@ -24,9 +24,11 @@ The `-L` flag tells QEMU where to find firmware and keymap files. Without it, QE
If the bundled package isn't installed, Quicksand falls back to system QEMU found on `PATH`.
-### Windows ARM64 and fat wheels
+### Windows ARM64 and interpreter architecture
-On Windows ARM64, most users run x86_64 Python through Microsoft's transparent emulation layer. The user may not even know they're running emulated Python β€” it's the default. This creates a conflict:
+quicksand-qemu 0.5.12 packages are single-architecture wheels: `win_amd64` contains x86_64
+executables and `win_arm64` contains ARM64 executables, directly in `bin/`.
+Windows ARM64 can run x86_64 Python through emulation, which affects wheel selection:
| | Python arch | pip accepts | QEMU needed |
|---|---|---|---|
@@ -36,31 +38,15 @@ On Windows ARM64, most users run x86_64 Python through Microsoft's transparent e
The third row is the problem. pip's wheel compatibility tags (PEP 425) match the Python interpreter's platform, not the hardware. An emulated x86_64 Python will only install `win_amd64` wheels β€” but the machine needs ARM64 QEMU binaries for hardware acceleration (WHPX).
-This problem is unique to Windows. Linux doesn't transparently emulate x86_64 on ARM64, and macOS users on Apple Silicon install ARM64 Python by default (Rosetta 2 exists but isn't the default Python experience).
+Use native ARM64 Python on Windows ARM64 so pip selects the ARM64 QEMU and image
+wheels. `quicksand install` delegates to pip; it does not override the
+interpreter's platform tags. Installing a single-architecture x64 QEMU wheel
+under emulated Python can produce an architecture-mismatch error at runtime.
-**Our solution: fat `win_amd64` wheels.** The `win_amd64` quicksand-qemu wheel ships both x86_64 and ARM64 QEMU binaries:
-
-```
-quicksand_qemu/bin/
-β”œβ”€β”€ x86_64/ # x86_64 QEMU binaries
-β”‚ β”œβ”€β”€ qemu-system-x86_64.exe
-β”‚ β”œβ”€β”€ qemu-img.exe
-β”‚ └── ...
-└── arm64/ # ARM64 QEMU binaries
- β”œβ”€β”€ qemu-system-aarch64.exe
- β”œβ”€β”€ qemu-img.exe
- └── ...
-```
-
-At runtime, `_find_bundled_runtime()` reads the native CPU architecture from the Windows Registry (`HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\PROCESSOR_ARCHITECTURE`) β€” this always reports the true hardware regardless of process emulation β€” and selects the matching subdirectory. On a single-arch wheel (Linux, macOS, or `win_arm64`), binaries live directly in `bin/` with no subdirectories.
-
-**Build pipeline:**
-1. The Windows x64 CI runner builds `win_amd64.whl` with x64 QEMU in `bin/`
-2. The GitHub-hosted `windows-11-arm` runner builds `win_arm64.whl` with ARM64 QEMU in `bin/`
-3. A `pre_release` hook (runs after all builds, before publishing) opens the `win_amd64` wheel, moves its binaries to `bin/x86_64/`, extracts ARM64 binaries from the `win_arm64` wheel into `bin/arm64/`, and rewrites the wheel
-4. The `win_arm64` wheel ships unchanged (lean, single-arch) for the rare native ARM64 Python user
-
-This approach doubles the `win_amd64` wheel size (~44 MB β†’ ~80 MB) but ensures `pip install quicksand-qemu` delivers hardware-accelerated QEMU on every Windows configuration without user intervention.
+The current pipeline publishes both Windows wheels without merging them.
+`_find_bundled_runtime()` still supports legacy combined wheels with
+`bin/x86_64/` and `bin/arm64/` subdirectories, selecting by native hardware
+architecture. That is backward compatibility, not the layout of the current release.
### Platform wheel matrix
@@ -68,17 +54,19 @@ This approach doubles the `win_amd64` wheel size (~44 MB β†’ ~80 MB) but ensures
quicksand-qemu is in `_SKIP` β€” never retagged. Each runner produces exactly one wheel.
-| Runner | QEMU Binary | Wheel Tag | After `pre_release` merge |
-|--------|-------------|-----------|--------------------------|
-| `[linux, x64]` | qemu-system-x86_64 (Linux) | `manylinux_<major>_<minor>_x86_64` | unchanged |
-| `[linux, arm64]` | qemu-system-aarch64 (Linux) | `manylinux_<major>_<minor>_aarch64` | unchanged |
-| `[macos, arm64]` | qemu-system-aarch64 (macOS) | `macosx_11_0_arm64` | unchanged |
-| `[windows, x64]` | qemu-system-x86_64.exe | `win_amd64` | β†’ **fat**: x64 in `bin/x86_64/`, arm64 in `bin/arm64/` |
-| `windows-11-arm` | qemu-system-aarch64.exe | `win_arm64` ΒΉ | unchanged (consumed by merge into fat wheel) |
+| Runner | QEMU Binary | Wheel Tag |
+|--------|-------------|-----------|
+| `[linux, x64]` | qemu-system-x86_64 (Linux) | `manylinux_<major>_<minor>_x86_64` |
+| `[linux, arm64]` | qemu-system-aarch64 (Linux) | `manylinux_<major>_<minor>_aarch64` |
+| `[macos, arm64]` | qemu-system-aarch64 (macOS) | `macosx_11_0_arm64` |
+| `[windows, x64]` | qemu-system-x86_64.exe | `win_amd64` |
+| `windows-11-arm` | qemu-system-aarch64.exe | `win_arm64` ΒΉ |
Linux manylinux versions are derived from versioned symbols in the bundled ELF
binaries and libraries. They are not fixed at glibc 2.17; pip selects a wheel
compatible with the host's glibc version.
+The published quicksand-qemu 0.5.12 Linux wheels require glibc 2.38 or newer.
+On older systems, use a compatible system QEMU instead.
With quicksand-build-tools 0.6.0, custom Linux build hooks must pass the bundled
binary directory as `bin_dir` to `BinaryBundler.set_platform_wheel_tag()` and
@@ -89,14 +77,13 @@ applications using `Sandbox` do not need to change their build configuration.
#### Image wheels (ubuntu, alpine, etc.): build runners β†’ retag
-Image wheels contain qcow2 files that are cross-platform. Retag runs only on `RETAG_RUNNERS`.
+Image wheels contain architecture-specific VM data that is portable across host
+operating systems. Retag runs only on `RETAG_RUNNERS`; these are the two image builders.
| Runner | Builds | Retag produces |
|--------|--------|----------------|
-| `[linux, x64]` | `linux_x86_64` | + `macosx_10_13_x86_64`, `win_amd64` |
-| `[macos, arm64]` | `macosx_11_0_arm64` | + `linux_aarch64`, `win_arm64` |
-| `[linux, arm64]` | `linux_aarch64` | none (not in `RETAG_RUNNERS`) |
-| `[windows, *]` | β€” | not an image builder |
+| `[linux, x64]` | `manylinux_2_17_x86_64` | + `macosx_10_13_x86_64`, `win_amd64` |
+| `[macos, arm64]` | `macosx_11_0_arm64` | + `manylinux_2_17_aarch64`, `win_arm64` |
#### quicksand-qemu: host β†’ pip install
@@ -107,14 +94,15 @@ Image wheels contain qcow2 files that are cross-platform. Retag runs only on `RE
| macOS Intel | x86_64 | x86_64 | β€” (no wheel) | system QEMU (Homebrew) | HVF βœ… |
| macOS Apple Silicon | arm64 | arm64 | `macosx_11_0_arm64` | qemu-system-aarch64 | HVF βœ… |
| macOS Rosetta | arm64 | x86_64 | β€” (no wheel) | system QEMU (Homebrew) | TCG ❌ |
-| Windows | x86_64 | x86_64 | `win_amd64` (fat) | picks `bin/x86_64/` | WHPX βœ… |
-| Windows | arm64 | x86_64 (emulated) | `win_amd64` (fat) | picks `bin/arm64/` | WHPX βœ… |
+| Windows | x86_64 | x86_64 | `win_amd64` | qemu-system-x86_64 | WHPX βœ… |
+| Windows | arm64 | x86_64 (emulated) | `win_amd64` | architecture mismatch; use native Python | β€” |
| Windows | arm64 | arm64 (native) | `win_arm64` | qemu-system-aarch64 | WHPX βœ… |
**Notes:**
- **No macOS x86_64 runner** β€” macOS Intel users fall back to system QEMU via Homebrew.
- **Rosetta Python** β€” rare; gets no bundled wheel, falls back to system QEMU with software emulation (TCG).
-- **Fat wheel** β€” only `win_amd64` is fat (~2x size). All other wheels are single-arch.
+- **Acceleration** β€” requires support in both the host and QEMU build. The table lists the preferred accelerator, not a guarantee that it is available on every host.
+- **Single-architecture wheels** β€” all current QEMU wheels contain one architecture. Large image wheels also use the term "fat", but that means they carry VM image data rather than being a small PyPI stub.
## `quicksand install ubuntu`
diff --git a/docs/under-the-hood/index.md b/docs/under-the-hood/index.md
index 6aabe92..a260e8a 100644
--- a/docs/under-the-hood/index.md
+++ b/docs/under-the-hood/index.md
@@ -494,7 +494,8 @@ quicksand install ubuntu # Ubuntu 24.04 headless
quicksand install alpine # Alpine 3.23 headless
quicksand install alpine-desktop # Alpine 3.23 + Xfce4
quicksand install ubuntu-desktop # Ubuntu 24.04 + Xfce4
-quicksand install all # everything (QEMU + all images + dev tools)
+# QEMU + all images + dev tools
+quicksand install qemu ubuntu alpine ubuntu-desktop alpine-desktop agent cua dev
```
Each image package provides:
diff --git a/docs/user-guide/01-installation.md b/docs/user-guide/01-installation.md
index 1cd5d96..164b7d8 100644
--- a/docs/user-guide/01-installation.md
+++ b/docs/user-guide/01-installation.md
@@ -8,7 +8,15 @@
pip install 'quick-sandbox[qemu,alpine,ubuntu]'
```
-This installs the core Python library, CLI, QEMU, and VM images. No native dependencies needed.
+This installs the core Python library, CLI, QEMU, and image packages. On platforms
+with a compatible bundled QEMU wheel, no system QEMU installation is needed.
+
+Large image packages are published to PyPI as small stubs. On first use, they
+download the full platform-specific wheel from the
+[Quicksand index](https://microsoft.github.io/quicksand/simple/). Both automatic
+downloads and `quicksand install` require `pip` in that Python environment
+(`uv venv --seed` when using uv). Use the CLI to fetch images before first use. Set
+`QUICKSAND_AUTO_INSTALL=0` to disable automatic image downloads.
To declare it as a dependency in your `pyproject.toml`:
@@ -21,11 +29,12 @@ dependencies = [
## Install QEMU and an image
-Quicksand bundles its own QEMU, so no system install is needed. Use the `quicksand install` CLI to download platform-specific binaries and images.
+Use the `quicksand install` CLI to download bundled QEMU binaries and images.
+See [Requirements](#requirements) for platform compatibility.
```bash
quicksand install qemu # Bundled QEMU (~15MB on macOS ARM64)
-quicksand install ubuntu # Ubuntu 24.04 headless (~340MB)
+quicksand install ubuntu # Ubuntu 24.04 headless (~309-357 MB)
```
That's enough to start using Quicksand:
@@ -42,25 +51,28 @@ async with Sandbox(image="ubuntu") as sb:
### QEMU (`quicksand install qemu`)
-| | macOS ARM64 | Linux ARM64 | Linux x86_64 | Windows x86_64 |
-|---|---|---|---|---|
-| Download | 14 MB | 15 MB | 15 MB | 43 MB |
-| On disk | 58 MB | 60 MB | 53 MB | 124 MB |
+| | macOS ARM64 | Linux ARM64 | Linux x86_64 | Windows x86_64 | Windows ARM64 |
+|---|---|---|---|---|---|
+| Download | 15 MB | 16 MB | 16 MB | 44 MB | 35 MB |
### Images
-| Image | Depends on | Display | ARM64 download | ARM64 on disk | Boot p50 | Boot p95 |
-|-------|------------|---------|----------------|---------------|----------|----------|
-| `alpine` | β€” | No | 73 MB | 74 MB | 0.37s | 0.45s |
-| `ubuntu` | β€” | No | 341 MB | 346 MB | 0.88s | 0.91s |
-| `alpine-desktop` | `alpine` | Yes | 287 MB | 290 MB | 0.47s | 0.54s |
-| `ubuntu-desktop` | `ubuntu` | Yes | 252 MB | 257 MB | 0.90s | 0.96s |
-| `quicksand-agent` | `ubuntu` | No | ~304 MB | ~308 MB | 0.91s | 0.92s |
-| `quicksand-cua` | `quicksand-agent` | No | ~445 MB | ~450 MB | 0.85s | 1.01s |
+| Image | Depends on | Display | ARM64 download | Boot p50 | Boot p95 |
+|-------|------------|---------|----------------|----------|----------|
+| `alpine` | β€” | No | 82 MB | 0.37s | 0.45s |
+| `ubuntu` | β€” | No | 357 MB | 0.88s | 0.91s |
+| `alpine-desktop` | `alpine` | Yes | 346 MB | 0.47s | 0.54s |
+| `ubuntu-desktop` | `ubuntu` | Yes | 273 MB | 0.90s | 0.96s |
+| `quicksand-agent` | `ubuntu` | No | 306 MB | 0.91s | 0.92s |
+| `quicksand-cua` | `quicksand-agent` | No | 489 MB | 0.85s | 1.01s |
-Boot times measured on macOS ARM64 (Apple M3 Max, HVF) with `quicksand benchmark -n 5`. First boot is slower due to cold cache.
+Download sizes are rounded decimal MB for the September 14, 2026 releases and
+exclude dependencies. Boot times are historical measurements on macOS ARM64
+(Apple M3 Max, HVF) with `quicksand benchmark -n 5`, not a new benchmark of these
+releases. First boot is slower due to cold cache.
-`quicksand install all` installs QEMU and all images.
+`quicksand install` accepts multiple names, for example
+`quicksand install qemu ubuntu alpine`.
Alpine is smaller and boots faster. Ubuntu has a larger package ecosystem. Desktop images are overlays on their base image and add a graphical environment for screenshot/keyboard/mouse interaction. The agent sandbox images are pre-configured agent environments with Python 3.12, browser automation tools, and common AI agent dependencies.
@@ -87,6 +99,11 @@ If this prints a Linux kernel version, everything is working.
- **No root/admin.** QEMU runs as a normal user process.
- **No Docker.** Quicksand is not container-based (Docker is only needed for *building* new images, not running them).
+Use native ARM64 Python on Windows ARM64. The current Windows QEMU wheels each
+contain one architecture; emulated x86_64 Python selects the x64 wheel rather
+than the ARM64 binaries needed by the host. Linux quicksand-qemu 0.5.12 wheels require
+glibc 2.38 or newer; use a compatible system QEMU on older Linux distributions.
+
## Using system QEMU
If you already have QEMU installed, Quicksand will find it on `PATH` as a fallback. But the bundled QEMU (`quicksand install qemu`) is recommended. It's tested and includes the right firmware files.
diff --git a/packages/quicksand-core/README.md b/packages/quicksand-core/README.md
index 6ff4e7a..75069b1 100644
--- a/packages/quicksand-core/README.md
+++ b/packages/quicksand-core/README.md
@@ -2,7 +2,7 @@
This package provides the core implementation for the [quicksand](https://github.com/microsoft/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 `quicksand` instead, which includes pre-built images.
+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
@@ -15,7 +15,7 @@ pip install 'quick-sandbox[qemu,ubuntu]'
For core-only (no bundled images):
```bash
-pip install quick-sandbox
+pip install quicksand-core
```
## Core Exports
@@ -26,6 +26,7 @@ This package exports the core building blocks:
from quicksand_core import (
# Main classes
Sandbox,
+ SandboxUser,
Mount,
ExecuteResult,
# Save support
@@ -69,6 +70,8 @@ asyncio.run(main())
- **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)
@@ -76,9 +79,13 @@ asyncio.run(main())
- 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 `quicksand` with a bundled image for zero-configuration usage:
+Install `quick-sandbox` with a bundled image for zero-configuration usage:
```bash
pip install 'quick-sandbox[qemu,ubuntu]'
diff --git a/packages/quicksand/README.md b/packages/quicksand/README.md
index ad797ee..56e720d 100644
--- a/packages/quicksand/README.md
+++ b/packages/quicksand/README.md
@@ -6,7 +6,15 @@
![Quicksand](docs/banner-light.png)
-Quicksand is an async Python API to launch, control, and snapshot [QEMU](https://www.qemu.org) virtual machines with a particular focus on sandboxing AI agents. Quicksand provides pre-built Linux VMs for Ubuntu and Alpine distros. It works on x86_64 and ARM64 across macOS, Linux, and Windows with no root privileges, no Docker, and no system dependencies. Just `pip install quick-sandbox`.
+Quicksand is an async Python API to launch, control, and snapshot [QEMU](https://www.qemu.org) virtual machines with a particular focus on sandboxing AI agents. Quicksand provides pre-built Linux VMs for Ubuntu and Alpine distros and supports x86_64 and ARM64 across macOS, Linux, and Windows. Running sandboxes needs no root privileges or Docker; install the QEMU and image extras for a bundled runtime on supported platforms.
+
+## Recent releases
+
+- πŸš€ **2026-09-14 β€” [quick-sandbox 0.12.0](https://pypi.org/project/quick-sandbox/0.12.0/):** Streaming `stdin`, guest-user accounts, and guest-local `flock`/SQLite locking. Includes refreshed Ubuntu and Alpine images; upgrade your images alongside the host package.
+- πŸ”οΈ **2026-09-09 β€” [quicksand-alpine 0.9.12](https://pypi.org/project/quicksand-alpine/0.9.12/):** Rebuilt Alpine 3.23 images across the supported platforms and corrected the minimal-image package documentation.
+- πŸͺŸ **2026-07-07 β€” [quick-sandbox 0.11.15](https://pypi.org/project/quick-sandbox/0.11.15/):** Windows file sharing without Administrator rights. Also fixes CIFS remount hangs and adds a loopback TCP transport for the guest agent on Windows.
+
+See the [changelog](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md) for the full release history.
## Installation
@@ -143,12 +151,15 @@ Sandbox(
| Image | Type | Wheel size | Install command | What is it |
|-------|------|-----------|-----------------|------------|
-| `ubuntu` | Base | ~341 MB | `quicksand install ubuntu` | Ubuntu 24.04 headless |
-| `alpine` | Base | ~78 MB | `quicksand install alpine` | Alpine 3.23 headless (faster boot) |
-| `ubuntu-desktop` | Overlay (`ubuntu`) | ~263 MB | `quicksand install ubuntu-desktop` | Ubuntu 24.04 + Xfce4 + Firefox |
-| `alpine-desktop` | Overlay (`alpine`) | ~310 MB | `quicksand install alpine-desktop` | Alpine 3.23 + Xfce4 + Chromium |
-| `quicksand-agent` | Overlay (`ubuntu`) | ~304 MB | `quicksand install quicksand-agent` | Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown |
-| `quicksand-cua` | Overlay (`quicksand-agent`) | ~445 MB | `quicksand install quicksand-cua` | Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium |
+| `ubuntu` | Base | ~309-357 MB | `quicksand install ubuntu` | Ubuntu 24.04 headless |
+| `alpine` | Base | ~82-85 MB | `quicksand install alpine` | Alpine 3.23 headless (faster boot) |
+| `ubuntu-desktop` | Overlay (`ubuntu`) | ~273-281 MB | `quicksand install ubuntu-desktop` | Ubuntu 24.04 + Xfce4 + Firefox |
+| `alpine-desktop` | Overlay (`alpine`) | ~346-363 MB | `quicksand install alpine-desktop` | Alpine 3.23 + Xfce4 + Chromium |
+| `quicksand-agent` | Overlay (`ubuntu`) | ~306-335 MB | `quicksand install quicksand-agent` | Ubuntu + Python 3.12, uv, build-essential, requests, pyyaml, ddgs, markitdown |
+| `quicksand-cua` | Overlay (`quicksand-agent`) | ~489-500 MB | `quicksand install quicksand-cua` | Agent Sandbox + Xvfb, x11vnc, noVNC, Playwright, Chromium |
+
+Sizes are approximate full image-wheel downloads for the September 14, 2026 releases
+and vary by architecture. Overlay sizes exclude their base images.
## Building from source