Skip to content

Quickly sandbox your AI agent.

Python

Add guest-user example and changelog badge to README

Tyler Payneaadbb46a645d
diff --git a/README.md b/README.md
index 56e720d..921a411 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
# Quicksand
[![PyPI](https://img.shields.io/pypi/v/quick-sandbox)](https://pypi.org/project/quick-sandbox/)
+[![Changelog](https://img.shields.io/github/v/release/microsoft/quicksand?label=changelog&logo=github)](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md)
[![Docs](https://img.shields.io/badge/docs-quicksand-blue)](https://microsoft.github.io/quicksand/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](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 directories
Share 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.md
index 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.md
index 56e720d..921a411 100644
--- a/packages/quicksand/README.md
+++ b/packages/quicksand/README.md
@@ -1,6 +1,7 @@
# Quicksand
[![PyPI](https://img.shields.io/pypi/v/quick-sandbox)](https://pypi.org/project/quick-sandbox/)
+[![Changelog](https://img.shields.io/github/v/release/microsoft/quicksand?label=changelog&logo=github)](https://github.com/microsoft/quicksand/blob/main/CHANGELOG.md)
[![Docs](https://img.shields.io/badge/docs-quicksand-blue)](https://microsoft.github.io/quicksand/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](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 directories
Share host directories into the VM at boot or on the fly.