DEV Community

Christopher Hoeben
Christopher Hoeben

Posted on • Originally published at stickwithfiddle-sys.github.io

How to Notarize and Sandbox Your macOS Sequoia App: A Practical Checklist for Indie Developers

#macossequoia #notarization #sandboxing #entitlements

How to Notarize and Sandbox Your macOS Sequoia App: A Practical Checklist for Indie Developers

A step-by-step guide to adopting Hardened Runtime, configuring the App Sandbox, notarizing your app, and debugging entitlement issues on macOS Sequoia—with a focus on what indie devs actually need to know.

TL;DR: To distribute on macOS Sequoia, you must enable Hardened Runtime and notarize your app. App Sandbox is mandatory for the Mac App Store and strongly recommended for direct distribution. Use correct entitlements like com.apple.security.device.microphone, test with targeted tccutil reset (never global), and verify with codesign. This checklist covers signing, sandbox configuration, notarization, and debugging so your app passes Gatekeeper without surprises.

Understand the Sequoia Security Baseline

Starting with macOS Sequoia, Apple has removed the familiar Control‑click shortcut to open an unsigned app, making notarization the recommended path for all software distributed outside the Mac App Store. For indie developers, the practical baseline is to adopt the Hardened Runtime, notarize every build, and strongly consider sandboxing even for direct downloads. While it is still possible to run unsigned software, the process is now more cumbersome and less user‑friendly. Apple’s guidance now explicitly recommends notarizing all apps distributed outside the store. The NIST National Checklist Program publishes a Sequoia Guidance compliance checklist (Revision 3.0) that addresses system security configurations for macOS 15. This means that the operating system’s default posture is to treat unnotarized code as untrusted, and the simplest way to meet user expectations is to sign with a Developer ID, enable the Hardened Runtime, and submit for notarization. Sandboxing is not mandatory for notarization, but it is required for Mac App Store distribution and is a best practice for limiting the impact of a compromise. Together, these three layers—Hardened Runtime, notarization, and sandboxing—form the Sequoia security baseline that every indie developer should plan for from the first line of code.

Enable Hardened Runtime and Code Signing

Hardened Runtime is mandatory for notarization. Enable it in Xcode, sign with a Developer ID Application certificate, and verify the signature to confirm the runtime flags are present.

In your target’s Signing & Capabilities tab, add the Hardened Runtime capability. This embeds the necessary entitlements and runtime protections. For distribution outside the Mac App Store, select your Developer ID Application certificate in the Signing Certificate dropdown.

The entitlements file will include com.apple.security.get-task-allow only for development builds. Xcode automatically strips this entitlement when you export a distribution-signed app, so you don’t need to manage it manually. Without Hardened Runtime, notarization will fail because Apple’s notary service requires the runtime hardening flags.

After building, verify the signature and inspect the embedded entitlements with:

codesign -dvvv --entitlements - YourApp.app
Enter fullscreen mode Exit fullscreen mode

Look for flags=0x10000(runtime) in the output. This confirms the Hardened Runtime flag is present. If the flag is missing, double-check that the capability is enabled and that you are signing with a Developer ID certificate, not a development certificate.

Configure the App Sandbox (Entitlements)

To sandbox your app, set the com.apple.security.app-sandbox entitlement to true in your entitlements file, then add only the specific capabilities your app requires. This is mandatory for Mac App Store distribution and strongly recommended for all other apps.

Start by creating or editing your app's .entitlements file. The minimal sandbox declaration looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
</dict>
</plist>
Enter fullscreen mode Exit fullscreen mode

Next, add only the entitlements your app genuinely needs. Over‑privileging defeats the purpose of sandboxing. Common entitlements include:

  • Outbound network connections: com.apple.security.network.client
  • User‑selected file access (read‑only): com.apple.security.files.user-selected.read-only
  • Microphone access: com.apple.security.device.microphone

A frequent mistake is omitting the microphone entitlement. Without com.apple.security.device.microphone, the system will never prompt for permission, and audio input will be silent. Always test with the smallest set of entitlements possible to avoid an over‑privileged build. If your app needs to open files outside the sandbox, use the com.apple.security.files.user-selected.read-only or com.apple.security.files.user-selected.read-write key, which grants access only to items explicitly chosen by the user through the standard open/save dialog. For debugging permission issues, reset the TCC database for your app specifically with tccutil reset Microphone com.yourcompany.yourapp—never omit the bundle ID, as that resets permissions globally for all apps.

Notarize Your App

Notarization is mandatory for apps distributed outside the Mac App Store on macOS Sequoia; without it, Gatekeeper will block the app by default. The process requires a valid Developer ID signature and Hardened Runtime enabled, then you upload the archive to Apple for automated scanning and staple the resulting ticket to your app.

First, ensure your app is signed with a Developer ID certificate and has Hardened Runtime enabled. Build and export your app, then create a zip archive:

zip -r YourApp.zip YourApp.app
Enter fullscreen mode Exit fullscreen mode

Submit the archive for notarization using xcrun notarytool. Replace the placeholders with your Apple ID, team ID, and the path to your zip file. The --wait flag makes the command block until the process completes:

xcrun notarytool submit YourApp.zip --apple-id your@email.com --team-id YOURTEAMID --wait
Enter fullscreen mode Exit fullscreen mode

Once the submission is approved, staple the notarization ticket to the app. This embeds the ticket so Gatekeeper can verify it offline:

xcrun stapler staple YourApp.app
Enter fullscreen mode Exit fullscreen mode

Verify the stapling succeeded:

xcrun stapler validate YourApp.app
Enter fullscreen mode Exit fullscreen mode

A successful output will show The staple is valid.

Note that notarization requires Hardened Runtime, but App Sandbox is not a prerequisite for notarization itself. App Sandbox is mandatory only for Mac App Store distribution, though it is strongly recommended for all apps to limit the impact of potential vulnerabilities. The NIST National Checklist Program provides a macOS Sequoia compliance guide (Checklist 1248) that addresses system security configurations for macOS 15. For debugging notarization failures, examine the JSON log returned by the notarytool command, which details any issues found during Apple’s automated scan.

Test and Debug Entitlement Issues

To debug entitlements that aren't working, first confirm the binary actually contains the keys you expect with codesign -d --entitlements - /path/to/YourApp.app. If a permission like microphone access is granted but silent, reset the TCC database for only your app using tccutil reset Microphone com.yourcompany.yourapp—never omit the bundle ID, as that would revoke the permission for every app on the system.

Start by dumping the embedded entitlements. This reveals exactly what the operating system sees at launch, so you can catch missing or misspelled keys immediately. A common mistake is using the wrong entitlement for audio input; the correct key is com.apple.security.device.microphone.

codesign -d --entitlements - /path/to/YourApp.app
Enter fullscreen mode Exit fullscreen mode

If the output lacks the expected key, add it to your entitlements file and re-sign. When the entitlement is present but the feature still fails—for example, the microphone appears in System Settings > Privacy & Security yet produces silence—the issue is often a stale TCC record. Reset it surgically:

tccutil reset Microphone com.yourcompany.yourapp
Enter fullscreen mode Exit fullscreen mode

Omitting the bundle ID (e.g., tccutil reset Microphone) resets the permission globally for all apps, which is disruptive and makes debugging imprecise. Always target your own bundle.

For real-time feedback on sandbox denials, monitor the sandbox subsystem. This stream surfaces every time the sandbox blocks a resource your app hasn't declared, helping you identify missing entitlements as you exercise the feature.

log stream --predicate 'subsystem == "com.apple.sandbox"'
Enter fullscreen mode Exit fullscreen mode

Run this in a terminal, then trigger the failing action in your app. The log will show denials like deny mach-lookup or deny file-read-data, pointing directly to the entitlement you need to add.

FAQ

Is App Sandbox required for notarization?

No. Hardened Runtime is required for notarization. App Sandbox is required for Mac App Store distribution and strongly recommended for all apps, but it is not strictly required for notarization outside the App Store. They are often used together but serve different purposes.

What happens if I forget the microphone entitlement?

Your app will not be able to access the microphone, and the system will never show a permission prompt. You must add com.apple.security.device.microphone to your entitlements file and rebuild.

How do I reset microphone permission for my app during testing?

Use tccutil reset Microphone com.yourcompany.yourapp to reset only your app’s permission. Avoid tccutil reset Microphone without a bundle ID, as that resets the permission for all apps on the system.

Can I still run an unsigned app on macOS Sequoia?

Yes, it is still possible to run unsigned apps, but the Control-click shortcut to bypass Gatekeeper has been removed. You must manually allow the app in System Settings > Privacy & Security, which is more cumbersome for users.

Do I need to notarize if I distribute only through the Mac App Store?

No. App Store distribution handles notarization automatically. However, you still need to enable App Sandbox and include the appropriate entitlements for your app’s functionality.

References for further reading

Sources consulted while researching this guide, included so you can verify the details and go deeper. Listing them is not a claim that every line was independently fact-checked.

I packaged the setup above into a ready-to-use kit — **macOS App Distribution Survival Pack: Notarization + Sandbox + Sequoia* — for anyone who'd rather copy-paste than wire it from scratch: https://unfairhq.gumroad.com/l/rmstlf.*

Top comments (0)