Headless setup

This is the guide to follow with the Mac in front of you, before it goes somewhere you cannot reach. Read the whole of step 1 first, because it decides whether this app suits your machine at all.

1. Understand the gap before you start

MoreDisplays is an ordinary app in your user session. It creates its displays when it launches and releases them when it quits.

That means there is a window it does not cover: from power on until you log in, this app is not running, and nothing it does affects what the login window looks like or which display it appears on.

For most people that is fine, because they never see the login window: the Mac has automatic login, or it stays logged in and only the screen sharing session comes and goes. If your machine must be reachable at the login window on a cold boot with no monitor attached, you still need a hardware dummy plug for that window, and MoreDisplays takes over once you are in.

The app does ship a privileged service meant to close that gap, and in this version it is groundwork: it installs, runs from boot and reports its state, and does not present a display at the login window yet. Displays at the login window is the whole story, including why there is nothing to gain from switching it on today.

2. Enable remote login first

You need a way in that does not depend on a display, and every later step assumes you have it.

# systemsetup -setremotelogin on && systemsetup -getremotelogin
Remote Login: On

$ ssh admin@rack-mini.local 'sw_vers -productVersion'
26.3

If the connection is refused, check System Settings, General, Sharing, Remote Login, and confirm your account is in the allowed list. Do not continue until this works.

3. Enable screen sharing

The display is what you are about to create. Screen sharing is what looks at it. Turn it on in System Settings, General, Sharing, and confirm a client connects while the monitor is still attached.

If you plan to use a third party client such as Jump Desktop or Screens, install and test it now. Remote clients has notes per client.

4. Check that virtual displays work on this machine

Before building anything, confirm the private interface works on this Mac and this macOS version. From a source checkout that is what make smoke is for.

$ make smoke
creating 5120x1440 virtual display
display 0x4d440001 active, unmirrored, 5120x1440
holding 5s
released
smoke: ok

If it fails, the app will tell you the same thing in Settings, as Virtual displays are unavailable on this Mac, with the reason. Run this again after every macOS update: it is the fastest way to find out whether an update broke the private interface.

5. Build the group you will actually use

Pick the size from the client you will connect with, not from the monitor currently attached. The catalogue is the shortcut: an iPad Pro 11-inch template gives you exactly the panel an iPad Pro has.

Set it as the main display of the group, and turn off Include physical displays if you want the group to be about the virtual one only.

6. Turn on activate on launch

This is what makes the setup come back by itself. The app applies the marked group as part of its launch sequence, after orphan cleanup and after the kill switch is checked.

Pair it with Open at login in Settings, so the app is running in the first place.

$ mdctl status
version: 0.1.0
state: active
active group: Console
groups: Console, Office

If state is idle, the app launched but activated nothing. Check that the group has activate on launch set, and that Allow virtual displays is on: the kill switch stops every creation, deliberately and silently.

7. Reboot with the monitor still attached

This is the rehearsal. You want to see the machine come back before you remove your ability to see anything.

# shutdown -r now
Shutdown NOW!

Log in, then check from another machine that the group came up. If your Mac logs in automatically, this is also where you find out whether that is configured the way you think it is.

8. Unplug the monitor

$ mdctl status
version: 0.1.0
state: active
active group: Console
groups: Console, Office

Connect with your screen sharing client. You should get the desktop the group describes.

If the client shows a black screen, the display exists but the session is not being composited to it. Reconnect the client first; Troubleshooting has the rest.

9. Build the rest of the groups

One per desk is the usual pattern, and the names should say where you are.

$ mdctl list
Home
Office
MacBook Air 13-inch (M1)

Give each one a keyboard shortcut. A shortcut arrives through a screen sharing session, so it is a way to switch setups from a client with no terminal.

10. Prove you can recover

Break it on purpose while you can still walk to the machine. Quit the app.

$ osascript -e 'quit app "MoreDisplays"' ; mdctl status
mdctl: MoreDisplays is not running

Every virtual display goes with it, and your screen sharing session ends. Reopen the app over SSH and watch the group come back.

$ open -a MoreDisplays && sleep 3 && mdctl status
version: 0.1.0
state: active
active group: Console
groups: Console, Office, MacBook Air 13-inch (M1)

If that works, the machine can recover from the worst thing that happens to it in normal operation, over a connection that does not depend on a display.

Next

• Switching without the window for hotkeys, the URL scheme and launch behaviour.
• Remote clients for advice specific to your client software.