| name | choose-macos-virtualization-shape |
| description | Choose the smallest macOS-hosted boundary for development, compatibility, or authorized security research. Use when deciding among the host, containers, container machine, full Linux or macOS VMs, remote systems, or physical Macs. |
Choose macOS Virtualization Shape
Purpose
Choose one boundary from evidence about fidelity, persistence, portability, host integration, threat level, and resources. Produce the shared shape record in virtualization-shape-record.md; do not return an undecided product menu.
When To Use
- Use for macOS-hosted development, clean-state validation, Linux compatibility, custom VM tools, and security-lab boundary selection.
- Use when container, persistent Linux machine, full VM, and physical Mac terminology is being mixed.
- Use before
virtualization-framework-workflow, either development-VM workflow, or prepare-isolated-analysis-lab when the boundary is not already approved.
Single-Path Workflow
- Record the purpose, host, target OS and architecture, GUI/headless needs, privileges, kernel/devices, expected lifetime, and evidence requirements.
- Classify fidelity and risk:
- trusted native macOS behavior: host process
- one portable Linux application: OCI container
- Apple-native per-container VM runtime: Apple
container
- persistent OCI-backed Linux environment with services:
container machine
- custom kernel, boot, disk, full-system, or GUI Linux: full Linux VM
- native macOS security, installer, signing, privacy, or OS-version behavior: macOS VM
- hardware, recoveryOS, Secure Enclave, unsupported device, performance, or anti-VM behavior: physical Mac
- Reject any option that cannot reproduce the target or safely bound the expected behavior.
- Choose one primary boundary and one explicit fallback only when a named fidelity or availability gap requires it.
- Complete the shape record with provenance, resources, integrations, lifecycle, validation, evidence, and uncertainty.
- Hand off implementation or operation to the owner skill.
Inputs
- Task purpose and target behavior.
- Host chip, macOS build, memory, storage, and toolchain.
- Guest OS/version/distro, architecture, devices, privilege, and lifetime.
- Portability, persistence, integration, isolation, and evidence requirements.
Outputs
status: success, handoff, or blocked.- One selected
boundary and the reason it is the smallest adequate choice.
- A completed virtualization shape record.
- One owner handoff and any unresolved fidelity gap.
Guards and Stop Conditions
- Do not call a Linux container or Linux VM evidence for native macOS behavior such as Gatekeeper, TCC, XProtect, LaunchServices, or macOS persistence.
- Do not treat automatic home sharing, clipboard, credentials, or sockets as harmless defaults.
- Do not claim two products have equivalent isolation because they use the same framework.
- Do not promise saved VM state is a disk snapshot or portable clone.
- Stop when target fidelity, host capacity, authorization, or safe evidence handling cannot be established.
- Tell Gale before launching a GUI VM, starting a VM or container service, downloading a restore image, creating a large disk, or running a resource-intensive workload.
Fallbacks and Handoffs
- Use
server-side-swift:docker-workflow for portable OCI authoring and deployment.
- Use
server-side-swift:apple-containerization-workflow for Apple container, container machine, or Containerization APIs.
- Use
virtualization-framework-workflow for custom VM host implementation.
- Use
linux-development-vm-workflow or macos-development-vm-workflow for guest lifecycle work.
- Use
cybersecurity-skills:select-analysis-isolation and prepare-isolated-analysis-lab for untrusted material.
- Escalate to a physical Mac with the unresolved gap stated when VM fidelity is insufficient.
Customization
Use customization-flow.md. The first release has no runtime-enforced knobs.
References
