# Mac kiosk setup Download this package and follow the setup steps at https://awake.experiments.team/. For interactive installations on macOS 13 or newer, Intel or Apple Silicon. This package contains an editable installer script, a universal cursor helper, and the helper's Swift source. No Homebrew or Xcode is required when using the included helper. Run as the logged-in installation user; the script requests an administrator password for Chrome installation and power settings. ## Setup 1. In **Shortcuts**, create a shortcut named **Kiosk Focus On**. Add **Set Focus** and configure it to **Turn Do Not Disturb On Until Turned Off**. Run it once to verify it. The installer requires this shortcut unless you explicitly pass `--skip-focus` to handle notifications yourself. 2. In **System Settings → Focus → Do Not Disturb**, use **Allow Notifications From** with no allowed people or apps. Disable repeated calls, time-sensitive notifications, and Intelligent Breakthrough & Silencing where offered. Turn off Share Across Devices and remove schedules that could change Focus. In **Notifications**, disable Allow Notifications / Allow critical alerts for apps that must never interrupt the installation. Focus alone does not block critical alerts or OS security prompts. A script cannot guarantee zero dialogs from every application and the operating system. 3. Unzip the package, open Terminal in its `mac-kiosk` folder, and run: ```bash chmod +x mac-kiosk.command kiosk-cursor ./mac-kiosk.command install --url 'https://your-installation.example' ``` Use your actual URL. `http://localhost:3000` and `file:///...` are also accepted. Alternatively edit `KIOSK_URL` at the top of the script and double-click it. To install Chrome and the other helpers without opening a page automatically: ```bash ./mac-kiosk.command install ``` 4. For unattended startup, set **System Settings → Users & Groups → Automatically log in as** to the installation account. FileVault or organizational policy can prevent automatic login. Chrome, Focus and the cursor helper start in the graphical user session after login. Automatic login is a manual setting; the script does not collect or store your account password. 5. In **System Settings → Energy**, enable power-loss recovery if offered. On macOS 26.5+ with a Mac mini 2024+, iMac 2024+, or Mac Studio 2025+, select **Start up when power is connected → Always**. On these models, disconnect and reconnect power to start again after shutdown; Apple suggests waiting about 30 seconds after disconnecting. Older recovery settings only restart supported Macs after a power failure while they were running. No script can restart a shut-down computer while its power remains continuously on. ## What it configures - Downloads Google's universal Chrome installer only when Chrome is missing, verifies Google's installer identity and macOS signature assessment, and installs to `/Applications`. Existing Chrome installations are reused. - Sets system, display and disk idle sleep timers to never; a login helper holds `caffeinate` assertions as an additional sleep guard. - Sets automatic screen saver idle timeout to zero for this user and this Mac. - Enables advertised `pmset` restart settings and checks readback. Unsupported hardware/settings are reported for manual setup instead of reported enabled. - Reapplies your Focus shortcut at login and every 60 seconds. Shortcut execution success means the shortcut ran; configure its action and DND exceptions as above. - Hides the cursor after 10 seconds without mouse movement, including dragging; restores it on motion (within about 200 ms) or normal helper termination. - Optionally launches Chrome with `--kiosk` and a separate persistent profile; relaunches it if it exits. Browser notification delivery is disabled in this instance. The profile can retain a login for the installation website. - Saves original power/screen saver values once for restoration; repeat installs keep the first backup and replace this package's login helpers. These settings prevent automatic idle sleep. A closed laptop lid, exhausted battery, thermal shutdown, manual locking/sleep, an already-running screen saver, or device-management policy can still interrupt the installation. Use wall power and an open lid or a supported closed-display setup. Scheduled shutdowns and automatic updates should be reviewed before a show. A local website also needs its own server startup configuration. `--kiosk` provides full screen browser presentation; it does not lock down keyboard shortcuts or macOS access. The cursor helper uses public cursor hide/show calls plus the private `SetsCursorInBackground` WindowServer hook so it can work behind Chrome. macOS updates may change this hook. The installer checks symbol availability; verify actual cursor hiding on the target Mac. Errors go to `cursor.log`. The source is included so the helper can be reviewed/rebuilt. The provided binary is ad-hoc signed rather than Apple-notarized; organizational execution policies may block it. ## Maintenance and undo ```bash ./mac-kiosk.command status ./mac-kiosk.command stop ./mac-kiosk.command start ./mac-kiosk.command uninstall ``` `stop` stops the helpers for the current session; they return on next login. Persistent sleep/screen saver values remain until `uninstall`. Stop the helpers before quitting Chrome for maintenance, because it normally relaunches. `uninstall` restores the saved power and screen saver values and removes the login helpers. It keeps Chrome, the kiosk browser profile and backups. DND and any manually configured automatic login/notification settings need manual reset. Files/logs: `~/Library/Application Support/Mac Kiosk/`. The installer is retained there as `setup.command` for maintenance and undo. Login helpers: `~/Library/LaunchAgents/local.mac-kiosk.*.plist`. Custom options: `--idle-seconds 10`, `--focus-shortcut 'Your Shortcut'`, `--skip-focus`. ## Installation check On the installation Mac: run `status`, wait 11 seconds without moving the mouse, then move it; check that the pointer hides and returns while Chrome is in front. Leave the display idle to check screen saver/sleep behavior. Reboot to verify automatic login and Chrome opening the correct URL. Confirm alerts are silenced. Test power-loss recovery separately on the actual hardware before unattended use. Development verification covers shell syntax, universal helper compilation, compatibility-symbol discovery, and generated launchd property lists. The setup script has not been applied to your Mac; kiosk behavior/power cycling has not been tested here. ## References - [Requested reference gist](https://gist.github.com/rettuce/71c801881e1433c3a9de) - [Google Chrome installation and macOS requirements](https://support.google.com/chrome/answer/95346?hl=en) - [Google's package installer deployment guide](https://support.google.com/chrome/a/answer/7550274?hl=en) - [Apple: Shortcuts command-line runner](https://support.apple.com/guide/shortcuts-mac/run-shortcuts-from-the-command-line-apd455c82f02/mac) - [Apple: Focus configuration](https://support.apple.com/en-gb/guide/mac-help/mchl613dc43f/26/mac/26) - [Apple: notifications and critical alerts](https://support.apple.com/en-om/guide/mac-help/mh40583/mac) - [Apple: automatic login and FileVault](https://support.apple.com/en-us/102316) - [Apple: power-on requirements](https://support.apple.com/en-us/125517) - [Apple: Energy settings](https://support.apple.com/en-za/guide/mac-help/-mchlp1168/mac) - [Chromium: command-line switches](https://www.chromium.org/developers/how-tos/run-chromium-with-flags/) - [Apple: cursor hiding API](https://developer.apple.com/documentation/coregraphics/cgdisplayhidecursor(_:)) - [CursorHide: background-cursor hook implementation](https://github.com/ggreer/CursorHide/blob/master/CursorHide/AppDelegate.m) Power settings use the installed `pmset(1)` and `caffeinate(8)` manuals.