Security · Entitlements

App Sandbox vs. Hardened Runtime: What Mac Developers Actually Need

App Sandbox and Hardened Runtime are different protections, not competing distribution options. A Mac app can use both. Confusing them often leads to unnecessary entitlement exceptions or a release that works in Xcode but fails on a customer’s Mac. Here is what each layer does and how to choose a configuration deliberately.

By Francisco Cantu ·

Five layers with five different jobs

App Sandbox: limit what the process can access
Restricts access to resources such as files, network connections, and hardware. Entitlements and supported user-mediated mechanisms grant specific capabilities.
Hardened Runtime: protect how the process executes
Protects against classes of code injection, library hijacking, and process-memory tampering. Targeted exceptions exist for legitimate needs such as some JIT workloads.
Code signing: identify and seal the code
Developer ID signing is the standard Apple identity for apps distributed outside the Mac App Store. Signed code includes an integrity seal and its entitlements.
Notarization: Apple’s automated distribution check
Apple inspects submitted software and, on acceptance, issues a ticket. It is not App Store review and does not prove an app is bug-free.
Privacy permissions: user consent
macOS separately controls access to sensitive capabilities such as Accessibility, screen recording, microphone, and camera. Signing or notarization does not grant consent.

What each distribution channel requires

Mac App Store: App Sandbox is generally required, alongside the store’s signing, submission, and review requirements. Confirm any applicable exceptions with Apple’s current rules. Store distribution is not the same as submitting a Developer ID archive to the notarization service.

Outside the store: App Sandbox is optional for the Developer ID distribution path. Hardened Runtime is required for the notarization workflow described by Apple. You can still choose to sandbox a directly distributed app when its features fit.

“Unsandboxed” does not mean unrestricted. macOS privacy controls, file permissions, System Integrity Protection, and other protections still apply. Direct distribution does not automatically authorize access to other apps or every user file.

For channel trade-offs rather than entitlement mechanics, read Developer ID versus the Mac App Store.

Start with capabilities, not with disabling Sandbox

Inventory the resources your app needs. A document app may use user-selected files and security-scoped bookmarks rather than require broad filesystem access. Network clients and servers have distinct sandbox capabilities. Extensions and helper processes require their own review.

  • User-picked documents: evaluate file access through supported open/save panels and preserve access correctly across launches.
  • Automation: investigate supported Apple Events mechanisms, sandbox restrictions, purpose descriptions, and user consent for your specific target apps.
  • External tools: distinguish a bundled helper from a tool installed at an arbitrary path. Review subprocess permissions, signing, and sandbox behavior rather than assuming it inherits everything you want.
  • Global interactions: a global hotkey is not categorically prohibited. Accessibility-driven control, event monitoring, and screen capture can have different constraints.

Temporary sandbox exception entitlements are not blanket permission to bypass store rules. If a central feature cannot work within supported restrictions, direct distribution may be the better channel; document that decision instead of accumulating unexplained exceptions.

Enable Hardened Runtime; add exceptions only with evidence

Enable Hardened Runtime for your release target in Xcode’s Signing & Capabilities settings. Test the Release build without a debugger. A crash that disappears after adding every exception is not a diagnosis.

  • JIT execution: some language engines need specific runtime support. Follow the engine’s current macOS guidance and Apple’s entitlement documentation.
  • Library validation: loading third-party plug-ins may need deliberate handling. Disabling library validation weakens a protection; it is not a default setting for every framework.
  • Unsigned executable memory: do not enable broad executable-memory exceptions merely because an AI assistant suggests them. Identify the actual engine and its requirements.
  • Debugging: development entitlements such as com.apple.security.get-task-allow should not be enabled in the distributed Developer ID release.

Embedded helpers and frameworks can have different needs from the main app. Inspect the relevant executable’s signature and entitlement set, not just the top-level target.

Inspect the artifact you will actually publish

Read-only signature and entitlement checks

# Replace MyApp with your app's name.
codesign --display --verbose=4 "MyApp.app"
codesign --display --entitlements - --xml "MyApp.app"
codesign --verify --deep --strict --verbose=2 "MyApp.app"
spctl --assess --type execute --verbose=4 "MyApp.app"

In signature output, check the signing authority, bundle identifier, and runtime flag. In entitlements, look for com.apple.security.app-sandbox, enabled runtime exceptions, and unwanted development settings. Entitlements may be absent on executables that do not require them.

The --deep option above is for verification. Do not treat codesign --deep --force as a universal signing repair: nested code must be signed in the correct order with its intended identity and entitlements.

Run these checks on the extracted download too. Modifying resources after signing, replacing a helper, or repackaging the wrong build can invalidate assumptions established during your local build.

Test permissions separately from notarization

Notarization acceptance does not approve Accessibility access, Screen Recording, Full Disk Access, or other user-controlled permissions. Some capabilities require usage-description keys or additional entitlements. Requirements vary by API and macOS version.

Use a clean account to test first launch, the explanation before a permission prompt, denial, later approval, and revocation while the app is running. Don’t make users grant Full Disk Access if a narrower supported mechanism is enough.

Keep the app’s identity and installation behavior consistent across updates, and test permissions through a real upgrade. Never promise that rebuilding or moving an app will preserve every permission in every environment.

A practical decision checklist

  1. Write down the capability list and supported macOS versions.
  2. Choose the distribution channel based on those capabilities and the applicable review rules.
  3. Use Sandbox where it fits; do not confuse it with Hardened Runtime.
  4. Enable Hardened Runtime for Developer ID notarization and justify each exception.
  5. Inspect entitlements on the app and every relevant helper.
  6. Sign, notarize, staple, then test the browser-downloaded artifact.
  7. Verify permission denial and a real old-to-new update.

If the submission fails, use the notarization errors guide. If the download fails to open, use the Gatekeeper troubleshooting guide. Neither failure is a reason to switch off system security.

Simplify your next release with HarborPilot.

Once your target’s security configuration is intentional and tested, HarborPilot can repeat the build, signing, notarization, stapling, and Sparkle preparation workflow. Your entitlements remain a product decision—not a shortcut a release tool should invent.

Sources and further reading

Service limits and Apple requirements can change. Check the linked documentation before publishing. HarborPilot is not affiliated with Apple, Cloudflare, or the Sparkle project.