shoes-vz is a tool suite for creating, running, and destroying ephemeral macOS VMs as GitHub Actions self-hosted runners on macOS 26+ (Apple Silicon) using Code-Hex/vz (Go bindings for Apple Virtualization Framework).
shoes-vz minimizes VM startup time to SSH-ready state by leveraging APFS Copy-on-Write (clone) for instant runner replication from templates.
- Fast SSH Ready: Unified startup completion condition based on successful SSH connection
- Ephemeral Runners: Fully isolated VM instances per runner
- CoW-based Fast Cloning: Instant template replication using APFS clone
- macOS 26+ Native: Leverages latest Virtualization.framework capabilities
- gRPC-centric Design: GUI-independent, gRPC integration with myshoes
shoes-vz consists of three components:
- gRPC integration with myshoes
- Agent management (registration, health monitoring)
- Runner scheduling
- Aggregated runner state management
- Virtualization.framework control (via vz)
- Template management (cloning)
- VM lifecycle management
- State synchronization with server
- GitHub Actions Runner state monitoring
- HTTP API for state exposure
- Automatic IP address notification to host
- Command execution via HTTP requests from host
- Setup Guide - Installation and configuration steps for each component
- Image Build Guide - Instructions for creating VM templates (Golden Images)
- Design Document - Detailed architecture and design explanation
- AGENTS.md - Developer guide with build instructions, API reference, and troubleshooting
# Install dependencies and build
make deps
make build
# See AGENTS.md for detailed build instructions, running examples, and development workflow- macOS 26+ (Apple Silicon)
- APFS filesystem
- Virtualization.framework permissions
- macOS 13+
- GitHub Actions Runner
- shoes-vz-runner-agent
- Code-Hex/vz - Go bindings for Apple Virtualization Framework
- prometheus/client_golang - Prometheus metrics
- grpc/grpc-go - gRPC implementation
MIT