Caker

Virtualization platform for macOS

View project on GitHub

Command Summary

This page summarizes the ArgumentParser commands implemented in:

  • Sources/caked/Commands
  • Sources/cakectl/Commands

Command model

  • caked is the local daemon/hypervisor command surface.
  • cakectl is the gRPC client command surface.
  • Most VM/image/network operations exist on both sides with similar names.

Common command groups (caked and cakectl)

VM lifecycle and execution

  • build — create a VM from a cloud image, downloading and converting it as needed; cloud-init runs on first boot.
  • launch — build and start a VM.
  • spawn (alias: create-from-disk) — create a VM from an existing root disk (raw image file or physical block device) without cloud-init. See Spawning from an existing disk.
  • spawn-start — same as spawn, then immediately start the VM.
  • start / stop / restart / suspend — control VM runtime state.
  • delete / duplicate / rename / configure — manage VM lifecycle and configuration.
  • list / infos / waitip — inspect VM inventory, details, and IP readiness.
  • exec / sh — execute commands in guest VM context.
  • mount / umount — manage VM mounts.
  • vnc — open a native VNC client window connected to a running VM’s display.

Images and registries

  • image group: list, info, pull.
  • pull / push — transfer VM images.
  • login / logout — registry authentication.
  • remote group: add, delete, list.
  • template group: create, delete, list.
  • purge — cleanup caches/images according to retention/budget options.

Networks

  • networks group: infos, list, create, configure, delete, start, stop.
  • The default network (formerly nat / NAT shared network; the old names are only normalized to default in a VM’s network attachments) is a caked-managed shared network without isolation between VMs. It is reserved: create, configure and delete reject it. Its CIDR is set in Settings > Advanced (local.default-network, applied at the next restart).
  • create/configure accept --dns: the process running the network then starts the compose DNS resolver on the network’s gateway, see Compose. On by default for default. In the direct-download build the resolver is the network’s main DNS server (port 53, other names forwarded to the host’s resolvers); in the App Store build it listens on port 28053 only.
  • In the direct-download build, a shared or host network run by root (macOS 26+) is served by caked’s own DHCP server instead of vmnet’s, with its own lease table in <CAKE_HOME>/net/<name>/dhcpd_leases; --dhcp-lease is then that network’s lease time. CAKED_VMNET_DHCP=vmnet keeps vmnet’s DHCP. See Compose.
  • stop refuses to stop a network that at least one running VM is using (infos/list distinguish instances that reference it from instances that actively use it).

Compose

  • compose group: up, down, ps, rm, ls, init, library. Manage multi-VM stacks defined in a compose.yml file. See Compose for full reference.
    • up [-f file] [--wait-ip-timeout N] [services...] — create and start services in depends_on order.
    • down [-f file] [--force] [services...] — stop services in reverse order.
    • ps [-f file] [services...] — show service status.
    • rm [-f file] [--stop] [--force] [services...] — remove service VMs and unregister the project.
    • ls — list all registered compose projects (cakectl only).
    • init [-f/--force] — write a commented compose.yml template in the current directory.
    • library [list|show|clone|sync] — library of compose.yml templates (local, does not go through caked); see Compose.

.cakerenv environments

  • init, up, down (top-level commands, not to be confused with compose init/up/down). Manage the development VM(s) described by a .cakerenv file at a project’s root. See .cakerenv environments for the file format.
    • init [-f/--force] — write a commented .cakerenv template in the current directory.
    • up [-f/--env-file path] [--wait-ip-timeout N] [vm...] — create missing VMs and start the others, in depends-on order.
    • down [-f/--env-file path] [--force] [vm...] — stop VMs in reverse order.

Updates

  • check-update — tell whether a Caker release newer than the installed one is published, by reading the same feed (Sparkle appcast) as Caker.app’s “Check for Updates…”, on the same channel (appcast.xml or appcast-prerelease.xml). It only reports: caked and cakectl ship inside Caker.app, so install the new release (or use “Check for Updates…”) to update all three. It runs locally: cakectl check-update doesn’t ask the connected caked, so run caked check-update on a remote daemon’s host. --json returns currentVersion, latestVersion, updateAvailable, downloadURL, releaseNotesURL, publishedAt and feedURL. Not available in the App Store build, which the App Store updates.

caked-specific commands

  • certificates group:
    • get — show certificate paths
    • generate — generate TLS certs
    • agent — generate agent certs
  • convert — convert a VMDK or QCOW2 disk image to raw format (pure Swift, no external tools required).
    • --source-format / -f — source format: qcow2 (default) or vmdk.
  • service — service/daemon management entry point.
    • install — install caked as a launchctl agent.
    • listen — start the daemon listener with the following notable flags:
      • --rest — enable the LXD-compatible REST API server (default port 8443 for HTTPS, 8080 for HTTP).
      • --rest-port <port> — override the REST API listen port.
      • --web-ui <path> — serve the bundled web UI from a directory or .zip archive at /ui.
      • --address / -l — override the gRPC listen address.
      • --disable-tls — disable TLS.
      • --imds-port <port> — unprivileged port IMDS listens on, directly reachable by guests with no root needed (default 28080). See IMDS.
    • status — report daemon status.
    • stop — stop the running daemon.
  • vmrun — internal VM runtime command (hidden/internal).
  • import — import external VM (Multipass or VMware Fusion) from file/URL.
  • relocate <path> — move the cake home directory (CAKE_HOME: VMs, images, caches) to another folder or volume and remember it for later runs. Refused while the caked daemon, a VM or a network is running. Caker.app equivalent: Settings > Advanced > Storage > Relocate…. Not available in the App Store build, whose cake home is always its App Group container — see Sandbox.
  • networks extra internal/admin subcommands:
    • set-dhcp-lease
    • restart
    • run (internal)
    • imds-redirect (internal, requires root) — installs/removes the pf address-alias redirect for 169.254.169.254, see IMDS.

cakectl-specific commands

  • certificate — Manage certificate to authenticate API rest.

macOS IPSW installation

build accepts an .ipsw file as the image source on Apple Silicon hosts. The installer back-end is chosen automatically based on the IPSW content.

Back-end selection

Guest macOS version Back-end used Availability
macOS 26 or older VZMacOSInstaller (system framework) All builds
macOS 27 (Golden Gate) or newer AMRestore (AppleMobileDeviceRestore SPI) All builds

The AMRestore path can be force-enabled for any IPSW by setting the CakerForceVirtualInstallBackend UserDefaults key (useful for testing):

defaults write com.aldunelabs.Caker CakerForceVirtualInstallBackend -bool true

Remove the override when you are done:

defaults delete com.aldunelabs.Caker CakerForceVirtualInstallBackend

How the AMRestore path works

  1. The VM is booted in DFU mode using the private _forceDFU property on VZMacOSVirtualMachineStartOptions.
  2. Caker waits for the VM to appear as a restorable AMRestore device (matched by its ECID — the unique chip identifier embedded in the machine identifier).
  3. The IPSW is handed to AMRestorableDeviceRestore which performs personalization against gs.apple.com and flashes the image. The VM shuts down on completion.

Restore logs are written to ~/Library/Application Support/Caker/VirtualInstall/Logs/ (four files: global.log, host.log, device.log, serial.log).

Limitations

  • Apple Silicon only — AMRestore SPI does not exist on Intel Macs.
  • Requires macOS 26 or later on the host.

PackerLite: unattended provisioning (macOS and Linux)

When build/create runs with --autoinstall, once installation finishes, caked automatically drives the VM’s first boot via PackerLite — a small built-in engine inspired by Packer’s boot_command, with no external binary or plugin required. Without --autoinstall, no automatic provisioning happens.

cakectl build my-vm https://updates.cdn-apple.com/.../UniversalMac_26.6_25G72_Restore.ipsw --autoinstall
cakectl build my-vm ./Fedora-Workstation-Live-x86_64-42.iso --autoinstall
# Windows 11: unattended install (outside PackerLite); the ISO file name must contain "windows"
cakectl build my-win11 iso:///path/Windows11_Client_arm64_en-us_26300_9457.iso --cpus 4 --memory 8192 --disk-size 64 --autoinstall

Windows 11 is installed by a dedicated installer, not by PackerLite. The ISO file name must contain windows (or win11/win10), otherwise --autoinstall does nothing. Details in Provisioning & Recording. Windows-specific --vars: WINDOWS_KEY (product key), WINDOWS_FRAME_SEGMENT_MIB (display buffer, 16 to 256 MB) WINDOWS_AUDIO=0 (leave the sound driver out) WINDOWS_AUTOLOGON=1 (log on automatically at every start) and WINDOWS_WHQL_ONLY=1 (install only drivers signed by Microsoft: no sound, no display resizing).

Option Description
--autoinstall Enables automatic provisioning (required in all cases).
--template <path> Custom PackerLite YAML template; bypasses auto-detection.
--macos-version <version> macOS version to pick the built-in template when it can’t be inferred from the IPSW filename.
--var <key=value> Sets a template variable (${var.key}), repeatable.

See the dedicated Provisioning & Recording page for: full template resolution (macOS and Linux), the list of built-in templates, the YAML format and complete boot_command token vocabulary, provision (re-running provisioning against an already-built VM, locally or via cakectl), the debug video recording, and caked record (recording a manual session to produce a template).

Quick image selection: --alias and aliases

Instead of pasting a raw image URL, build/create/launch accept a short catalog id via --alias:

caked build --alias macos12 new-vm --autoinstall
cakectl build --alias ubuntu2604 new-vm
cakectl launch --alias fedora44Server my-vm --autoinstall

--alias resolves the given id against the bundled VMImages.json catalog (the same catalog behind Caker.app’s image picker) and substitutes the URL/disk format the catalog specifies for that id. For an ipsw entry whose id also matches a known macOS version (e.g. macos12), --macos-version is auto-populated if you didn’t pass it yourself. Every id in the catalog is unique: CentOS, openSUSE, and Alpine ship both an installer ISO and a prebuilt cloud image, so their iso entries use an -iso-suffixed id (e.g. centos10-iso, alpine324-iso) to stay reachable alongside the bare cloud id (centos10, alpine324).

To list every id --alias accepts, tagged with its category (ipsw/iso/cloud):

caked aliases
cakectl aliases

caked aliases reads the local catalog, while cakectl aliases asks the connected caked over gRPC, so it lists the ids that caked will actually resolve --alias against, including its own <CAKE_HOME>/VMImages.json, even when it runs on another host.

The catalog itself — <CAKE_HOME>/VMImages.json, if present, overrides the version bundled with the app; see VMImageCatalog.refreshFromGitHub() to refresh it from the repo.

provision and record

  • caked provision/cakectl provision <vm> re-runs PackerLite against an already-built VM (a build that skipped --autoinstall, or provisioning that needs redoing), locally or remotely over gRPC.
  • caked record <vm> records a manual session (clicks/keystrokes in a local window) and produces a ready-to-use .packerlite.yaml template — the reverse of provision.
cakectl provision my-vm
caked record my-vm --output ./my-template.packerlite.yaml

See the dedicated Provisioning & Recording page for the full detail: resolving the VM’s stored version/platform, options, the automatic provisioning debug video recording, and for record — pause/resume, OCR-assisted clicks (locate mode), folding wait gaps into timeout=, pre_boot_command routing for Linux, and the format of the produced file.

Notes

  • Some commands are internal or hidden in help output on caked (vmrun, some networks subcommands).
  • Exact flags/options are defined in the corresponding *Options types and command files.
  • If the caked service is already active, do not run caked commands directly; use cakectl to interact with the running service.

Examples

Basic VM Operations

# Create and start a VM
cakectl launch myvm --image ubuntu:22.04

# List running VMs
cakectl list

# Execute command in VM
cakectl exec myvm -- ls -la

# Stop VM
cakectl stop myvm

Image Management

# Pull an image
cakectl pull ubuntu:22.04

# List local images
cakectl image list

# Push custom image
cakectl push myregistry.com/myimage:latest

Disk formats: raw and ASIF

Caker supports two root-disk image formats, selected with --disk-format / -f on build and launch:

Format Value Host requirement Description
Raw raw Any supported macOS Flat disk image resized by extending the file. Default on hosts older than macOS 26.
ASIF asif macOS 26 (Tahoe) or later Apple Sparse Image Format, created and managed with diskutil image. Space-efficient — the file only occupies the blocks actually written by the guest. Default on macOS 26+.
# Create a VM with an ASIF root disk (macOS 26+, default there)
cakectl build myvm --disk-size 40 --disk-format asif ubuntu:noble

# Force the raw format
cakectl build myvm --disk-size 40 --disk-format raw ubuntu:noble

Notes:

  • ASIF requires macOS 26 or later on the host. On older hosts the format is unavailable and raw is used.
  • Caker recognizes an ASIF disk by its .asif extension or its shdw magic header, so an existing ASIF image is detected regardless of its file name.
  • Growing a disk with configure --disk-size <GiB> uses diskutil image resize for ASIF disks and file truncation for raw disks. The VM must be stopped first. Shrinking is not supported.

⚠️ ASIF disk resize is not available from the command line in the App Store (sandboxed) version

The App Store version of Caker runs inside the macOS App Sandbox, which prevents the caked/cakectl command-line interface and the background service from invoking diskutil image resize. Attempting to resize an ASIF disk from the CLI fails with:

Resize disk is not available in sandboxed mode with command line interface, ...

To resize an ASIF disk in the sandboxed version you can either:

  1. Use the Caker application — resizing from the VM settings UI works normally, or
  2. Run the diskutil command manually in Terminal (with the VM stopped):
diskutil image resize --size=<new-size>G "$(caked home)/vms/<vm-name>.cakedvm/disk.img"

When the resize is refused, the Caker application displays the exact command to run for your VM. Raw disks and the direct-download build are not affected — configure --disk-size works normally there.

Spawning from an existing disk

spawn and spawn-start register a new VM that boots directly from an existing disk — a raw image file you already have, or a physical block device (/dev/diskN). No image is downloaded or converted, and cloud-init does not run by default.

When to use spawn vs build

  build / launch spawn / spawn-start
Root disk Downloaded / converted from URL Provided by you (image or block device)
cloud-init Runs on first boot Off by default; opt in with --use-cloud-init
Typical use Fresh Linux/macOS VMs from cloud images Pre-configured images, physical disks, migrated VMs

Syntax

caked spawn [options] <name> <root-disk>
caked spawn-start [options] <name> <root-disk>

<root-disk> can be:

  • An absolute or ~-expanded path to a raw disk image (/path/to/disk.img)
  • A physical block device (/dev/disk4) — requires macOS 14 or later

Options

Flag Default Description
-c, --cpus <num> 1 Number of vCPUs
-m, --memory <MB> 512 RAM in megabytes
--os <linux\|darwin> linux Guest OS type
--disk <path> — Additional attached disk (repeatable)
-u, --user <name> admin Username caked uses to connect to the guest (exec/sh)
-w, --password <pass> — Password for the guest user
--nvram <path> — Existing NVRAM / auxiliary-storage file to copy (required for macOS on Apple Silicon when not auto-fetched)
-a, --autostart off Start VM automatically at boot
-t, --nested off Enable nested virtualisation
--suspendable off Optimise for VM suspension (macOS guests)
-p, --publish <spec> — Port forwarding, docker syntax (repeatable)
-v, --mount <spec> — Virtio-FS directory share (repeatable)
-n, --network <spec> — Network interface (repeatable)
--bridged off Add one bridged network interface
--net.ifnames <bool> true Use predictable interface names (eth0 → enp…)
--display <WxH> 1024x768 Guest screen resolution
--socket <url> — Virtio socket (repeatable)
--console <url> — Serial console URL
--use-cloud-init off Run cloud-init on first boot (Linux only)

spawn-start also accepts --wait-ip-timeout <seconds> (default 180).

NVRAM behaviour

Platform --nvram provided --nvram omitted
Linux (any arch) ignored — fresh EFI variable store is always created fresh EFI variable store created
macOS (Apple Silicon) provided file is copied as the VM’s auxiliary storage hardware model fetched from Apple metadata; fresh auxiliary storage created automatically

cloud-init when using --use-cloud-init

When --use-cloud-init is passed (Linux only), the following additional options become meaningful:

Flag Description
-i, --ssh-authorized-key <path> SSH authorized-key file to inject
-g, --main-group <name> Primary group for the user (default adm)
-o, --other-group <name> Additional groups (default sudo, repeatable)
-k, --clear-password Allow password-based SSH login
--cloud-init <path\|url\|-> Custom user-data file or URL (- for stdin)
--network-config <path> Custom cloud-init network-config file

Without --use-cloud-init, none of these options have any effect — they are accepted but ignored.

Spawn examples

# Register a VM from a raw image, 2 vCPUs, 2 GiB RAM
caked spawn myvm ~/images/ubuntu-24.04.raw -c 2 -m 2048

# Register and immediately start, with NAT network and port forwarding
caked spawn-start myvm ~/images/ubuntu-24.04.raw \
  -c 4 -m 4096 \
  --network nat \
  -p 2222:22/tcp

# Boot from a physical disk, specifying the guest credentials for exec/sh
caked spawn diskvm /dev/disk4 --os linux -c 2 -m 4096 -u ubuntu -w secret

# macOS guest from an existing disk — copy its NVRAM (Apple Silicon)
caked spawn macosvm ~/vms/macos.img --os darwin -c 4 -m 8192 \
  --nvram ~/vms/macos.nvram

# macOS guest — let caked fetch the hardware model and create NVRAM automatically
caked spawn macosvm ~/vms/macos.img --os darwin -c 4 -m 8192

# Spawn with cloud-init enabled and a custom SSH key
caked spawn webvm ~/images/ubuntu-24.04.raw \
  -c 2 -m 2048 -u ubuntu -w secret \
  --use-cloud-init -i ~/.ssh/id_ed25519.pub

Physical block device (/dev/diskN)

When <root-disk> points to a block device rather than an image file, caked:

  1. Checks whether any volumes on the disk are currently mounted.
  2. If mounted, prompts to unmount them automatically (GUI) or aborts with an error message (daemon/headless mode) — you must run diskutil unmountDisk /dev/diskN manually first.
  3. Opens the device with an exclusive lock (O_EXLOCK) in read-write mode.
  4. Passes the open file descriptor to Apple’s Virtualization.framework as a VZDiskBlockDeviceStorageDeviceAttachment.

The lock is held for the entire lifetime of the VM, preventing macOS from re-mounting the disk while the VM is running.

Note: Attaching physical block devices requires macOS 14 (Sonoma) or later and is not supported in the App Store version. The App Sandbox cannot acquire the exclusive lock (O_EXLOCK) required to open a block device safely. Use the direct-download build if you need raw disk access.

Taking ownership of a physical device

macOS block devices (/dev/diskN) are owned by root:operator with mode 0660. Ordinary users cannot open them read-write without additional privileges.

If caked reports a permission denied error for a block device, you have two options:

sudo dseditgroup -o edit -a "$USER" -t user operator

Log out and back in (or start a new shell session) for the group membership to take effect. After that, every /dev/diskN device is accessible to you without sudo, and you never need to repeat this step.

Option B — change the device owner (per-session, resets on reboot)

sudo chown "$USER" /dev/disk4

This changes ownership of the specific node to your user. The change is not persistent — macOS resets device ownership on reboot or when the disk is reconnected.

Which option to choose

  Option A (operator group) Option B (chown)
Persistent Yes No (resets on reboot / reconnect)
Scope All block devices One device at a time
Effort Once per user account Every time the disk is reconnected
Recommended Yes Quick one-off testing

After granting access with either option, retry the spawn or spawn-start command — no other changes are needed.