feat: Add Quicksand (QEMU-based VM) backend support for MXC
- Dominant language
- Rust
- Stars
- 1.3k
- Forks
- 79
- Avg merge
- 2d 7h
- Merged PRs (30d)
- 117
Description
### Description of the new feature / enhancement
MXC (Microsoft eXecution Container) currently supports multiple containment backends, including ProcessContainer, Windows Sandbox, LXC, Bubblewrap, Seatbelt (macOS), MicroVM (NanVix), Hyperlight, IsolationSession, and WSLC. However, the existing backends mainly focus on process‑level containers or lightweight VM solutions.
[Quicksand](https://github.com/microsoft/quicksand) is an open‑source asynchronous Python API from Microsoft for launching, controlling, and snapshotting QEMU virtual machines, with a specific focus on sandboxing for AI agents. It provides pre‑built Linux VM images (Ubuntu and Alpine), supports x86_64 and ARM64 architectures, runs across macOS, Linux, and Windows, and **requires no root privileges, no Docker, and no system dependencies** – just `pip install quick-sandbox`.
Currently, there is no direct integration between MXC and Quicksand. Developers who want to use Quicksand’s QEMU‑based isolation capabilities within MXC’s policy‑driven framework must write custom glue code, missing out on MXC’s unified JSON configuration specification and TypeScript SDK.
Additionally, Quicksand offers features that are not fully covered by existing MXC backends:
- **Snapshot and rollback**: capture the full VM state and revert on experiment failure.
- **Desktop environment control**: supports Xfce4 graphical environment, enabling screenshots, keyboard input, mouse control, etc.
- **Dynamic mounting**: mount/unmount host directories inside a running sandbox on the fly.
- **Cross‑machine state migration**: save VM disk state to a directory and load it on different machines.
Bringing these capabilities under MXC’s unified backend framework would provide richer options for secure AI agent isolation scenarios.
This proposal suggests adding **Quicksand** as a new containment backend for MXC, allowing developers to use Quicksand’s QEMU‑based virtual machine sandboxing through MXC’s unified JSON configuration and TypeScript SDK.
Users will be able to:
1. **Use Quicksand via MXC JSON configuration**:
```json
{
"backend": "quicksand",
"image": "ubuntu",
"memory": "2G",
"cpus": 4,
"network_mode": "full",
"mounts": [{ "host": "./workspace", "guest": "/mnt/workspace" }]
}
```
2. **Use Quicksand programmatically via MXC TypeScript SDK**:
```typescript
const sandbox = await mxc.createSandbox({
backend: 'quicksand',
image: 'ubuntu',
memory: '2G',
cpus: 4,
});
```
3. **Leverage Quicksand‑specific capabilities**:
- Snapshot & rollback: `await sandbox.checkpoint('before-experiment')` / `await sandbox.revert('before-experiment')`
- Desktop control: screenshots, keyboard input, mouse control
- Dynamic mounts: mount/unmount host directories at runtime
- State persistence and cross‑machine loading
4. **Unified policy enforcement**: Under MXC’s policy‑driven framework, administrators can define filesystem policies (read/write path lists), network policies (allow/block outbound), and UI policies (clipboard, display, GUI access control) for Quicksand VMs.
### Proposed technical implementation details
### Architecture Design
Following the existing MXC backend patterns (e.g., `processcontainer`, `bubblewrap`, `lxc`, `seatbelt`), a new `quicksand` backend would be added:
1. **Backend adapter layer**: Implement the MXC backend interface, wrapping Quicksand’s Python API calls.
- Quicksand provides an asynchronous Python API, which can be invoked via a subprocess or embedded Python interpreter.
- Must implement the MXC lifecycle interface: `provision` → `start` → `exec` → `stop` → `deprovision`.
2. **Configuration mapping**:
- MXC JSON configuration → Quicksand `Sandbox()` constructor parameters.
- Filesystem policies → Quicksand `mounts` parameter.
- Network policies → Quicksand `network_mode` and `port_forwards` parameters.
- Resource limits → Quicksand `memory` and `cpus` parameters.
3. **Platform support**:
- Quicksand already supports x86_64 and ARM64 on macOS, Linux, and Windows.
- On Windows, it leverages WHPX acceleration.
- Aligns with MXC’s existing cross‑platform strategy.
4. **Dependency management**:
- Core dependency: `pip install quick-sandbox`.
- QEMU and VM images can be installed via commands like `quicksand install qemu alpine`.
- These dependencies need to be handled in MXC’s build/installation process.
5. **Experimental flag**:
- Following MXC’s handling of experimental backends (`windows_sandbox`, `wslc`, `microvm`, etc.), the Quicksand backend can initially be marked as experimental, requiring `{ experimental: true }` or the `--experimental` flag to enable.
### Implementation Steps
1. Register the `quicksand` backend in MXC’s backend registry.
2. Implement the Quicksand backend lifecycle management (provision/start/exec/stop/deprovision).
3. Implement mapping of MXC policies (filesystem, network, UI) to Quicksand configurations.
4. Add TypeScript SDK type definitions and API support.
5. Write integration tests and documentation.
6. (Optional) Provide pre‑configured MXC policy templates for Quicksand images.
Contributor guide
Assessment
This issue has not been assessed yet.