The Mac that logs you in and shows you nothing

A customer opens their Mac in the browser. The connection succeeds. The username and password are accepted. Then the screen is black. Not an error, not a disconnect. Black, with a mouse cursor that moves.

Every log says the machine is fine. The Screen Sharing service is running. The account authenticates. The session is unlocked. Disk, CPU and memory are normal. Nothing anywhere reports a problem.

This cost us several days. Here is what it actually was, and why the obvious ways to test for it are worse than useless.

Everything obvious is wrong

A headless Mac with a black screen has a familiar list of suspects. We worked through all of them.

• No display attached. The usual advice is a dummy HDMI plug. We bought them. No change.
• Resolution. A headless Mac can come up at a size some clients dislike. It was not that.
• The screen lock. A locked session can serve black. The session was unlocked.
• The display itself. We attached a real monitor to a real Mac mini. The physical screen was black too.

That last one is what redirected the search. The machine was not failing to send a picture to a remote client. There was no picture.

Running is not the same as permitted

Our provisioning script turns Screen Sharing on the only way that works without a human present:

launchctl enable system/com.apple.screensharing
launchctl bootstrap system   /System/Library/LaunchDaemons/com.apple.screensharing.plist

That starts the service. Since macOS 14, Apple's own kickstart -activate refuses to run headless, so this is what is left.

But starting the service is not the same as granting it permission to record the screen. Screen recording is a TCC privilege. macOS grants it in exactly two ways: a human switches Screen Sharing on in System Settings and authenticates, or MDM pushes a PPPC profile.

Without that grant the service still runs. It still listens on port 5900. It still accepts your password. It just has nothing it is allowed to show you.

macOS will say so, if you ask it the right question:

$ sudo .../ARDAgent.app/Contents/Resources/kickstart     -configure -access -on -users runner -privs -all

Screen recording might be disabled. Screen Sharing or Remote
Management must be enabled from System Settings or via MDM.

Why we did not find it sooner

This is the part worth passing on. The problem was not that the answer was hidden. It was that every cheap way to check told us things were fine.

screencapture over SSH always fails. Run it in an SSH session and TCC denies it, whether or not the privilege is granted. It cannot distinguish a broken machine from a working one, so every result it gave us was noise.

The kickstart probe passes when it has no privilege. Without enough rights it prints nothing at all. Code that treats empty output as absence of a warning reads that as success. Ours did.

Both checks share one property: their failure output is identical to their success output. A check like that is not weak evidence. It is no evidence, dressed as reassurance.

Measure the picture

The only trustworthy test is the thing the customer sees. We connect as a real VNC client, pull one framebuffer rectangle, and measure it. A black desktop is two colours at near zero brightness. A working one is not.

desktop        : Mac mini  1920x1080  32bpp depth24
sampled        : 273768 pixels from 1 rect(s)
mean brightness: 36.31%
distinct colours: 93828
RESULT: REAL PICTURE

Ninety three thousand distinct colours is a desktop. Two is a failure. There is no interpretation needed, and no exit code to misread. This now runs on every machine before a customer is allowed near it.

The fix, and what it costs

On one machine the fix takes ten seconds. Open System Settings, General, Sharing. Turn Screen Sharing off. Turn it back on. It asks for an administrator password, and that authentication is the whole point. The switch usually already looks on, because the script started the service. Toggling it anyway is what grants the privilege.

The grant is system level, so it survives wiping the machine between customers. We verified that by wiping a unit and checking again.

The real cost is that it needs a human at the machine, once, which is the only manual step in an otherwise scripted process. At fleet scale the answer is an MDM configuration profile that grants the privilege up front. That is the right fix, and it is the one thing you cannot script your way around on a Mac you have not enrolled yet.

If you automate Macs

Two things are worth taking away, and only one of them is about screen recording.

The first is that macOS has a category of state a script cannot reach. TCC privileges are deliberately gated behind a human at the keyboard or an MDM profile. If your automation assumes it can configure everything, it will eventually produce a machine that looks provisioned and is not.

The second is more general. Before you write a check, ask what it prints when the thing is broken. If that matches what it prints when the thing works, the check is worthless. It will cost you more time than having no check at all. We had two of those, and they are the reason this took days instead of an afternoon.