DispatchShield

caffeinate has been keeping Macs awake since forever.

But I didn't just need my Mac awake.

I needed it awake, running a computer use agent, with the screen blacked out and input blocked so nobody in the office could touch it while I stepped away.

That's DispatchShield.

macOS Kiosk Mode crossed my mind too.

But Kiosk Mode locks the session — and a locked session kills the agent.

The problem with running computer use agents at the office: you can't leave your laptop unlocked, awake, and active while you step away.

So I built DispatchShield. A macOS menu bar app that blacks out your screen and blocks all input while keeping your machine unlocked so your agent keeps running.

The agent works. The screen is dark. Nobody touches your laptop.

---

DispatchShield is a macOS menu bar utility for a specific but increasingly important workflow:

keep a Mac awake and available for remote or autonomous computer-use agents, while preventing casual physical use of the machine by people nearby.

It is designed for people running long-lived background work at a desk, in an office, or in a shared environment where leaving the computer visibly open is not acceptable, but putting the machine fully to sleep would interrupt the work.

Project Aim

DispatchShield exists to make this workflow practical:

• an agent keeps working on the current user session
• the local screen is visibly shielded
• local keyboard and pointer input are blocked
• the system stays awake instead of drifting into sleep
• the user still has a deliberate reclaim path

This is not a replacement for macOS account security, MDM, or endpoint protection. It is a session-shielding tool for supervised local environments.

The Problem We Are Solving

Modern computer-use agents often need a live desktop session to continue operating. That creates an awkward gap between two bad options:

1. Leave the machine fully open.
2. Lock or sleep the machine and interrupt the work.

DispatchShield is an attempt to create a third option:

• the machine remains operational for the active session
• the display clearly shows that it is intentionally controlled
• nearby users cannot casually interact with the keyboard or pointer
• the operator retains an intentional reclaim path

Key Challenges

This project exists because the operating system does not provide a neat first-class mode for this workflow.

The hard parts are:

• blocking local input without terminating the user session
• keeping the machine awake without permanently weakening OS security settings
• handling sleep, wake, and session transitions safely
• distinguishing "remote automation should continue" from "local user is reclaiming control"
• recovering from privacy-permission instability after app reinstalls or permission changes
• doing all of that with public macOS APIs and predictable behavior

Challenges We Experienced Building It

The implementation surfaced a number of real macOS constraints:

• Screen wake is not the same thing as successful session authentication. Early reclaim logic tied disengage to wake events, which was not reliable.

• Session notifications are not a complete unlock API. NSWorkspace activation and resignation events help, but they are not a perfect "user just unlocked" signal.

• Accessibility and Input Monitoring permissions are fragile across reinstall cycles. Even when the user has previously granted access, macOS can require the exact installed app copy to be removed and re-added.

• A session event tap is powerful but operationally fragile. If the tap is disabled by the system and not recovered properly, the app can appear shielded while input is no longer blocked.

• Keychain calls on the main thread can become a real runtime problem. During testing, passphrase availability checks in the wrong path caused activation stalls and required redesign.

• A local control socket is convenient, but unsafe by default. We had to harden it with a per-user path, owner-only permissions, peer checks, and a control token to avoid trivial bypass.

Current Approach

DispatchShield uses a layered model:

• a full-screen overlay on all displays
• a session-level event tap that swallows keyboard and pointer input
• power assertions to keep the system awake
• a local reclaim passphrase flow
• a local Unix socket for trusted automation control

The reclaim path is deliberate:

• hold both Shift keys for 2 seconds
• enter the configured passphrase
• press Return

Features

• Menu bar app with no normal Dock workflow
• Full-screen shield overlay across all displays
• Input interception using a session event tap
• Idle sleep suppression while active
• Local passphrase reclaim flow
• Remote/local automation control through a hardened Unix socket
• Appearance customization for shield text and accent color
• Sleep and wake lifecycle handling
• Safety timeout support through heartbeats

Security Model

DispatchShield aims to reduce opportunistic local interaction, not to provide cryptographic workstation isolation.

What it does:

• blocks normal local keyboard and pointer input while shielded
• makes the machine appear intentionally unavailable
• requires a deliberate reclaim action
• restricts socket control to the same user plus a generated control token

What it does not do:

• harden the operating system globally
• replace account login, FileVault, or MDM controls
• prevent a privileged local administrator from changing the machine
• guarantee the same behavior across every macOS version forever

Installation

Prebuilt App

1. Build or download DispatchShield.dmg
2. Drag DispatchShield.app to /Applications
3. Launch the app once
4. Grant permissions in:
   • System Settings -> Privacy & Security -> Accessibility
   • System Settings -> Privacy & Security -> Input Monitoring

Important:

If you reinstall the app, macOS may require you to remove and re-add the /Applications/DispatchShield.app copy in those permission panels.

Build From Source

swift build
./scripts/build-dmg.sh

Artifacts are generated in build/.

First Run

1. Open DispatchShield
2. Set your overlay message and accent color
3. Configure a local reclaim passphrase
4. Click Start Using Shield
5. Grant the required permissions
6. Use the menu bar item to engage the shield

Automation Control

DispatchShield exposes a local control channel for trusted same-user automation.

Use the helper script:

dispatch-shield-ctl status
dispatch-shield-ctl engage
dispatch-shield-ctl disengage
dispatch-shield-ctl heartbeat
dispatch-shield-ctl relaunch

The project no longer uses a world-accessible /tmp socket. Control now goes through a per-user runtime directory and tokenized local socket flow.

Open Source Priorities

This project is open sourced for people who want to:

• study the macOS mechanics behind session shielding
• improve the reclaim and permission experience
• strengthen the security model further
• adapt the tool for other local-agent workflows
• validate behavior across macOS versions and hardware setups

Good contribution areas:

• more reliable permission diagnostics
• better event-tap recovery and fail-closed behavior
• improved reclaim UX
• telemetry and debugging tools
• installer/signing/notarization improvements
• documentation and compatibility testing

Roadmap

• finish end-to-end passphrase reclaim validation across real installed builds
• improve permission-state detection and recovery guidance
• add better runtime diagnostics for engage failures
• document threat model and operational limits more clearly
• harden packaging and distribution workflows
• add tests where macOS APIs make them practical

Project Status

This is an actively evolving macOS utility, not a finished security product.

The core idea is valuable and the implementation is usable, but the project still has platform-friction areas, especially around TCC permissions and live macOS behavior under reinstall/regrant cycles.

That is precisely why it is useful as an open source project.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

Code Of Conduct

See CODE_OF_CONDUCT.md.

License

MIT. See LICENSE.