Quickly sandbox your AI agent.
Python
Add guest-user example and changelog badge to README
Tyler Payneaadbb46a645d
diff --git a/README.md b/README.mdindex 56e720d..921a411 100644--- a/README.md+++ b/README.md@@ -1,6 +1,7 @@# Quicksand[](https://pypi.org/project/quick-sandbox/)+[](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md)[](https://microsoft.github.io/quicksand/)[](LICENSE)@@ -8,14 +9,6 @@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```bash@@ -52,6 +45,25 @@ result = await sb.execute("apt update && apt install -y python3")print(result.stdout, result.exit_code)```+### Create guest users++Give workloads their own Linux accounts and home directories inside one VM.+Commands run with the user's identity and default to their home directory.++```python+async with Sandbox(image="ubuntu") as sb:+ alice = await sb.create_user("alice")+ await alice.execute("cat > hello.txt", stdin="Hello from Alice!\n")++ result = await alice.execute("whoami && pwd && cat hello.txt")+ print(result.stdout)++ await sb.delete_user("alice") # Also removes the user's home directory+```++Users share one VM, not separate VM isolation boundaries. Requires Ubuntu or+Alpine image packages 0.10.0 or newer, or a custom image with the updated guest agent.+### Mount host directoriesShare host directories into the VM at boot or on the fly.diff --git a/docs/contributor-guide/04-releasing.md b/docs/contributor-guide/04-releasing.mdindex 5a2659f..403d6a9 100644--- a/docs/contributor-guide/04-releasing.md+++ b/docs/contributor-guide/04-releasing.md@@ -73,8 +73,7 @@ failure normally requires a fresh dispatch.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 root README's GitHub release badge links to the changelog and updates its+version automatically after publication.The `sync-readme` pre-commit hook copies the root README to`packages/quicksand/README.md` for the package description.diff --git a/packages/quicksand/README.md b/packages/quicksand/README.mdindex 56e720d..921a411 100644--- a/packages/quicksand/README.md+++ b/packages/quicksand/README.md@@ -1,6 +1,7 @@# Quicksand[](https://pypi.org/project/quick-sandbox/)+[](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md)[](https://microsoft.github.io/quicksand/)[](LICENSE)@@ -8,14 +9,6 @@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```bash@@ -52,6 +45,25 @@ result = await sb.execute("apt update && apt install -y python3")print(result.stdout, result.exit_code)```+### Create guest users++Give workloads their own Linux accounts and home directories inside one VM.+Commands run with the user's identity and default to their home directory.++```python+async with Sandbox(image="ubuntu") as sb:+ alice = await sb.create_user("alice")+ await alice.execute("cat > hello.txt", stdin="Hello from Alice!\n")++ result = await alice.execute("whoami && pwd && cat hello.txt")+ print(result.stdout)++ await sb.delete_user("alice") # Also removes the user's home directory+```++Users share one VM, not separate VM isolation boundaries. Requires Ubuntu or+Alpine image packages 0.10.0 or newer, or a custom image with the updated guest agent.+### Mount host directoriesShare host directories into the VM at boot or on the fly.