cove

package module

v0.0.0-...-427221a Latest Latest Go to latest Published: Jun 28, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tmc/cove

Links

Open Source Insights

README ¶

cove

macOS VMs that suspend, snapshot, and script.

cove is a CLI for creating and managing macOS and Linux virtual machines on Apple Silicon using Apple's Virtualization.framework. Pure Go, cgo-free (purego).

New to cove? Start with the safe first-run flow:

cove first-run
cove doctor host
cove up -user myuser

cove up installs, provisions, and boots a first VM. It prompts for the guest account password when you omit -password, which keeps secrets out of shell history.

Install

Install from source for now:

go install github.com/tmc/cove/cmd/cove@latest

The Homebrew formula is not the recommended first-run path yet.

After installing, check the host before creating a VM:

cove doctor host

See INSTALL.md for first-run requirements, IPSW reuse, and the macOS virtualization license note.

Quick Start

cove up -user myuser                    # install, provision, and boot

Or step by step:

cove doctor host                        # check this Mac first
cove install                            # download IPSW and install macOS
cove provision -user myuser             # provision user, skip Setup Assistant
cove run                                # boot with native GUI window

On first launch, cove auto-signs itself with the required Virtualization.framework entitlements. No manual codesign step is needed for normal installs.

Common Commands

cove first-run                          # show the first-run checklist
cove doctor host                        # host readiness check
cove list                               # list VMs
cove status -vm my-vm                   # VM and guest-agent status
cove ctl -vm my-vm agent-status         # detailed agent status
cove logs my-vm                         # guest logs
cove support bundle                     # redacted host diagnostics
cove support bundle -vm my-vm           # include VM diagnostics

Use cove help advanced for the full command list.

License and Apple Virtualization Limits

cove is MIT-licensed. macOS guests still run under Apple's macOS Software License Agreement: the current macOS Tahoe 26 SLA section 2B(iii) permits up to two additional virtualized macOS instances on each Apple-branded computer you own or control, for the listed development, testing, macOS Server, or personal non-commercial purposes. Cove does not bypass or expand that Apple limit; fleet capacity is hardware capacity.

This is a product note, not legal advice. Read the applicable Apple SLA for the macOS version you run: https://www.apple.com/legal/sla/. See License and Virtualization Limits for the cove, Lume, Tart, Orchard, and tart-guest-agent comparison.

Features

Suspend and Resume

VMs suspend to disk on quit and resume where they left off. Cold boot with -no-resume.

Snapshots

VM state snapshots and APFS copy-on-write disk snapshots. Checkpoint before risky changes, restore in seconds.

cove disk-snapshot save before-update
cove disk-snapshot restore before-update

VZScript Engine

Declarative recipes for guest VM configuration. Built on rsc.io/script with guest-agent and OCR commands.

cove vzscript list                      # list built-in recipes
cove vzscript run homebrew golang       # install Homebrew, then Go (deps resolved)
cove vzscript run ./custom.vzscript     # run a custom script

Guest commands: guest-exec, guest-shell, guest-cp, guest-write, guest-read. UI commands: ocr-click, ocr-wait, type, key, click, screenshot.

SIP Management

Disable or enable System Integrity Protection with automated recovery boot.

cove sip disable-auto -user admin -password <password> -confirm
cove run -recovery -gui -unattended -boot-commands ~/.vz/vms/default/sip-disable.vzscript

Guest Agent

A vsock gRPC agent injected into the guest at install time. Execute commands, transfer files, manage proxy settings, share clipboard -- all without SSH.

cove run -clipboard -proxy http://192.168.64.1:8080

Agent Sandbox

Run OpenAI, Anthropic, Gemini, or Vertex computer-use loops against fresh local VM forks with replay artifacts and provider auth checks.

cove agent-sandbox doctor --provider all
cove agent-sandbox run --provider anthropic --image agentkit/macos-base:latest --task "Describe the desktop."

Start with the quickstart, then use the provider matrix, cookbook, and benchmark harness.

Native GUI Window

macOS-native window with toolbar, menu bar, and frame persistence per VM. Multi-display support with resolution presets. When a GUI VM is running, cove also shows a macOS status item with the VM state and quick actions for the window and clean shutdown.

cove run -display 4k
cove run -display 1920x1080 -display 1024x768

Linux VMs

Ubuntu Server with cloud-init automated install. EFI boot, Virtio GPU, serial console, Rosetta x86-64 translation.

cove install -linux
cove run -linux -gui -rosetta

Shared Folders

VirtioFS volume mounts with runtime hot-add.

cove run -share ~/projects -share /data:ro

Usage Examples

One-Command Setup

# Install, provision, and boot with vzscripts
cove up -user dev -vzscripts homebrew,golang

Headless CI Runner

cove install -ipsw ~/cache/restore.ipsw
cove provision -user ci -skip-setup-assistant  # prompts for password
cove run -headless -cpu 4 -memory 8

Self-hosted GitHub Actions or GitLab runner inside a long-lived VM:

read -rsp 'GitHub runner registration token: ' GH_TOKEN
export GH_REPO=tmc/cove GH_TOKEN
cove vzscript run github-runner

RUNNER_REINSTALL=1 cove vzscript run github-runner

read -rsp 'GitLab runner registration token: ' GITLAB_TOKEN
export GITLAB_URL=https://gitlab.com GITLAB_TOKEN
cove vzscript run gitlab-runner

Runner registration tokens are secrets. Avoid pasting real values into shell history; use a prompt, keychain lookup, or CI secret variable instead.

Cirrus Task Migration

This is an advanced workflow. Get a local VM working first with cove first-run.

From the cove checkout:

cove action doctor
cove image verify --strict --newer-than 168h macos-runner:latest
cove action prepare-image macos-runner:latest --ttl 24h
go run ./cmd/cove-action -image macos-runner:latest -command './ci/test.sh'

Use Quickstart from Cirrus for the five-step path and Migrating from Cirrus CI to cove for container, macOS, persistent-worker, and matrix examples.

Tailscale Mesh Access

TS_AUTHKEY=tskey-auth-... cove vzscript run tailscale
# VM joins your tailnet with --ssh; reach it from anywhere.

Control a Running VM

cove ctl -vm default status
cove ctl -vm default screenshot -o screen.jpg
cove ctl -vm default agent-status

The raw Unix-socket protocol is documented in Control API for integrations that cannot use cove ctl.

Recovery and SIP

cove sip disable-auto -user admin -password <password> -confirm
cove run -recovery -no-resume -gui -unattended \
  -usb ~/.vz/vms/default/recovery-disk.img \
  -boot-commands ~/.vz/vms/default/sip-disable.vzscript

Architecture

cove uses Apple's Virtualization.framework through purego for cgo-free Objective-C interop. VMs are stored in ~/.vz/vms/<name>/ with disk images, identity files, and a Unix domain control socket.

Project Structure

cove/
├── cmd/cove/                   # cove CLI command
│   └── main.go                 # CLI entry point, subcommand routing
├── cmd/vz-agent/               # In-guest agent daemon (vsock gRPC)
├── cmd/coved/                  # Host-side cove coordinator daemon
├── cmd/cove-fleetd/            # Private fleet control-plane daemon
├── vzscripts/                  # Built-in recipes (.vzscript)
├── templates/                  # Embedded launchd and provisioning templates
├── proto/                      # Protobuf definitions (agent + control)
├── internal/                   # Reusable implementation packages
├── docs/                       # Guides, design notes, and release material
└── swift/VZControl/            # Swift package for control socket client

Requirements

Apple Silicon Mac (M1/M2/M3/M4)
macOS 14.0+ (Sonoma or later)
Xcode Command Line Tools

Feature Maturity

Maturity	Features
GA	install, run (auto-suspend on quit, resume on next run), provisioning (inject), vzscripts
Beta	snapshots, guest agent, clipboard sharing, shared folders, Linux guests, OCI push/pull, VM fork/restore, `cove compact`, local content-addressed store, `cove build` for local VM-directory and registry bases (cache-aware execution, OCI cache import/export, `# secret:` tmpfs, compaction)
Experimental	UTM import, memory balloon, Windows stub

Security

Control socket: per-VM bearer token, owner-only permissions (0600)
Guest agent: unencrypted gRPC over vsock, scoped to host-VM boundary
Entitlements: auto-signed on first launch with com.apple.security.virtualization and local networking entitlements
Safety posture: see SAFETY.md for trust boundaries, known limitations, and audit guidance.

Contributing

git clone https://github.com/tmc/cove
cd cove
go build -o cove ./cmd/cove
./cove run

Run tests:

go test -short ./...
make release-check    # vet + test + goreleaser snapshot

License

MIT -- see LICENSE.

References

Apple Virtualization Framework
purego
Code-Hex/vz (CGO reference implementation)

Documentation ¶

Index ¶

Variables

Constants ¶

This section is empty.

Variables ¶

View Source

var AgentLaunchAgentPlist string

View Source

var AgentLaunchDaemonPlist string

View Source

var AutoLoginLaunchDaemonPlist string

View Source

var AutoLoginScriptTmpl string

View Source

var CovedPlistTemplate string

View Source

var ProvisionLaunchDaemonPlist string

View Source

var ProvisionScriptTmpl string

View Source

var VZScripts embed.FS

Functions ¶

This section is empty.

Types ¶

This section is empty.

Source Files ¶

View all Source files

assets.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
agentsandbox
bench
fork-time/fork-bench command fork-bench measures cove fork latency against existing local VMs.	fork-bench measures cove fork latency against existing local VMs.
soft-reset/matrix command soft-reset-matrix renders the soft-reset isolation test matrix.	soft-reset-matrix renders the soft-reset isolation test matrix.
cmd
cove command Command cove manages macOS and Linux virtual machines with Apple's Virtualization framework.	Command cove manages macOS and Linux virtual machines with Apple's Virtualization framework.
cove-action command
cove-fleetd command cove-fleetd is the fleet control-plane process.	cove-fleetd is the fleet control-plane process.
coved command coved is the host-side cove coordinator daemon.	coved is the host-side cove coordinator daemon.
vz-agent command vz-agent is a guest agent daemon for VMs managed by cove.	vz-agent is a guest agent daemon for VMs managed by cove.
examples
agent-loop-5-lines command
internal
action Package action implements the cove action subcommands that prepare hosts and images for cove-action runs.	Package action implements the cove action subcommands that prepare hosts and images for cove-action runs.
agent agent_client.go - Host-side connect-go client for the guest agent.	agent_client.go - Host-side connect-go client for the guest agent.
agentsandbox Package agentsandbox runs cove computer-use provider adapters.	Package agentsandbox runs cove computer-use provider adapters.
anthropicadapter Package anthropicadapter runs Anthropic computer-use loops against cove.	Package anthropicadapter runs Anthropic computer-use loops against cove.
assets Package assets embeds static resources for cove.	Package assets embeds static resources for cove.
bench Package bench builds cove benchmark reports from checked-in run artifacts.	Package bench builds cove benchmark reports from checked-in run artifacts.
builddigest Package builddigest contains digest helpers for cove build cache inputs.	Package builddigest contains digest helpers for cove build cache inputs.
buildmeta Package buildmeta parses metadata comments in cove build scripts.	Package buildmeta parses metadata comments in cove build scripts.
buildpaths Package buildpaths contains host path helpers shared by build flows.	Package buildpaths contains host path helpers shared by build flows.
buildscratch
bytefmt Package bytefmt formats and parses byte counts.	Package bytefmt formats and parses byte counts.
control Package control owns the VM control socket edge.	Package control owns the VM control socket edge.
control/operations Package operations tracks long-running control operations.	Package operations tracks long-running control operations.
controlclient control_client.go - Programmatic client for VM control socket	control_client.go - Programmatic client for VM control socket
controlserver AgentBridge owns the agent clients, the connection mutex protecting them, and the proactive health-monitor state.	AgentBridge owns the agent clients, the connection mutex protecting them, and the proactive health-monitor state.
covecli
coved Package coved contains host-side daemon services.	Package coved contains host-side daemon services.
diskimages2 Package diskimages2 provides convenience wrappers around the generated DiskImages2 framework bindings.	Package diskimages2 provides convenience wrappers around the generated DiskImages2 framework bindings.
disposable
filehandle
fleet Package fleet stores remote cove host registrations.	Package fleet stores remote cove host registrations.
fleetcontrol
guestplan
imagestore Package imagestore defines local image-store paths and references.	Package imagestore defines local image-store paths and references.
lifecycle Package lifecycle enforces per-VM run-budget limits.	Package lifecycle enforces per-VM run-budget limits.
metrics Package metrics: redact.go - secret-value masker for run logs.	Package metrics: redact.go - secret-value masker for run logs.
nixos Package nixos renders and validates the NixOS guest installer inputs used by cove.	Package nixos renders and validates the NixOS guest installer inputs used by cove.
ociimage Package ociimage defines cove's OCI VM image metadata conventions.	Package ociimage defines cove's OCI VM image metadata conventions.
password password.go - macOS password hash and auto-login support	password.go - macOS password hash and auto-login support
pcap Package pcap writes classic libpcap captures with the Ethernet link type.	Package pcap writes classic libpcap captures with the Ethernet link type.
provision Package provision describes staged macOS guest provisioning files.	Package provision describes staged macOS guest provisioning files.
runs Package runs reads and renders cove-action run records from the metrics event log.	Package runs reads and renders cove-action run records from the metrics event log.
sckit Package sckit probes the host for ScreenCaptureKit availability and exposes a single-window capture entry point used by design 041.	Package sckit probes the host for ScreenCaptureKit availability and exposes a single-window capture entry point used by design 041.
secrets Package secrets resolves secret URI references for cove configuration.	Package secrets resolves secret URI references for cove configuration.
softreset Package softreset runs empirical probes that test whether a host soft-reset (without fork/restore) leaves no residue across runs.	Package softreset runs empirical probes that test whether a host soft-reset (without fork/restore) leaves no residue across runs.
storagecensus Package storagecensus walks ~/.vz/ once and reports per-category disk usage.	Package storagecensus walks ~/.vz/ once and reports per-category disk usage.
storagepins Package storagepins persists operator-supplied "keep this" markers for objects under ~/.vz/.	Package storagepins persists operator-supplied "keep this" markers for objects under ~/.vz/.
store Package store is cove's content-addressed blob store for OCI image layers and manifests.	Package store is cove's content-addressed blob store for OCI image layers and manifests.
version Package version resolves build and runtime version strings.	Package version resolves build and runtime version strings.
vmconfig Package vmconfig loads and saves cove VM configuration files.	Package vmconfig loads and saves cove VM configuration files.
vmidentity Package vmidentity reads and writes the host-side identity files that Virtualization.framework binds into saved macOS VM state.	Package vmidentity reads and writes the host-side identity files that Virtualization.framework binds into saved macOS VM state.
vmpolicy Package vmpolicy persists per-VM lifecycle stop thresholds.	Package vmpolicy persists per-VM lifecycle stop thresholds.
vmquota Package vmquota persists and applies per-VM resource quotas.	Package vmquota persists and applies per-VM resource quotas.
vmrun Package vmrun describes the configuration of a single VM run or install as plain data.	Package vmrun describes the configuration of a single VM run or install as plain data.
vmstate Package vmstate normalizes Virtualization.framework VM state labels.	Package vmstate normalizes Virtualization.framework VM state labels.
vmtree
vsock Package vsock documents cove's host-guest virtio socket conventions.	Package vsock documents cove's host-guest virtio socket conventions.
windows Package windows builds Windows ARM64 install media helpers.	Package windows builds Windows ARM64 install media helpers.
windows/esd Package esd selects and downloads Windows Electronic Software Download images.	Package esd selects and downloads Windows Electronic Software Download images.
proto Package proto contains protocol buffer definitions for cove.	Package proto contains protocol buffer definitions for cove.
agentpb
agentpbconnect
controlpb