Getting Started
From first download to a running CI pipeline in seven steps. No prior experience required.
Download & Install
Install Spooktacular on your Mac. Takes about 30 seconds.
Download Spooktacular v1.0.0 macOS 14+ · Apple Silicon · 25 MBDrag Spooktacular.app to your Applications folder and launch it.
spook command-line tool:brew install spooktacular (planned)
Create Your First VM
Create a fresh macOS virtual machine with one command. It pulls the latest IPSW and installs it automatically.
$ spook create my-first-vm --from-ipsw latest ✓ Downloading macOS 15.4 Sequoia (13.2 GB)... ✓ Installing macOS into virtual machine... ✓ Automating Setup Assistant... ✓ VM "my-first-vm" created successfully # Total time: ~15-20 minutes (mostly IPSW download)
What just happened?
Spooktacular downloaded the latest macOS restore image (IPSW) from Apple, installed it into a Virtualization.framework VM, and ran through Setup Assistant automatically. Your VM is ready to use -- no manual configuration required.
Clone a VM
Create an identical copy of your base VM. APFS copy-on-write makes this nearly instant.
$ spook clone my-first-vm runner-01 ✓ Cloned "my-first-vm" → "runner-01" (48ms) ✓ New machine identity assigned ✓ Disk: copy-on-write (shared blocks, ~0 bytes additional)
Why is it so fast?
APFS copy-on-write cloning shares disk blocks between the source and the clone. Only modified blocks consume additional storage. A fresh clone takes 48 milliseconds and starts at approximately zero additional disk usage. Each clone gets a unique machine identity so it appears as a distinct Mac.
Run Your CI Pipeline
Turn your clone into a GitHub Actions runner with a single command. It registers, connects, and starts polling for jobs.
$ spook start runner-01 --headless --github-runner \ --github-repo your-org/your-repo \ --github-token ghp_xxx ✓ Starting "runner-01" in headless mode... ✓ GitHub Actions runner provisioned ✓ Connected to your-org/your-repo ✓ Polling for jobs...
What's happening inside?
Spooktacular boots the VM without a display, installs the GitHub Actions runner agent via SSH provisioning, registers it with your repository using the provided token, and starts polling for workflow jobs. Your runner is now connected to your CI pipeline -- jobs will be picked up automatically.
Double Your Capacity
Apple Silicon supports 2 VMs per Mac. Clone another runner and run both simultaneously. Ephemeral mode auto-destroys after each job for a clean slate.
$ spook clone my-first-vm runner-02 ✓ Cloned "my-first-vm" → "runner-02" (48ms) $ spook start runner-02 --ephemeral --github-runner \ --github-repo your-org/your-repo \ --github-token ghp_xxx ✓ Starting "runner-02" in ephemeral mode... ✓ Runner will self-destruct after one job ✓ Connected and polling...
Why ephemeral?
Ephemeral runners auto-destroy after completing a single job. This guarantees a pristine environment for every CI run -- no leftover state, no cache poisoning, no stale artifacts from previous builds. Spooktacular re-clones from your base image before the next job.
Run as a Service
Make your runner survive reboots and run headless in the background. Install it as a system service and forget about it.
$ sudo spook service install runner-01 ✓ Created launchd service: com.spooky-labs.spooktacular.runner-01 ✓ Service enabled (starts on boot) ✓ Runner-01 is now a persistent service # Manage the service $ spook service status runner-01 # check status $ spook service stop runner-01 # stop service $ spook service uninstall runner-01 # remove service
What does this do?
This installs a launchd plist that starts your runner automatically when the Mac boots. The VM runs headless in the background -- no display, no logged-in user required. Your runner persists through power cycles and macOS updates.
Remote Control
Use the guest agent to interact with your VM without SSH or screen sharing. The spook remote command talks to the agent over VirtIO socket.
# Check agent health $ spook remote health runner-01 ✓ Agent v1.0.0 — uptime 4h32m # Execute a command inside the VM $ spook remote exec runner-01 -- "sw_vers" ProductName: macOS ProductVersion: 15.4 BuildVersion: 24E5xxx # Read the guest clipboard $ spook remote clipboard get runner-01 hello world # List running applications $ spook remote apps runner-01 Xcode (16.3) Finder Terminal Safari
What's the guest agent?
The guest agent is a lightweight daemon that runs inside the VM and exposes 12 HTTP endpoints over VirtIO socket. It enables clipboard sync, remote command execution, app control, file transfer, port discovery, and health monitoring -- all without SSH or network access. The host-side GuestAgentClient actor in SpooktacularKit provides a type-safe Swift API for all endpoints.