Locara

macOS App Sandbox (and Mac App Store)

What it is: Apple’s kernel-enforced sandboxing system for macOS apps. Required for Mac App Store distribution; optional but recommended for direct distribution. Configured via entitlements plist. Most relevant to Locara: This is the enforcement primitive Locara apps should use. The framework’s capability declarations should map directly to macOS entitlements where possible, so the OS does the heavy lifting.

Background

macOS App Sandbox is the desktop sibling of iOS sandboxing — same kernel mechanism, more permissive defaults. Apps that opt in (or are required to, for App Store) are restricted to a per-app container directory, denied arbitrary network/filesystem/IPC by default, and gated by an entitlements file that the developer signs into the binary.

Mac App Store distribution requires sandboxing + Apple-notarized signing. Direct distribution is more flexible but needs notarization for Gatekeeper to allow easy install.

Key design decisions

  • Kernel enforcement via Sandbox Profile Language (SBPL). Not a userland honor system; the kernel actually denies syscalls.
  • Entitlements baked into the signed binary. App can’t escalate at runtime — entitlements are immutable post-signing.
  • Per-app container at ~/Library/Containers/<bundle-id>/Data/. Apps see this as their “home” with redirected ~/Documents, ~/Library, etc.
  • Powerbox for user-selected files. App can’t read ~/Documents directly, but a system file picker can hand it a file with persistent access (security-scoped bookmark).
  • Granular entitlements — separate keys for camera, mic, network client/server, USB, address book, etc.
  • Temporary exceptions for apps that genuinely need it (e.g., reading specific paths outside container).
  • TCC (Transparency, Consent, Control) layer on top — even a sandboxed app must prompt the user before accessing camera/mic/contacts/etc. the first time.
  • More permissive than iOS — devs can ship Mac apps that need full disk access via direct distribution; impossible on iOS.

What worked

  • The container model + Powerbox lets apps work with user data without seeing the whole filesystem. Right balance for desktop.
  • Entitlements are declarative + signed — verifiable property of the app, not a runtime claim.
  • TCC adds a user-consent layer that catches things the static entitlement system doesn’t (e.g., screen recording).
  • App Store apps reliably can’t trash your machine — provable malware in App Store apps is rare-to-nonexistent.

What failed / criticisms

  • Massive friction for power apps. Anything that needs deep system integration (clipboard managers, automation, system utilities) fights sandbox constantly.
  • Powerbox UX is awkward for batch file processing — users have to repeatedly approve.
  • Security-scoped bookmarks complexity. Persisting access to user-selected files across launches is non-obvious to implement.
  • Many devs ship outside the App Store specifically to avoid sandbox. The freedom of macOS direct-distribution made this viable, hurting App Store catalog richness.
  • Entitlement plist is a poorly-documented landmine. “I declared the right entitlement and it still doesn’t work” is a common dev experience.
  • TCC prompts can be confusing or scary to non-technical users.

Specific learnings for Locara

  1. Locara apps should be sandboxed via macOS App Sandbox by default. Free, kernel-enforced, real security. Locara’s runtime sets up the entitlements based on the app’s manifest declarations.
  2. Map Locara capabilities → macOS entitlements 1:1 where possible:
    • network: false → no network entitlements set → kernel blocks
    • fs.user-selected: true → com.apple.security.files.user-selected.read-write
    • device.camera: true → com.apple.security.device.camera
    • device.microphone: true → com.apple.security.device.microphone This means the “fully local” badge isn’t a Locara promise — it’s Apple’s kernel saying so.
  3. Locara also needs its own enforcement layer for things macOS doesn’t model — model loading, tool execution, capability scopes within the app. Defense in depth.
  4. Code signing + notarization is non-negotiable. ~$99/yr Apple Developer Program. Locara CI handles signing and notarization for published apps. Without this, every user hits “unidentified developer” warnings and aborts.
  5. Use the Powerbox / file picker model. Apps that need user data go through a file picker, get a security-scoped bookmark, persist it. Locara’s <DocDropzone> etc. components should encapsulate this so app authors don’t fight it.
  6. Decide: App Store or direct distribution? Both are viable.
    • App Store: stricter sandbox, automatic distribution, Apple takes 30% on paid downloads, Apple does last-mile delivery. Gives users an additional trust layer.
    • Direct (Locara registry): more flexibility (e.g., apps can opt out of sandbox if they really need to, with appropriate warnings), Locara controls distribution end-to-end, no Apple cut.
    • Both: apps published to Locara registry; if they want App Store too, separate submission. Most apps probably direct-only initially.
  7. TCC (camera/mic/screen) prompts are unavoidable and that’s fine. Just expose them through clear runtime affordances.
  8. com.apple.security.app-sandbox = true + minimum entitlements is the Locara default. Apps can request more in the manifest, which surfaces in the install UI.

References