[GH-ISSUE #916] feat: Add snapshot and restore functionality for macOS VMs #680

New issue

Closed

opened 2026-02-27 23:01:35 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 23:01:35 +03:00

Owner

Originally created by @dmzoneill on GitHub (Feb 9, 2026).
Original GitHub issue: https://github.com/sickcodes/Docker-OSX/issues/916

Summary

Add built-in snapshot management to save and restore macOS VM states, enabling quick rollback to known-good configurations and faster development/testing workflows.

Motivation

Docker-OSX is extensively used for security research, CI/CD pipelines, and macOS software development. Users frequently need to:

Test potentially destructive operations (security research, malware analysis)
Quickly reset VMs to a clean state for reproducible testing
Save configured environments after lengthy setup processes
Roll back after software updates break functionality
Maintain multiple VM states for different project configurations

Currently, users must either:

Rebuild containers from scratch (time-consuming)
Manually manage QCOW2 snapshots (error-prone, not beginner-friendly)
Use external VM snapshot tools (defeats the simplicity of Docker-based workflow)

Proposed Solution

Implement snapshot management via Docker volume manipulation and QCOW2 internal snapshots:

Create Snapshots
```
docker-osx snapshot create my-vm clean-state-v1 "Fresh macOS install with Xcode"
```
- Save current VM disk state with a named tag
- Store metadata (timestamp, description, macOS version)
- Optionally include RAM state for instant resume

List Snapshots

docker-osx snapshot list my-vm
# Output:
# NAME              CREATED          SIZE     DESCRIPTION
# clean-state-v1    2 hours ago      45 GB    Fresh macOS install with Xcode
# before-update     1 day ago        48 GB    Before macOS 13.2 update
# dev-env           3 days ago       52 GB    All dev tools configured

Restore Snapshots
```
docker-osx snapshot restore my-vm clean-state-v1
```
- Stop running container if active
- Revert disk to snapshot state
- Optionally restore RAM state
- Restart container automatically
Delete Snapshots
```
docker-osx snapshot delete my-vm before-update
```
- Free up disk space by removing old snapshots
- Confirm deletion for safety

Export/Import Snapshots

docker-osx snapshot export my-vm clean-state-v1 -o macos-snapshot.tar.gz
docker-osx snapshot import my-other-vm clean-state-v1 -i macos-snapshot.tar.gz

Share preconfigured VM states across systems
Distribute ready-to-use development environments

Benefits

Security Research: Safely test malware/exploits, instantly restore clean state
CI/CD: Cache fully configured build environments, dramatically reduce pipeline times
Development: Quickly test risky changes, roll back if needed
Education: Distribute preconfigured lab environments to students
Reproducibility: Guarantee consistent testing environments across team members

Technical Considerations

QCOW2 format already supports internal snapshots (qemu-img snapshot)
Could wrap QEMU snapshot commands with Docker-friendly CLI
Metadata could be stored in Docker volume labels or separate JSON files
RAM snapshots would require additional storage but enable instant resume
Snapshot size optimization via QCOW2 compression and deduplication

Example Workflow (Security Research)

# Set up clean macOS environment
docker-osx run --name research-vm big-sur

# Configure tools, install dependencies
# ... (lengthy setup)

# Save clean state
docker-osx snapshot create research-vm baseline "Fully configured research environment"

# Run potentially destructive test
# ... test malware sample ...

# Restore to clean state in seconds
docker-osx snapshot restore research-vm baseline

# Repeat testing cycle rapidly

This feature would significantly enhance Docker-OSX's value for professional workflows while maintaining the simplicity that makes it popular for beginners.

Originally created by @dmzoneill on GitHub (Feb 9, 2026). Original GitHub issue: https://github.com/sickcodes/Docker-OSX/issues/916 ## Summary Add built-in snapshot management to save and restore macOS VM states, enabling quick rollback to known-good configurations and faster development/testing workflows. ## Motivation Docker-OSX is extensively used for security research, CI/CD pipelines, and macOS software development. Users frequently need to: - Test potentially destructive operations (security research, malware analysis) - Quickly reset VMs to a clean state for reproducible testing - Save configured environments after lengthy setup processes - Roll back after software updates break functionality - Maintain multiple VM states for different project configurations Currently, users must either: 1. Rebuild containers from scratch (time-consuming) 2. Manually manage QCOW2 snapshots (error-prone, not beginner-friendly) 3. Use external VM snapshot tools (defeats the simplicity of Docker-based workflow) ## Proposed Solution Implement snapshot management via Docker volume manipulation and QCOW2 internal snapshots: 1. **Create Snapshots** ```bash docker-osx snapshot create my-vm clean-state-v1 "Fresh macOS install with Xcode" ``` - Save current VM disk state with a named tag - Store metadata (timestamp, description, macOS version) - Optionally include RAM state for instant resume 2. **List Snapshots** ```bash docker-osx snapshot list my-vm # Output: # NAME CREATED SIZE DESCRIPTION # clean-state-v1 2 hours ago 45 GB Fresh macOS install with Xcode # before-update 1 day ago 48 GB Before macOS 13.2 update # dev-env 3 days ago 52 GB All dev tools configured ``` 3. **Restore Snapshots** ```bash docker-osx snapshot restore my-vm clean-state-v1 ``` - Stop running container if active - Revert disk to snapshot state - Optionally restore RAM state - Restart container automatically 4. **Delete Snapshots** ```bash docker-osx snapshot delete my-vm before-update ``` - Free up disk space by removing old snapshots - Confirm deletion for safety 5. **Export/Import Snapshots** ```bash docker-osx snapshot export my-vm clean-state-v1 -o macos-snapshot.tar.gz docker-osx snapshot import my-other-vm clean-state-v1 -i macos-snapshot.tar.gz ``` - Share preconfigured VM states across systems - Distribute ready-to-use development environments ## Benefits - **Security Research**: Safely test malware/exploits, instantly restore clean state - **CI/CD**: Cache fully configured build environments, dramatically reduce pipeline times - **Development**: Quickly test risky changes, roll back if needed - **Education**: Distribute preconfigured lab environments to students - **Reproducibility**: Guarantee consistent testing environments across team members ## Technical Considerations - QCOW2 format already supports internal snapshots (`qemu-img snapshot`) - Could wrap QEMU snapshot commands with Docker-friendly CLI - Metadata could be stored in Docker volume labels or separate JSON files - RAM snapshots would require additional storage but enable instant resume - Snapshot size optimization via QCOW2 compression and deduplication ## Example Workflow (Security Research) ```bash # Set up clean macOS environment docker-osx run --name research-vm big-sur # Configure tools, install dependencies # ... (lengthy setup) # Save clean state docker-osx snapshot create research-vm baseline "Fully configured research environment" # Run potentially destructive test # ... test malware sample ... # Restore to clean state in seconds docker-osx snapshot restore research-vm baseline # Repeat testing cycle rapidly ``` This feature would significantly enhance Docker-OSX's value for professional workflows while maintaining the simplicity that makes it popular for beginners.