# Headless Apple silicon Mac virtual display and the interactivity watchdog > Creating a virtual display from code uses Apple's `CGVirtualDisplay` API, which a standalone unsigned script cannot use: a Swift script that compiled and ran created nothing, silently, and the author concluded the API needs entitlements held by a signed app. Parent: [Mac local LLMs: Serving ops and multi-model](https://llms-explorer.com/tree/mac-local-llms-serving-ops-and-multi-model/) · 2 facets · 22 facts · page: https://llms-explorer.com/tree/headless-apple-silicon-mac-virtual-display-and-t/ ## Facts - Creating a virtual display from code uses Apple's `CGVirtualDisplay` API, which a standalone unsigned script cannot use: a Swift script that compiled and ran created nothing, silently, and the author concluded the API needs entitlements held by a signed app. — source: `asserted` - BetterDisplay is a signed, entitled app that creates a persistent virtual screen (a 5K one in the source), starts at boot, and exposes an HTTP API that a health monitor can poll and use to reconnect the display after a crash. — source: `asserted` - A managed virtual display changes the resolution and refresh the compositor works at (for example 5K), so GPU compositing load differs from the automatic 1920 by 1080 display; no source measures the effect on long compute command buffers. — source: `asserted` - For a remote desktop session over VNC or Screen Sharing, the automatic display stays at 1920 by 1080 non-Retina; a remote-desktop tool with its own virtual display (Astropad Workbench "Unified Display") creates a matched Retina display for the session instead. Such a session display adds a compositing target while the session is connected. — source: `asserted` - 2022-07: a BetterDisplay (then BetterDummy) user on a headless M1 Mac mini with a 2560 by 1440 virtual display reported a trailing ghost cursor over remote desktop. The thread had 8 replies and no recorded fix in the cached page text. — source: `asserted` - Astropad's dummy-plug article treats the HDMI dummy plug as an Intel-era habit and the automatic virtual display as sufficient on M1 through M4. — source: `asserted` - Silent failure of UI automation: on one headless Mac mini, `screencapture` returned empty files and UI-automation scripts found no windows until a BetterDisplay virtual display was added. The author attributes this to macOS not initializing a graphics context without a display. — source: `asserted` - A display utility that creates the virtual display is a single point of failure for GUI-dependent agents: if it crashes at 3 AM the display disappears, so the source built a monitor that restarts it. — source: `asserted` - Apple's own docs for the managed interface do not exist in the sources found; `CGVirtualDisplay` is not a documented public API in anything fetched. — source: `asserted` - Does a headless Mac with no virtual display, with an automatic one, or with a BetterDisplay one trigger `ImpactingInteractivity` on a long prefill? No source tests this. — source: `asserted` - Does `pmset displaysleepnow` on a headless Mac with a virtual display stop compositing the way it does on a panel? No source. — source: `asserted` - Is the M5 Max `watchdogd` stall specific to a physical panel under load? The only report used a live panel. — source: `asserted` - A Swift script using `CGVirtualDisplay` compiled and ran on a headless Mac mini but created no display; the author says the API requires special entitlements only properly signed apps have. — [source](https://thoughts.jock.pl/p/mac-mini-ai-agent-migration-headless-2026) - BetterDisplay, installed with Homebrew, created a persistent 5K virtual display named "WizDisplay" that starts when the Mac mini boots and has an HTTP API used by a health monitor. — [source](https://thoughts.jock.pl/p/mac-mini-ai-agent-migration-headless-2026) - On that headless Mac mini `screencapture` returned empty files and Peekaboo UI automation silently failed until the virtual display was added. — [source](https://thoughts.jock.pl/p/mac-mini-ai-agent-migration-headless-2026) - The jock.pl author's explanation is that macOS on a headless Mac mini does not initialize a graphics context when no display exists; the page names no Mac model or macOS version. — [source](https://thoughts.jock.pl/p/mac-mini-ai-agent-migration-headless-2026) - Astropad states that M1, M2, M3 and M4 Mac minis create a virtual display on their own, that the default is 1920 by 1080 non-Retina, and that Workbench's Unified Display creates a Retina virtual display for the remote session. — [source](https://astropad.com/blog/dummy-plug-headless-mac-mini/) - Astropad states Intel Macs needed the dummy plug for the GPU to activate with a display, and treats that advice as outdated for M1 and later. — [source](https://astropad.com/blog/dummy-plug-headless-mac-mini/) - A 2022 BetterDisplay discussion reports a ghost trailing cursor on a headless M1 Mac mini using a 2560 by 1440 BetterDummy virtual display over Apple Screen Sharing and Jump Desktop. — [source](https://github.com/waydabber/BetterDisplay/discussions/790) - No source found tests the interactivity watchdog, display sleep, or `AGX_RELAX_CDM_CTXSTORE_TIMEOUT` on a headless Mac with an automatic or managed virtual display. — source: `asserted` - A headless LLM host that must avoid the interactivity kill should not assume a virtual display counts as "display off"; the safe tested mitigations remain the env var plus a display that is actually asleep. — source: `asserted` ## Corrections and disagreements - Does a headless Apple silicon Mac have a working display by default? Side A (Astropad): M1 and later Mac minis create a virtual display automatically, no hardware needed, default 1920 by 1080. Side B (jock.pl): on his headless Mac mini `screencapture` returned empty files and UI automation failed until a BetterDisplay virtual screen existed. The existing dossier windowserver-gpu-contention-and-display-sleep-mi.md asserts Side A ("A headless Apple silicon Mac still runs WindowServer against a virtual display"). CONTRADICTS (partly): windowserver-gpu-contention-and-display-sleep-mi.md. The two accounts can both be true if the automatic display exists for remote-desktop sessions but not for `screencapture` of the console session; neither source says which Mac model or macOS version the second account used. — source: `asserted`