Caker

Virtualization platform for macOS

View project on GitHub

Automated Provisioning and Recording (PackerLite)

Caker automates a freshly-installed VM’s first boot — account creation, enabling Screen Sharing for macOS, or a keystroke-driven Linux installer — via PackerLite, a small built-in engine inspired by HashiCorp Packer’s boot_command and its packer-plugin-tart plugin, with no external binary or plugin required. This page covers the three ways to interact with it:

  • --autoinstall — automatic provisioning at build/create time.
  • provision — re-runs provisioning on an already-built VM.
  • record — records a manual session to produce a template instead of writing one by hand.

For catalog-based image selection (--alias/aliases), see the corresponding section of Command Summary.

Automatic provisioning with --autoinstall

When build/create runs with --autoinstall, once installation finishes, caked automatically drives the VM’s first boot. Without --autoinstall, no automatic provisioning happens.

Template resolution

From an .ipsw (macOS) — resolved in this order, the build fails if nothing resolves:

  1. --template <path> — an explicit path to a custom YAML template; wins over everything else.
  2. Automatic detection of the macOS version from the IPSW’s filename (Apple’s UniversalMac_<version>_<build>_Restore.ipsw convention), loading the matching built-in template.
  3. --macos-version <version> — if detection fails, uses the explicitly given version (macos12, macos13, macos14, macos15, macos26, or macos27; the former marketing names monterey/ventura/sonoma/sequoia/tahoe/goldengate are still accepted as input for backward compatibility) to pick the built-in template.

The detected macOS version (identifier + dotted version, e.g. macos15 / 15.6) is always recorded on the VM’s config (osName/osRelease), whether or not --autoinstall was used — so a later caked provision run can find the right version without the original IPSW.

From an .iso (Linux) — resolved in this order:

  1. --template <path> — an explicit path to a custom YAML template; wins over everything else.
  2. Automatic detection of the distro from the ISO’s filename/URL, loading the matching built-in template: fedora, centos, redhat (or rhel), openSUSE, debian — and windows, which doesn’t use PackerLite but the dedicated Windows installer (see below; the name must contain windows).
  3. Otherwise, no provisioning happens — silently, not an error. That’s the expected outcome for Ubuntu (which already handles its own autoinstall via cloud-init/subiquity) or any distro caker doesn’t recognize; provide your own --template for the latter.

In Caker.app’s VM creation wizard, the “Provisioning yaml” file picker only appears for non-Ubuntu ISO sources; it stays optional when a built-in template exists for the detected platform, and only becomes required otherwise if autoinstall is enabled.

# macOS: version auto-detected from the IPSW filename
cakectl build my-vm https://updates.cdn-apple.com/.../UniversalMac_26.6_25G72_Restore.ipsw --autoinstall

# macOS: non-standard filename, version given explicitly
cakectl build my-vm ./restore.ipsw --autoinstall --macos-version macos26

# macOS: custom template, bypasses auto-detection entirely
cakectl build my-vm ./restore.ipsw --autoinstall --template ./my-template.packerlite.yaml

# Linux: distro auto-detected from the ISO filename (Fedora here)
cakectl build my-vm ./Fedora-Workstation-Live-x86_64-42.iso --autoinstall

# Linux: custom template, for a distro with no built-in template
cakectl build my-vm ./my-distro.iso --autoinstall --template ./my-distro.packerlite.yaml

# Extra template variables (repeatable)
cakectl build my-vm ./restore.ipsw --autoinstall --var greeting=hello
Option Description
--autoinstall Enables automatic provisioning (required in all cases, macOS and Linux alike).
--template <path> Custom PackerLite YAML template; bypasses auto-detection for both macOS and Linux. Only required if the detected platform has no built-in template.
--macos-version <macos12\|macos13\|macos14\|macos15\|macos26\|macos27> macOS version to use for picking the built-in template when it can’t be inferred from the IPSW filename. Former marketing names (monterey, ventura, sonoma, sequoia, tahoe, goldengate) are still accepted as input. No effect for Linux.
--var <key=value> Sets a template variable (${var.key}), repeatable.

Account credentials: the account provisioning creates always uses --user/--password (or the UI equivalent) — never a template-declared value. Inside a template, these are available as ${var.username} / ${var.password}.

Stored provisioning variables: --var (on the CLI — caked build/provision and cakectl build/provision) and Caker.app’s VM creation wizard “Provisioning variables” editor (shown below the ISO/IPSW image picker) share the same persistent store, <CAKE_HOME>/ProvisionVariables.json — a variable added on either side is automatically available on the other, without re-entering it per VM. If no --var is passed, the stored variables are used as-is; if a --var is passed and one of its keys collides with an already-stored variable of the same name, the command fails with a “Duplicate provision variable” error rather than letting either one silently win — rename the variable or remove the conflicting stored entry. Names/values can’t contain = or |.

Built-in templates

macOS: six templates ship as embedded resources (Sources/cakedlib/PackerLite/Resources/), one per version — macos12, macos13, macos14, macos15 (originally transcribed from a Packer sequoia.pkr.hcl template), macos26 (originally transcribed from tahoe.pkr.hcl), and macos27. Those legacy Packer/Tart reference templates have since been removed from the repo — PackerLite no longer depends on them. All six recognized macOS versions now have a built-in template. Version identifiers were renamed from their original marketing names (monterey→macos12, ventura→macos13, sonoma→macos14, sequoia→macos15, tahoe→macos26, goldengate→macos27); the old names remain accepted as --macos-version input for backward compatibility.

Linux: nine Linux templates also ship as embedded resources (the linux-/vanilla- filename prefixes have since been dropped from every bundled template, macOS included): fedora (Fedora Workstation, Anaconda — Live ISO, boots into a live desktop and then GNOME’s graphical first-boot setup wizard; selected when the URL/filename contains “workstation” or “desktop”), fedora-server (Fedora Server, Anaconda — same flow as a CentOS/RHEL ISO, boots straight in with no live session; selected by default otherwise), centos (CentOS Stream, Anaconda), redhat (RHEL, Anaconda — both redhat and rhel are recognized in the filename), opensuse (openSUSE Leap, YaST installer), debian (Debian, debian-installer), alpine (Alpine, setup-alpine), and ubuntu/ubuntu-server (Ubuntu Desktop and Server). Most have since been rewritten to use OCR-synchronized (<locate>) navigation instead of fixed clicks/delays, across several fix passes explicitly aimed at matching what the real installer actually shows — unlike their original “reviewed for plausibility only” state, that implies iteration against real boots, though no commit claims full end-to-end validation; still expect to need to nudge the occasional click target. opensuse targets the YaST installer (openSUSE Leap ≤ 15.6) — the newly-added Leap 16.0/16.1 ISOs in VMImages.json use the new Agama installer instead, which this template doesn’t cover; bring your own --template for those versions in the meantime. Ubuntu also still has its own native unattended-install mechanism (cloud-init/subiquity, via the “autoinstall” boot option) — the ubuntu* templates are an optional alternative that goes through the same OCR-driven PackerLite approach every other distro here uses; unlike the other bundled Linux templates, their boot_command never types the account credentials, it just navigates the GRUB menu and keyboard layout, then waits for Ubuntu’s own autoinstall flow to finish on its own. Any other distro needs a custom --template.

Windows 11 (ARM64): Windows installs unattended, but not through PackerLite: its installer shows nothing on screen (Apple’s firmware gives Windows no framebuffer), so an OCR-driven boot_command would have nothing to read. build --autoinstall on a Windows 11 ISO (ARM or x64) does this instead:

  1. a GPT installation disk is built from the ISO (the ISO as is doesn’t boot: it only has an El Torito boot record, which firmware doesn’t read on a USB disk); WinPE’s image (boot.wim) is edited (by Swift code that reads and extends the WIM format, no external tool) so its shell runs an install script instead of Windows Setup;
  2. the VM boots that disk: the script partitions the system disk, applies the Windows image (dism), adds the virtio drivers (display and network, from the virtio-win ISO, downloaded and cached) and an answer file that creates the --user/--password account with automatic logon, then powers the VM off;
  3. the VM boots Windows, which sets itself up (several restarts: Virtualization.framework stops a VM whose guest reboots, so it is started again until Windows leaves its done marker on the EFI partition and powers off).

Installing takes about 8 minutes. Windows then starts normally (cakectl start), with a working display and network.

The ISO file name must contain windows (case-insensitive, e.g. Windows11_Client_arm64_en-us_26300_9457.iso). That is how Caker knows the image is Windows: without it the ISO is taken for an unknown distro and --autoinstall does nothing, with no error. The names Microsoft gives its images without the word windows (Win11_25H2_English_Arm64_v2.iso) are also recognized when they contain win11 or win10; any other name must be renamed before build. The whole path or URL is examined: ubuntu, centos or macos appearing in it are tested before windows and win, so avoid them.

cakectl build my-win11 iso:///path/to/Windows11_Client_arm64_en-us_26300_9457.iso \
  --cpus 4 --memory 8192 --disk-size 64 --user admin --password admin --autoinstall

Specifics:

  • Pass the ISO as iso:///absolute/path.iso: a bare path is treated as a raw disk image.
  • Product key. When the WINDOWS_KEY provisioning variable is set (--var WINDOWS_KEY=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX, or Caker.app’s “Provisioning variables” editor), it goes into the answer file (<ProductKey>, specialize pass) and Windows activates with it. Without it, Windows installs with no key (unactivated). A key that isn’t five groups of five characters fails the build before the install rather than leaving Windows on a dialog nobody can see; the key is never logged.
  • Display buffer size. The display driver allocates its memory when it starts, and the biggest screen depends on it (width × height × 4 bytes): 64 MB by default (up to 5120×3200). To change it, pick “Display buffer size” in Caker.app’s wizard (16 to 256 MB) or pass --var WINDOWS_FRAME_SEGMENT_MIB=128; a value outside 16–256 fails the build before the install. A bigger buffer uses more of the guest’s memory.
  • Sound. Windows has no driver for Virtualization.framework’s virtio sound device, so the installation media carries the viosnd driver (317764920/viosnd, BSD license, with one INF tweak: playback only, the VM has no audio input), test-signed like the display driver (the test mode already turned on for it is enough). The guest’s sound goes out of the Mac’s default audio output (Linux VMs too). To leave it out, pass --var WINDOWS_AUDIO=0. No microphone yet. Once installed, Windows shows a “Speakers (XCB VirtIO Audio Device)” device; if the driver doesn’t load, build says so (audio= in the first-boot marker).
  • Automatic logon. By default Windows logs the account on once, to finish setup, and then waits at the lock screen: anything that has to run in the user’s session at start (the display following the window size, for instance) only works once someone has logged on. --var WINDOWS_AUTOLOGON=1 (or “Log on automatically” in the wizard) logs the account on at every start. The password is then kept in the guest’s registry in clear text, as for any automatic logon: use it for test or development machines.
  • WHQL-signed drivers only. Caker’s own display and sound drivers are test-signed: the guest trusts a throwaway certificate and runs in test-signing mode (a “Test Mode” watermark on the desktop). --var WINDOWS_WHQL_ONLY=1 (or “Use only WHQL-signed drivers” in the wizard) installs only virtio-win’s drivers, which Microsoft signed: no certificate, no test mode. The price: no sound (Windows has no signed driver for Virtualization.framework’s sound device) and no display resizing: with the stock display driver the picture is corrupted when the size changes, so the guest keeps its size, displayRefit is turned off (the choice is greyed out in the wizard) and the VM’s window can’t be resized any more (nor made full screen), in Caker.app, in caked’s window and in the caked vnc and cakectl vnc windows. The same rule applies to a Windows guest installed before Caker’s driver existed. WINDOWS_AUDIO and WINDOWS_FRAME_SEGMENT_MIB are ignored then.
  • Architecture. The ISO must match your Mac’s architecture: Windows 11 for ARM on Apple silicon, for x64 on an Intel Mac. An ISO of the other architecture is refused (the architecture is read from the ISO’s boot loader).
  • No TPM. Virtualization.framework exposes none (Windows only binds a TPM described by an ACPI table, and a virtio device has no Windows driver). The install doesn’t go through Windows Setup, so its TPM/Secure Boot checks don’t apply, but BitLocker and device encryption are unavailable.
  • Windows-friendly hardware. NVMe system disk, USB mass storage installation media, two CPU features enabled for Windows (PMU emulation), and a small UEFI driver (Tools/WindowsEFI) that supplies the framebuffer Windows requires.
  • Shared folders. The virtio-fs driver (viofs) and WinFsp 2.1 (downloaded from WinFsp’s official releases, SHA-256 verified) are installed along with the virtio-fs service: a folder shared with --mount shows up in Windows as a drive (Z:), readable and writable.
  • virtio sockets (vsock). The viosock driver (with its Winsock provider service) is installed, so Windows can open AF_VSOCK connections to the host.
  • Display resizing. When the VM window’s size changes the virtio GPU driver learns the wanted size, but the helper virtio-win ships to apply it (viogpuap) never finds the GPU, because Windows 11 also keeps a “Microsoft Basic Display Driver” adapter in first position. The agent (cakeagent) asks the driver from the logged-on user’s session and applies the size, so Windows follows the VM window (with --display-refit, or caker’s display option). Both ARM64 (Apple silicon) and x64 (Intel) installs use a patched build of the GPU driver (the stock driver makes Virtualization.framework show a corrupted picture after a resolution change on both; the fix, proposed to virtio-win, is opt-in: it stays off unless an INF line specific to Virtualization.framework’s PCI id turns it on, so other hypervisors keep the original code), test-signed with one certificate per architecture: the guest runs with test-signing on and shows a “Test Mode” watermark. A guest installed before the patched driver keeps the size it boots with and the window scales it. The size is limited: the driver allocates its display memory when it starts (at least 16 MiB, about 4.19 million pixels, or what the size the guest started with needs) and refuses a bigger mode, and a refusal can leave Windows refusing the next sizes too. Caker therefore keeps the guest’s display inside that limit, with the window’s aspect ratio (a 3440×1440 window gives a 3164×1324 display, which the view scales); refusals are logged in C:\ProgramData\caker\display.log.
  • SSH server. Windows 11 only ships the OpenSSH client (the server is a Feature on Demand that needs Windows Update): the pinned Win32-OpenSSH release (SHA-256 verified) goes on the media and is installed as a service that starts with Windows, port 22 is opened in the firewall, and the host’s public keys are authorized for administrators (administrators_authorized_keys). The account’s password works too: ssh admin@<ip>.
  • Agent (cakeagent). The Windows cakeagent is downloaded (the CAKEAGENT_SNAPSHOT release, like Linux and macOS), copied with the agent certificates onto the media, and installed as a service on first boot, listening on vsock (vsock://any:5000) with mutual TLS: the host talks to it through the VM’s agent socket. It needs a cakeagent build that can listen on vsock on Windows.
  • Any Windows language can be installed. Caker reads the image’s default language (install.wim) and carries it into the answer file (display language, locale and keyboard): just use the ISO in the language you want (Win11_25H2_French_Arm64_v2.iso, Win11_25H2_Japanese_Arm64_v2.iso, and so on). There is nothing to configure, and the rest of the install (drivers, SSH, agent) is the same. A multilingual ISO is installed in the image’s default language. Checked with the French ISO, on ARM64 and on x64.
  • Not in the App Store build: the install runs hdiutil, diskutil and rsync, and the App Store build does not run Windows VMs.
  • Minimum sizing: 2 CPUs, 4 GiB of memory, 64 GB of disk (a warning is logged below that).

Several Linux templates ({centos,debian,fedora,opensuse,redhat}.packerlite.yaml) now also declare an optional pre_boot_command:, run immediately after the VM starts — before an IP is available — to send GRUB boot-menu keystrokes right at the start of boot, cutting the initial blind wait down to 5s (from roughly 30s).

SELinux is disabled on every distro

Whether the VM comes from a cloud image or from an ISO provisioned with --autoinstall, the agent install script turns SELinux off on any distro that has it (/etc/selinux/config present): SELINUX=disabled is written to the configuration and setenforce 0 makes the kernel permissive right away. SELinux only really goes away at the next boot, and the script prints NOTICE: SELinux is disabled on this guest … in its log (~/install-agent.log for ISO builds, the cloud-init log for cloud images). If you need SELinux enforcing, re-enable it inside the VM after provisioning.

Template format and token vocabulary

A template is a minimal YAML file with a boot_command list of title/commands entries (commands is a list of token/text fragments, concatenated together — not a single string — so you can put one token per line for readability), plus variables: and boot_timeout. Each entry’s title is surfaced as a progress substep and in the logs — handy for spotting exactly where a provisioning run stalled. ${var.username}/${var.password} are always injected by caked; any other ${var.*} comes from variables: or a matching --var.

Token Description
<wait10s>, <wait1m>, <wait> Pause before the next token (seconds by default, s/m accepted; bare <wait> = 1s).
<enter>, <tab>, <spacebar>, <esc>, etc. Press a named key. Accepts a repeat=N suffix to press it N times in one go, e.g. <tab repeat=3>.
<f1> – <f20> Function keys.
<leftShiftOn>/<leftShiftOff>, <fnOn>/<fnOff>, etc. Hold/release a modifier key, wrapped around other tokens.
<click 'On-screen text'> or <click text='...' timeout=N> Locates On-screen text via Vision OCR and clicks it; retries until the timeout elapses (10s by default, timeout=N to change it).
<click X,Y> or <click point="X,Y"> Clicks a fixed screen coordinate (CGPoint), no OCR involved.
<locate 'On-screen text'> or <locate text='...' timeout=N> Waits, via OCR, for On-screen text to appear — without clicking; a synchronization point before blindly chaining <tab>/<spacebar> steps, more robust than a bare <waitNs> when a screen’s appearance time varies.
<skipCommandIfNotFound text='...' timeout=N> or <skipCommandIfNotFound 'On-screen text'> Polls via OCR for the text to appear within timeout seconds (10s default); if it never does, abandons the rest of the steps in the current title block and moves on to the next boot_command entry, instead of throwing. Useful for a screen that only sometimes appears (e.g. a locale-dependent step).
<skipStepIfNotFound text='...' steps=N timeout=N> Like <skipCommandIfNotFound>, but instead of abandoning the rest of the current title block when the text isn’t found in time, skips exactly the next N steps (default 1) and then continues normally. More precise than <skipCommandIfNotFound> when only a couple of a screen’s steps are conditional.
<scroll N> or <scroll horizontal=N vertical=N> Emits a scroll-wheel event at the current cursor position; <scroll N> scrolls vertically only.
<keyboard 'com.apple.keylayout.XXX'> or <keyboard 'current'> Switches the keyboard layout used to translate typed characters from this point on.
<reboot> or <reboot stop="true\|false"> Stops and restarts the VM mid-provisioning-run — useful when the installer itself triggers a reboot that needs to be driven through rather than just survived. stop="true" (the default) does a graceful requestStop; stop="false" forces an immediate stop.
<voiceOverOn> or <voiceOverOn confirm=true> Turns VoiceOver on (macOS only) via the usual key sequence (Option+Fn+F5); confirm=true also types “v” afterward, for the “Use VoiceOver?” dialog that only appears the very first time it’s enabled on a fresh install.
<voiceOverOff> Turns VoiceOver off (same key sequence).

<click text=...>, <locate>, <skipCommandIfNotFound>, and <skipStepIfNotFound> all also accept a pipe-delimited list of alternatives in text=, e.g. text="Accept|Continue" — the step matches if either string is recognized on screen, useful for wording that varies across installer versions/locales.

Besides boot_command/pre_boot_command, a template can declare ignore_ip: true: provisioning then never waits for the VM’s IP address, either before or after boot_command. Useful for a boot_command that doesn’t need the network anyway, or a guest whose DHCP is too slow/unreliable to be worth waiting on. Side effect: a VM with ignore_ip: true also skips the automatic cakeagent install at the end of provisioning, since that step itself depends on having an IP.

install_agent: false has the same targeted effect on the agent alone, without touching the IP wait — useful for a guest where the cakeagent doesn’t make sense.

required_variables: [name1, name2, ...] declares variables the template requires: if any of them is missing at resolve time (not supplied via --var, the wizard’s variable editor, or the built-in variables below), provisioning fails immediately with a clear error instead of silently substituting an empty string. The redhat template uses this for redhat_username/redhat_password — the Red Hat subscription credentials needed to register the system, distinct from the VM’s own --user/--password account.

Beyond ${var.username}/${var.password}, two more built-in variables are now always available: ${var.hostname} (the VM’s own name) and ${var.ssh_authorized_key} (the configured SSH public key(s), absent if none are configured).

post_boot_command: { use_ssh_key: true|false, commands: [command1, command2, ...] } declares a list of shell commands run over SSH once the agent-install step has finished (whether or not install_agent actually ran) — handy for configuring the VM after install, such as installing packages, writing config files, or running a setup script, without having to drive it through boot_command’s keystrokes. use_ssh_key explicitly opts this phase into key-based SSH auth rather than password auth, independent of what the VM’s own config provides. Execution stops at the first command that fails; to avoid a credential-leakage risk, only debug-level logs ever show command/output content — a failing command is only ever reported by its position in the list. Like boot_command/pre_boot_command, these commands support the same ${var.*} substitution.

# my-template.packerlite.yaml — illustrative excerpt
boot_timeout: 45m        # fail if provisioning isn't done within this long

variables:
  greeting: hello         # default value, overridable via --var greeting=...

boot_command:
  - title: Welcome screen
    commands:
      - <wait60s>
      - <spacebar>

  - title: Select Language
    commands:
      - <wait30s>
      - italiano
      - <esc>
      - english
      - <enter>

  - title: Select Your Country or Region
    commands:
      - <click timeout=30 text='Select Your Country or Region'>
      - <wait5s>
      - united states
      - <leftShiftOn>
      - <tab>
      - <leftShiftOff>
      - <spacebar>

  - title: Transfer data (OCR-synchronized before continuing)
    commands:
      - <locate timeout=30 text='Transfer Your Data to This Mac'>
      - <tab repeat=3>
      - <spacebar>

  - title: Create Account
    commands:
      - "${var.username}"
      - <tab>
      - "${var.password}"
      - <tab>
      - "${var.password}"
      - <tab>
      - <tab>
      - <spacebar>

See Sources/cakedlib/PackerLite/Resources/*.packerlite.yaml (every bundled template — macOS and Linux, with titles) for full, fully-commented examples.

provision: re-running provisioning standalone

build/create only drives PackerLite automatically when --autoinstall was used. For a VM (macOS or Linux) that skipped provisioning at build time — or was built before --autoinstall existed — provision <vm> re-runs the same automation directly against an already-built VM. Available two ways:

  • caked provision <vm> — runs locally on the host where the VM’s files live; boots the VM itself with a visible window (like vmrun) rather than assuming it’s already running, so you can watch provisioning happen right there.
  • cakectl provision <vm> — the same operation over gRPC, streamed (like build/launch), for driving provisioning on a remote VM without being physically at the caked host. The template’s content (not just its path) is sent to the server, so --template can point at a file local to wherever cakectl is running, not the machine hosting the VM.

Both use the VM’s own stored state instead of the original .ipsw/.iso:

  • macOS VM: the version comes from CakeConfig.osName — recorded automatically on every .ipsw build — unless overridden with --macos-version; --template is still available to bypass this resolution entirely.
  • Non-macOS (Linux) VM: the platform comes from CakeConfig.configuredPlatform — recorded automatically on every ISO build — and picks the same built-in template build would (fedora, centos, redhat/rhel, openSUSE, debian). --template is still available to override it, and only becomes required if the stored platform has no built-in template (Ubuntu, or an unrecognized distro).
  • Either way, account credentials come from the VM’s own --user/--password (configuredUser/configuredPassword), exactly as at build time. Once the boot_command finishes and an IP is obtained, provision also installs the cakeagent if needed — useful for a Linux VM that skipped cloud-init.
# Re-provision a macOS VM using its stored version and credentials
cakectl provision my-vm

# Override the resolved macOS version
cakectl provision my-vm --macos-version macos26

# Re-provision a Linux VM whose stored platform has a built-in template (e.g. Fedora)
cakectl provision my-fedora-vm

# Re-provision a Linux VM with no built-in template (template required)
cakectl provision my-linux-vm --template ./my-distro.packerlite.yaml

# The same thing run locally on the caked host, without going through gRPC
caked provision my-vm
Option Description
--template <path> Custom PackerLite YAML template; overrides the VM’s stored macOS version or Linux platform. Only required if the stored platform has no built-in template.
--macos-version <macos12\|macos13\|macos14\|macos15\|macos26\|macos27> macOS version to use for picking the built-in template, overriding the VM’s stored osName. Former marketing names are still accepted as input. No effect for Linux.
--var <key=value> Sets a template variable (${var.key}), repeatable.

caked provision refuses to run if the VM is currently running or has already been provisioned — first boot only happens once, so re-running against an already-provisioned VM would just hang waiting for screens that no longer appear.

Provisioning debug video recording

For the whole duration of any PackerLite provisioning run (build/create --autoinstall, or a standalone provision), the VM automatically feeds an H.264 .mp4 recording from the periodic screenshots it already takes every 5 seconds (the same mechanism behind screenshot.png/the GrandCentral stream) — handy for figuring out after the fact why a boot_command template misbehaved, without having had to watch the live VNC session. The video is written to provision.mp4 at the root of the VM’s directory (alongside screenshot.png, config.json, etc). The format is deliberately plain — standard H.264 inside a regular .mp4 container, never ProRes or Apple-only HEVC-in-MOV — so it plays anywhere (VLC, QuickTime, a browser, Windows Media Player) with no extra codec needed. Since it’s only about one frame every 5 real seconds, the video isn’t smooth — that’s expected, it’s a debugging aid, not a screen recording.

  • Provisioning succeeds: the video is deleted automatically, nothing is left on disk.
  • Provisioning fails: the video is kept, and its location is appended to the failure reason returned by caked provision/caked build --autoinstall and cakectl provision/cakectl build --autoinstall — no need to go hunting for it on the filesystem.

This recording honors the existing screenshot opt-out (UserDefaults’s NoScreenshot) — if it’s set, there’s no frame source and therefore no video either. See Sources/cakedlib/PackerLite/ProvisioningVideoRecorder.swift (the recorder itself), VirtualMachine.swift (starting/feeding the recorder off the existing screenshot timer), and VMLocation.provisioningVideoURL.

record: recording a boot_command template by hand

Writing a boot_command template by hand means guessing coordinates and timing, then iterating against a real boot. caked record <vm> does the reverse: it boots <vm> (already built, but not running yet — typically a VM created without --autoinstall, so it’s sitting at its first-boot screen), opens a local window, and records every click and keystroke you perform through it by hand. Press Ctrl-C in the terminal to stop recording — the matching boot_command template is then written to disk.

This capture works directly off the local window’s own native NSEvents (VNCVirtualMachineView.actionRecorder) — no VNC server is started and no network port is opened. That’s deliberately simpler and more direct than tapping a VNC server (still how caked provision itself works): no VNC-protocol keysym round-trip, just the events macOS already delivers to the window. The trade-off is that this capture can only be driven by an operator sitting at this host — unlike caked provision, it can’t be driven by a remote VNC client.

# Record a session to the default file (record.packerlite.yaml, inside the VM's own directory)
caked record my-vm

# Pick a different output location
caked record my-vm --output ./my-template.packerlite.yaml

Local-only (caked record) for now — no cakectl/gRPC counterpart yet, same as caked provision when it first shipped. Scripts/record.sh automates the usual manual steps around a recording session (deletes any existing same-named VM, duplicates the vanilla template, runs caked record with debug logging and the right output path).

Caker.app offers the same recording feature directly inside the VM window (for a VM running in the app, not external/remote) — the toolbar’s Record button, with the same locate-mode/Reset/VoiceOver controls described below, no command line needed.

While recording

  • Pause/resume: the recording window’s toolbar shows a button — a pulsing “Recording” button while capturing (tap to pause), a hollow “Paused” button while paused (tap to resume). Pausing only suspends action capture; the VM keeps running either way. Ctrl-C is still the only way to actually stop recording and write the file, whether paused or not.
  • OCR-assisted clicks: a “locate mode” toggle button in the recording window’s toolbar highlights every piece of recognized on-screen text in blue (Vision OCR). Once armed, the left mouse button on a highlighted region records a <clickText text='...'> token, and the right mouse button on a highlighted region records a <locate text='...'> token — both instead of a raw coordinate-based <click point="X,Y">, an anchor that’s more resilient to small layout shifts than a bare coordinate. A left-click outside any highlighted region (or with locate mode off) still records the usual <click point="X,Y">; a right-click outside any highlighted region records nothing at all (unlike the left button, there’s no coordinate fallback for the right button, since <locate> only makes sense as an OCR anchor). This mode is an explicit button toggle, never a held key — so it can never conflict with a real macOS shortcut you might need to record verbatim (e.g. Fn+F5 for VoiceOver).
  • VoiceOver button (macOS VMs only — hidden for Linux VMs): toggles VoiceOver and records a <voiceOverOn>/<voiceOverOff> token (see the token table above) instead of the raw key sequence. A plain click records an unconfirmed toggle; Option-click records a confirmed one (confirm=true), for the “Use VoiceOver?” dialog that only appears the very first time it’s enabled.
  • Wait gaps before <clickText>/<locate> fold into their own timeout=: every other step type still gets a separate <waitNs> for a ≥1s gap. But <clickText>/<locate> already poll, via OCR, for their text to appear (up to a timeout= in seconds) instead of firing blind — a separate <waitNs> in front of either would just be redundant. The recorder instead folds the measured gap (rounded to the second, plus a flat 10s of slack for OCR recognition/rendering latency) straight into the token’s own timeout=, e.g. <locate text='...' timeout=13> for a 3.4s gap. A gap below the 1s threshold forces no timeout= override either — the parser’s own 10s default applies as usual.
  • Linux VMs: the first recorded action is automatically routed into pre_boot_command: instead of boot_command: (useful for a GRUB-navigation keystroke sent before the installer has an IP) — macOS VMs never get this field. This is a coarse heuristic — check the generated file’s pre_boot_command/boot_command split, it may need a manual tweak.

What comes out

The result is a first draft, not a finished, reliable template: clicks become <click point="X,Y"> tokens, typed text is coalesced into one line per continuous run of keystrokes, special keys and modifiers (<enter>, <tab>, <leftShiftOn>/<leftShiftOff>, etc.) use the same token vocabulary as hand-written templates — but pauses between actions become fixed-delay <waitNs> steps (except in front of <clickText>/<locate>, see above). This project has deliberately moved away from fixed delays in favor of OCR-synced <locate> anchors, precisely because fixed delays are unreliable (see the provisioning section above) — treat the result as a starting point to harden with <locate> anchors before relying on it for unattended --autoinstall runs.

Account credentials (the VM’s own --user/--password) are never written out in plaintext: any recorded text that exactly matches the VM’s configured username or password is automatically replaced with ${var.username}/${var.password}.