I’m developing an app on macOS where I want a daemon/agent to run only when the user explicitly triggers it using SMAppService. The goal is to start the daemon when needed, perform the required task, and then stop/unload it after completion. Additionally, if unload or unregister calls are missed, I want to ensure that the daemon doesn’t start automatically upon reboot. Instead, it should only run when a specific action is taken. What are the best practices and detailed methods for achieving this clean and controlled behavior?

’m developing an app on macOS where I want a daemon/agent to run only when the user explicitly triggers it using SMAppService. The goal is to start the daemon when needed, perform the required task, and then stop/unload it after completion. Additionally, if unload or unregister calls are missed, I want to ensure that the daemon doesn’t start automatically upon reboot. Instead, it should only run when a specific action is taken. What are the best practices and detailed methods for achieving this clean and controlled behavior?

Hi, we are in the process of exploring how to create an installer for our array of apps. We have come to the conclusion that regular .pkg installers produced by pkgbuild and productbuild are unfulfilling of our expectations. [1] Regardless, our installer needs to place files at privileged locations (/Library/Application Support) so we are looking into how to best solve this problem, with the user having the largest clarity on what they are about to do (so no shady "wants to make changes" dialogs) the least steps to do to install these files in the right place (so no targeted NSSavePanel-s) Now, we have done our light reading via some nicely collected posts on the topic (https://forums.developer.apple.com/forums/thread/708765 for example) and the single missing option in the list of privilege escalation models seems to be a one-time privilege escalation from a GUI app. Our reasons for declaring so: AuthorizationExecuteWithPrivileges is long deprecated and we are trying to build a futureproof solution NSAppleScript is just putting up a shady ("wants to make changes") dialog when trying something like this: $ osascript -e "set filePath to \"/Library/Application Support\"" -e "do shell script \"touch \" & the quoted form of filePath & \"/yyy.txt\" with administrator privileges" Is there another way to request a one-time authorization from the admin to perform such a simple operation as copying a file to a protected location? I know it's possible to externalize and internalize Authorization Rights, but they are just an interface to create extra rights and use them as barriers, because they don't actually pass the required right to further operations based on this documentation. Using SMAppService to register a daemon, which has to be manually allowed by the user adds a lot to the complexity of this installation process, and is something we would like to avoid if possible. (And it's also not the right security model if we want to be honest - we don't want ongoing administrator rights and a daemon) Is there something we haven't taken into consideration? [1] preinstall scripts run after the choices are presented during installation and we would need advanced logic (not the limited JavaScript system/files API provided by Installer JS) - plus, the GUI is obviously very limited in a .pkg :(

I have a process [command line cpp application] which i want to run always such as it should relaunch after a crash, after device startup etc. I created a launchd Property List File with KeepAlive true and placed under /Library/LaunchDaemons. Problem Statements: I have a bash script to start and stop this process. start using: launchctl bootstrap. stop involve these two steps: send SIGTERM signal and wait untill process stops after doing some cleanups launchctl bootout [It doesn't sends SIGTERM] during steps 1 - Process is getting stop, but also getting immediate relaunch by launchctl during step 2 - it getting stop again. is there a proper way so that we can disable KeepAlive temporarily so that process will not launch during step 1? or suggest other ways to handle this?

I was experimenting with Service Management API and Xcode project from https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api and faced some issues with the API. I replaced agent with XPC service and tried to re-register it. Use case is a new app package installation with a newer service binary. In order to get the running service restarted with the new binary it's required to unregister old version and register new one. Otherwise the old version would be still running after app upgrade. The problem is that register fails with "Operation not permitted" error after running unregister which seems to work fine. Experiments with some delays (500ms) between unregister and register seem to help but it's a not a good solution to work around the problem. I'm using open func unregister() async throws with description: The completion handler will be invoked after the running process has been killed if successful or will be invoked whenever an error occurs. After the completion handler has been invoked it is safe to re-register the service. Sample output with no 500ms sleep between unregister and register calls: /Library/Application\ Support/YourDeveloperName/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode unregister && /Library/Application\ Support/YourDeveloperName/SMAppServiceSampleCode.app/Contents/MacOS/SMAppServiceSampleCode register Successfully unregistered LaunchDaemon(com.xpc.example.service.plist) Unable to register LaunchDaemon(com.xpc.example.service.plist): Error Domain=SMAppServiceErrorDomain Code=1 "Operation not permitted" UserInfo={NSLocalizedFailureReason=Operation not permitted} In fact it doesn't seem to be safe to re-register. Any explanation would much appreciated! ===================================================== Side issue #2: I tried to add a similar helper executable as in the original project with register/unregister and put it inside the same app bundle but at a different location like Contents/Helpers/ folder instead of Contents/MacOS. And it always fails with this error: Error Domain=SMAppServiceErrorDomain Code=3 "Codesigning failure loading plist: com.okta.service.osquery code: -67028" UserInfo={NSLocalizedFailureReason=Codesigning failure loading plist: com.okta.service.osquery code: -67028} When I moved the helper binary to Contents/MacOS/ folder along with the main app executable it starts working fine again. Other folders like Resources/XPCServices also don't work. Is it a hard requirement for an executable to be located inside main Contents/MacOS folder in order to be able to call SMAppService register/unregister APIs? I haven't found any documentation regarding this requirement. Thanks, Pavel

When I tried to launch my application from non-gui process (from launch daemon) NSworkspace openApplicationAtURL failed if I tried to run it when my device on the login screen. Everything is working if someone logged in, but on the login screen I have the error The application “TestApp” could not be launched because a miscellaneous error occurred. with code 256 NSWorkspace* workspace = [NSWorkspace sharedWorkspace]; NSWorkspaceOpenConfiguration* config = [NSWorkspaceOpenConfiguration configuration]; config.createsNewApplicationInstance = YES; config.activates = NO; config.promptsUserIfNeeded = NO; config.addsToRecentItems = NO; [workspace openApplicationAtURL: appURL configuration: config completionHandler:^(NSRunningApplication *app, NSError *error) { }]; Sometimes after the third try it works, sometimes not at all. I try to use "open" command, it works on MacOS Sequoia, but not working for operating systems below, I see this error The application cannot be opened for an unexpected reason, error=Error Domain=RBSRequestErrorDomain Code=5 "Launch failed." UserInfo={NSLocalizedFailureReason=Launch failed., NSUnderlyingError=0x600002998120 {Error Domain=OSLaunchdErrorDomain Code=125 "Domain does not support specified action" UserInfo={NSLocalizedFailureReason=Domain does not support specified action}}} All these problems occur only on the login screen. I'm developing screen share utility, so I need somehow to launch my application on the login screen. Could someone please help me understand what is recommended way to launch application on the login screen?

I am using [SMAppService registerAndReturnError:] to register a launch agent from a plist bundled in the app (before the registration call a matching unregister is done via unregisterWithCompletionHandler as suggested by the docs). The non standard thing is that I am doing that in a root gui login with sudo to bootstrap my launch agent into gui/0 domain. This worked well until Sonoma 14.4 - now the call fails with: Error Domain=SMAppServiceErrorDomain Code=125 "Domain does not support specified action" UserInfo={NSLocalizedFailureReason=Domain does not support specified action} which is not really helpful. For now, i've switche to just using launchctl bootout and launchctl bootstrap to get around this, but could anyone elaborate on what has changed? My feeling is that something has changed in the logic that determines the domain - could it be that even with sudo the target domain is gui/ not gui/0 ? As far as I can see there are no ways to specify the domain from the SMAppService APIs right? Also a weird thing is that if run the code in a raw terminal in root gui it works as previously (but out of security, no thing really runs as root, everything is a launch agent under some less privileged user, and before Sonoma 14.4 sudoing with that less privileged user did work for [SMAppService registerAndReturn], now it does not, and what is also strange, doing sudo - and then sudo su also shows the same error code 125.

Context/Project Idea: I'm currently developing a project that consists of a macOS application using Swift and a local Python backend that executes specific tasks such as processing data. The Python backend is the core of this project, while the Swift application is a mere interface to interact with it. These two project parts should be decoupled so the user can theoretically run their own backend and connect the Swift application to it. Likewise, the user should be able to connect to the shipped backend using, e.g. curl. Current plan: My main idea is to use launchctl to launch a launchd agent which runs the Python backend. The script launching the backend will generate an API key stored in a keychain access group. The Swift application can then get that key and access the backend. The user can always get that API key from the keychain if they want to connect to it programmatically. Here are the main questions I have currently: Python Interpreter Consistency: I'm exploring options such as cx_Freeze or PyInstaller to create a standalone Python executable for better system stability. Does anyone have experience with these tools in a macOS environment, or are there other reliable alternatives worth considering? Adding a Launchd Agent to Xcode: How can I add a launchd agent to my Xcode project to manage a Python executable built with cx_Freeze or PyInstaller? What steps should I follow to ensure it functions properly? Keychain Access for Launchd Agent: Is it feasible for a launchd agent to access a Keychain access group? What configurations or permissions are necessary to implement this? Thanks in advance!

I'm working on an enterprise product that's mainly a daemon (with Endpoint Security) without any GUI component. I'm looking into the update process for daemons/agents that was introduced with Ventura (Link), but I have to say that the entire process is just deeply unfun. Really can't stress this enough how unfun. Anyway... The product bundle now contains a dedicated Swift executable that calls SMAppService.register for both the daemon and agent. It registers the app in the system preferences login items menu, but I also get an error. Error registering daemon: Error Domain=SMAppServiceErrorDomain Code=1 "Operation not permitted" UserInfo={NSLocalizedFailureReason=Operation not permitted} What could be the reason? I wouldn't need to activate the items, I just need them to be added to the list, so that I can control them via launchctl. Which leads me to my next question, how can I control bundled daemons/agents via launchctl? I tried to use launchctl enable and bootstrap, just like I do with daemons under /Library/LaunchDaemons, but all I get is sudo launchctl enable system/com.identifier.daemon sudo launchctl bootstrap /Path/to/daemon/launchdplist/inside/bundle/Library/LaunchDaemons/com.blub.plist Bootstrap failed: 5: Input/output error (not super helpful error message) I'm really frustrated by the complexity of this process and all of its pitfalls.

btm_launchagent.txt I have a menu bar app which should be triggered to start when a system extension is successfully installed. The menu bar app is configured as a agent which should be started by SMAppServer. SMAppService register/unregister the agent successfully when the program is running locally. When doing the program installation through JamfNow, which is a MDM system, it fails with following error. I think the problem here is that the backgroundtaskmanagementd trys to register the agent with an invalid uid=-1 or uid: 4294967295(0xFFFFFFFF). 2024-10-02 10:45:33.100537+0200 0x156d4 Activity 0x1b927 88 0 smd: (BackgroundTaskManagement) BTMManager.getEffectiveDisposition 2024-10-02 10:45:33.103478+0200 0x156dd Default 0x1b927 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] effectiveItemDisposition: appURL=file:///Applications/Company%20Agent.app/, type=agent, url=Contents/Library/LaunchAgents/com.Company.agent.notifier.plist -- file:///, config={ BTMConfigArguments = ( ); BTMConfigBundleIdentifiers = ( ); BTMConfigExecutablePath = "Contents/Resources/CompanyNotifier.app/Contents/MacOS/CompanyNotifier"; BTMConfigLabel = "com.Company.agent.notifier"; } 2024-10-02 10:45:33.103544+0200 0x156dd Info 0x1b927 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] effectiveItemDisposition: result=[disabled, allowed, visible, not notified] 2024-10-02 10:45:33.105120+0200 0x156d4 Default 0x1b927 88 0 smd: (BackgroundTaskManagement) [com.apple.backgroundtaskmanagement:main] getEffectiveDisposition: disposition=[disabled, allowed, visible, not notified], have LWCR=true 2024-10-02 10:45:33.105181+0200 0x156d4 Default 0x0 88 0 smd: [com.apple.xpc.smd:all] Found status: 0 for <private> 2024-10-02 10:45:33.240190+0200 0x154da Default 0x0 88 0 smd: [com.apple.xpc.smd:SMAppServiceFactory] Setting up BundleProgram keys for <private> 2024-10-02 10:45:33.240250+0200 0x154da Default 0x0 88 0 smd: [com.apple.xpc.smd:SMAppServiceFactory] Setting up BundleProgram keys for <private> 2024-10-02 10:45:33.240388+0200 0x154da Activity 0x1b92a 88 0 smd: (BackgroundTaskManagement) BTMManager.registerLaunchItemWithAuditToken 2024-10-02 10:45:33.243990+0200 0x156dd Default 0x1b92a 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] registerLaunchItem: pid=3626, uid=-1, type=agent, parentURL=<private>, url=<private>, config=<private> 2024-10-02 10:45:33.244917+0200 0x156dd Default 0x1b92a 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] registerLaunchItem: found existing item: uuid=AC0DBC9B-7A16-443E-ABFC-05DF0F534C08, name=CompanyNotifier, type=managed agent, disposition=[disabled, allowed, visible, notified], identifier=com.Company.agent.notifier, url=Contents/Library/LaunchAgents/com.Company.agent.notifier.plist -- file:/// 2024-10-02 10:45:33.245238+0200 0x156dd Debug 0x1b92a 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] BTMStore: save scheduled. 2024-10-02 10:45:33.245281+0200 0x156dd Debug 0x1b92a 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] RecordSet notification scheduled for uid -1 .... 2024-10-02 10:45:33.252358+0200 0x154da Error 0x0 88 0 smd: [com.apple.xpc.smd:SMAppService] Unable to submit job: <private> error: Error Domain=OSLaunchdErrorDomain Code=112 UserInfo={NSLocalizedFailureReason=<private>} 2024-10-02 10:45:33.252707+0200 0x156d4 Default 0x1b92a 88 0 smd: [com.apple.xpc.smd:all] Update request for identifier: <private> uid: 4294967295 2024-10-02 10:45:33.253190+0200 0x156dd Default 0x1b92a 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] getItemWithIdentifier: identifier=com.Company.agent.notifier, uid=-1 2024-10-02 10:45:33.253759+0200 0x156d4 Error 0x1b92a 88 0 smd: [com.apple.xpc.smd:btm] Error getting BTMItem with Identifier: <private> uid: 4294967295 error: (null) 2024-10-02 10:45:33.253803+0200 0x156d4 Error 0x1b92a 88 0 smd: [com.apple.xpc.smd:all] Unable to find BTMItem for <private> in 4294967295 2024-10-02 10:45:33.253835+0200 0x156d4 Error 0x1b92a 88 0 smd: [com.apple.xpc.smd:all] Update operation returned error: 3, but no reply expected so error will be silent 2024-10-02 10:45:33.661537+0200 0x156dd Debug 0x0 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] sending notification for uid -1, type 131080 2024-10-02 10:45:33.665159+0200 0x154fa Info 0x1b853 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] fetchSFLItemsMatching: type=managed user item app 2024-10-02 10:45:33.665374+0200 0x154fa Activity 0x15dd3 282 0 backgroundtaskmanagementd: (BackgroundTaskManagement) BTMManager.userDataDidChange 2024-10-02 10:45:33.666041+0200 0x154da Activity 0x1b92d 88 0 smd: (BackgroundTaskManagement) BTMManager.userDataDidChange 2024-10-02 10:45:33.666651+0200 0x154fa Debug 0x15dd3 282 0 backgroundtaskmanagementd: (BackgroundTaskManagement) [com.apple.backgroundtaskmanagement:main] -[BTMManager handleUserDataDidChangeNotification:]: uid=-1, type=131080 2024-10-02 10:45:33.666085+0200 0x154da Debug 0x1b92d 88 0 smd: (BackgroundTaskManagement) [com.apple.backgroundtaskmanagement:main] -[BTMManager handleUserDataDidChangeNotification:]: uid=-1, type=131080 2024-10-02 10:45:36.218160+0200 0x154fa Debug 0x0 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] -[BTMStore handleWriteTimer] entered 2024-10-02 10:45:36.218254+0200 0x154fa Debug 0x0 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] -[BTMStore _save] entered 2024-10-02 10:45:36.224738+0200 0x154fa Default 0x0 282 0 backgroundtaskmanagementd: [com.apple.backgroundtaskmanagement:main] BTMStore: store saved to /var/db/com.apple.backgroundtaskmanagement/BackgroundItems-v9.btm Could it be a problem from the MDM system JamfNow or somewhere else? The whole logs is as attached. Thanks!

Hi, I developed a utility app that allows monitoring system activity and usage. It is a sandboxed app distributed via the Mac App Store. Because in the sandbox I cannot fetch enough data about system activity (like processor temperature, fans, etc.), I developed a little Helper app (non-sandboxed), which currently is distributed via my website, and to enable extra features it provides, the user is asked to download and install it manually (it installs itself as a daemon). I'm looking for ways to improve the user experience. Ideally, it would be a button inside the main app, which would download and install the helper app, without asking the user to do more than pressing a button. As far as I understand, in the previous versions of macOS, it would be possible with privileged helpers and SMJobBless, but those are deprecated APIs now. Another way I tried, is simply downloading the installer app from the website, but opening it programmatically from the main app is tricky since it cannot remove it from the quarantine, in other words, it fails with "operation not permitted". Any advice is appreciated!

Hi, I'd like to be able to run my daemon process only in pre-logon mode that can be reach by either reboot the machine prior to provide user credentials, or by log out from current user. So far I couldn't find any useful configuration in the plist file under /Library/LaunchDaemon. Perhaps there's a way to get notification programmatically for when the system enter/exit pre-login mode ? Thanks

Years ago my daemon was since then using SCDynamicStoreCopyConsoleUser() function and now it longer works. Basically the daemon needs to know the user name of who is using the system. If I restart the daemon,after the login, it gets the user name. I tried run a shell command via my daemon ("id -F") and look likes it still picks the root as user name. So, is there a way to get the current user name using Swift? ProcessInfo.userName fails too

Coming from windows development, I'm trying to understand macOS architecture and how to do certain things. I've already read the Root and Login Sessions AND Service and Daemons AND User Switch Notifications documentation so will frame the questions accordingly. On Windows, there's a concept of User Sessions, each of which contain One or more WindowStations, each of which contain One or more Desktops. Each user gets at least 3 desktops (e.g. Login/Lock/UAC, Screensaver, and default desktop). From what I understand about macOS, it only has Sessions and then a single Desktop. Is that correct? i.e. same display surface is used to display user's desktop, screensaver, sudo prompt and lock screen? What about login screen? Does each user get its own login screen process/window running in their session? or is there a common login screen for all users running in one particular session (root?). How does Fast User switching effect login screen? In a daemon, is it possible to get active console session ID? console meaning the session being displayed on the monitor, whether its login screen, lock screen, user's desktop etc. In a daemon, is it possible to get session switch notifications? E.g. user logged-in and now their desktop is being displayed, user logged-out and now we're back on login screen, or user switched to another user (Fast User switching). How do I get notification of such events in daemon? If no user is logged in which session is pre-login agent running in? and after login does the session ID assigned to pre-login agent stay the same and user's session is assigned a new session ID? Is there always one and only one pre-login agent running? Is it possible to launch pre-login agent and user agents on-demand with custom commandline arguments from a daemon?

Hi There, I have to achieve following scenario Track system event on macosx for shutdown and restart and update one plist with same event via launchAgent I have tried following code on launchAgent class MyAgent { init() { let notificationCenter = NSWorkspace.shared.notificationCenter // Register for system shutdown notification notificationCenter.addObserver(self, selector: #selector(handleNotification(_:)), name: NSWorkspace.willPowerOffNotification, object: nil) RunLoop.current.run() } @objc func handleNotification(_ notification: Notification) { var logMessage = "" switch notification.name { case NSWorkspace.willPowerOffNotification: os_log("System is going to shut down at", log: log, type: .default) updatePlistFile(event: "shut down") let fileName = "example.txt" let content = "shut down" createAndWriteFile(fileName: fileName, content: content) logMessage = "System is going to shut down at \(Date())\n" } } } loaded the agent, and tried to restart device, I can't see as it is coming to handleNotification Same code is working fine from sample application but not from launchAgent Is there any restriction is there for NSWorkspace, if is that so, how to track shutdown/restart event from launchAgent or LaunchDaemon Any help will be appreciate

Hello, we are currently working on a plan to migrate our app suite from Developer ID binaries inside a simple pkg installer to macOS app store distribution. The reason we are using an installer is that there are multiple binaries inside that communicate via XPC and we need to install the respective launchd plist in /Library/LaunchDaemons and /Library/LaunchAgents: 1 root daemon 1 agent that has minimal UI and lives in the system menu bar 1 embedded command line utility in user agent 1 embedded FileProvider extension in user agent 1 embedded Action Extension in user agent 1 agent that only does OAuth stuff Looking through Updating helper executables from earlier versions of macOS I can install the root daemon with SMAppService.daemon(plistName:) and the OAuth helper with SMAppService.agent(plistName:). For the main application I only found SMAppService.mainApp which does not accept a property list configuration. Therefore, I have no place to put my MachServices array and so the File Provider extension, the Action Extension, and the embedded command line utility have no way to talk to the user agent. Currently, XPC is used in between these processes: user agent -> root daemon command line utility -> user agent action extension -> user agent file provider extension -> user agent user agent -> file provider extension: that already works through NSFileProviderServicing I know app-to-app communication only works through launchd for security reasons, but these applications are all part of the same app group (except the root daemon obviously). My question is what is the proper way of starting the user agent so XPC from other binaries just work ™️? Any input is much appreciated!

We want to keep our Mac UI app running all the time, when a user is logged into to a mac machine (app resides in /Applications). To achieve this, we can use launchctl from within post-isntall script to load a plist file which resides in /Library/LaunchAgent. How to prevent a user (without admin password) to unload the agent using launchctl from terminal?

Service Management framework supports installing and uninstalling services, including Service Management login items, launchd agents, and launchd daemons. General: Forums subtopic: App & System Services > Processes & Concurrency Forums tag: Service Management Service Management framework documentation Daemons and Services Programming Guide archived documentation Technote 2083 Daemons and Agents — It hasn’t been updated in… well… decades, but it’s still remarkably relevant. EvenBetterAuthorizationSample sample code — This has been obviated by SMAppService. SMJobBless sample code — This has been obviated by SMAppService. Sandboxing with NSXPCConnection sample code WWDC 2022 Session 10096 What’s new in privacy introduces the new SMAppService facility, starting at 07˸07 BSD Privilege Escalation on macOS forums post Background items showing up with the wrong name forums post Related forums tags include: XPC, Apple’s preferred inter-process communication (IPC) mechanism Inter-process communication, for other IPC mechanisms Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

This week I’m handling a DTS incident from a developer who wants to escalate privileges in their app. This is a tricky problem. Over the years I’ve explained aspects of this both here on DevForums and in numerous DTS incidents. Rather than do that again, I figured I’d collect my thoughts into one place and share them here. If you have questions or comments, please start a new thread with an appropriate tag (Service Management or XPC are the most likely candidates here) in the App & System Services > Core OS topic area. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" BSD Privilege Escalation on macOS macOS has multiple privilege models. Some of these were inherited from its ancestor platforms. For example, Mach messages has a capability-based privilege model. Others were introduced by Apple to address specific user scenarios. For example, macOS 10.14 and later have mandatory access control (MAC), as discussed in On File System Permissions. One of the most important privilege models is the one inherited from BSD. This is the classic users and groups model. Many subsystems within macOS, especially those with a BSD heritage, use this model. For example, a packet tracing tool must open a BPF device, /dev/bpf*, and that requires root privileges. Specifically, the process that calls open must have an effective user ID of 0, that is, the root user. That process is said to be running as root, and escalating BSD privileges is the act of getting code to run as root. IMPORTANT Escalating privileges does not bypass all privilege restrictions. For example, MAC applies to all processes, including those running as root. Indeed, running as root can make things harder because TCC will not display UI when a launchd daemon trips over a MAC restriction. Escalating privileges on macOS is not straightforward. There are many different ways to do this, each with its own pros and cons. The best approach depends on your specific circumstances. Note If you find operations where a root privilege restriction doesn’t make sense, feel free to file a bug requesting that it be lifted. This is not without precedent. For example, in macOS 10.2 (yes, back in 2002!) we made it possible to implement ICMP (ping) without root privileges. And in macOS 10.14 we removed the restriction on binding to low-number ports (r. 17427890). Nice! Decide on One-Shot vs Ongoing Privileges To start, decide whether you want one-shot or ongoing privileges. For one-shot privileges, the user authorises the operation, you perform it, and that’s that. For example, if you’re creating an un-installer for your product, one-shot privileges make sense because, once it’s done, your code is no longer present on the user’s system. In contrast, for ongoing privileges the user authorises the installation of a launchd daemon. This code always runs as root and thus can perform privileged operations at any time. Folks often ask for one-shot privileges but really need ongoing privileges. A classic example of this is a custom installer. In many cases installation isn’t a one-shot operation. Rather, the installer includes a software update mechanism that needs ongoing privileges. If that’s the case, there’s no point dealing with one-shot privileges at all. Just get ongoing privileges and treat your initial operation as a special case within that. Keep in mind that you can convert one-shot privileges to ongoing privileges by installing a launchd daemon. Just Because You Can, Doesn’t Mean You Should Ongoing privileges represent an obvious security risk. Your daemon can perform an operation, but how does it know whether it should perform that operation? There are two common ways to authorise operations: Authorise the user Authorise the client To authorise the user, use Authorization Services. For a specific example of this, look at the EvenBetterAuthorizationSample sample code. Note This sample hasn’t been updated in a while (sorry!) and it’s ironic that one of the things it demonstrates, opening a low-number port, no longer requires root privileges. However, the core concepts demonstrated by the sample are still valid. The packet trace example from above is a situation where authorising the user with Authorization Services makes perfect sense. By default you might want your privileged helper tool to allow any user to run a packet trace. However, your code might be running on a Mac in a managed environment, where the site admin wants to restrict this to just admin users, or just a specific group of users. A custom authorisation right gives the site admin the flexibility to configure authorisation exactly as they want. Authorising the client is a relatively new idea. It assumes that some process is using XPC to request that the daemon perform a privileged operation. In that case, the daemon can use XPC facilities to ensure that only certain processes can make such a request. Doing this securely is a challenge. For specific API advice, see this post. WARNING This authorisation is based on the code signature of the process’s main executable. If the process loads plug-ins [1], the daemon can’t tell the difference between a request coming from the main executable and a request coming from a plug-in. [1] I’m talking in-process plug-ins here. Plug-ins that run in their own process, such as those managed by ExtensionKit, aren’t a concern. Choose an Approach There are (at least) seven different ways to run with root privileges on macOS: A setuid-root executable The sudo command-line tool The authopen command-line tool AppleScript’s do shell script command, passing true to the administrator privileges parameter The osascript command-line tool to run an AppleScript The AuthorizationExecuteWithPrivileges routine, deprecated since macOS 10.7 The SMJobSubmit routine targeting the kSMDomainSystemLaunchd domain, deprecated since macOS 10.10 The SMJobBless routine, deprecated since macOS 13 An installer package (.pkg) The SMAppService class, a much-needed enhancement to the Service Management framework introduced in macOS 13 Note There’s one additional approach: The privileged file operation feature in NSWorkspace. I’ve not listed it here because it doesn’t let you run arbitrary code with root privileges. It does, however, have one critical benefit: It’s supported in sandboxed apps. See this post for a bunch of hints and tips. To choose between them: Do not use a setuid-root executable. Ever. It’s that simple! Doing that is creating a security vulnerability looking for an attacker to exploit it. If you’re working interactively on the command line, use sudo, authopen, and osascript as you see fit. IMPORTANT These are not appropriate to use as API. Specifically, while it may be possible to invoke sudo programmatically under some circumstances, by the time you’re done you’ll have code that’s way more complicated than the alternatives. If you’re building an ad hoc solution to distribute to a limited audience, and you need one-shot privileges, use either AuthorizationExecuteWithPrivileges or AppleScript. While AuthorizationExecuteWithPrivileges still works, it’s been deprecated for many years. Do not use it in a widely distributed product. The AppleScript approach works great from AppleScript, but you can also use it from a shell script, using osascript, and from native code, using NSAppleScript. See the code snippet later in this post. If you need one-shot privileges in a widely distributed product, consider using SMJobSubmit. While this is officially deprecated, it’s used by the very popular Sparkle update framework, and thus it’s unlikely to break without warning. If you only need escalated privileges to install your product, consider using an installer package. That’s by far the easiest solution to this problem. Keep in mind that an installer package can install a launchd daemon and thereby gain ongoing privileges. If you need ongoing privileges but don’t want to ship an installer package, use SMAppService. If you need to deploy to older systems, use SMJobBless. For instructions on using SMAppService, see Updating helper executables from earlier versions of macOS. For a comprehensive example of how to use SMJobBless, see the EvenBetterAuthorizationSample sample code. For the simplest possible example, see the SMJobBless sample code. That has a Python script to help you debug your setup. Unfortunately this hasn’t been updated in a while; see this thread for more. Hints and Tips I’m sure I’ll think of more of these as time goes by but, for the moment, let’s start with the big one… Do not run GUI code as root. In some cases you can make this work but it’s not supported. Moreover, it’s not safe. The GUI frameworks are huge, and thus have a huge attack surface. If you run GUI code as root, you are opening yourself up to security vulnerabilities. Appendix: Running an AppleScript from Native Code Below is an example of running a shell script with elevated privileges using NSAppleScript. WARNING This is not meant to be the final word in privilege escalation. Before using this, work through the steps above to see if it’s the right option for you. Hint It probably isn’t! let url: URL = … file URL for the script to execute … let script = NSAppleScript(source: """ on open (filePath) if class of filePath is not text then error "Expected a single file path argument." end if set shellScript to "exec " & quoted form of filePath do shell script shellScript with administrator privileges end open """)! // Create the Apple event. let event = NSAppleEventDescriptor( eventClass: AEEventClass(kCoreEventClass), eventID: AEEventID(kAEOpenDocuments), targetDescriptor: nil, returnID: AEReturnID(kAutoGenerateReturnID), transactionID: AETransactionID(kAnyTransactionID) ) // Set up the direct object parameter to be a single string holding the // path to our script. let parameters = NSAppleEventDescriptor(string: url.path) event.setDescriptor(parameters, forKeyword: AEKeyword(keyDirectObject)) // The `as NSAppleEventDescriptor?` is required due to a bug in the // nullability annotation on this method’s result (r. 38702068). var error: NSDictionary? = nil guard let result = script.executeAppleEvent(event, error: &error) as NSAppleEventDescriptor? else { let code = (error?[NSAppleScript.errorNumber] as? Int) ?? 1 let message = (error?[NSAppleScript.errorMessage] as? String) ?? "-" throw NSError(domain: "ShellScript", code: code, userInfo: nil) } let scriptResult = result.stringValue ?? "" Revision History 2025-03-24 Added info about authopen and osascript. 2024-11-15 Added info about SMJobSubmit. Made other minor editorial changes. 2024-07-29 Added a reference to the NSWorkspace privileged file operation feature. Made other minor editorial changes. 2022-06-22 First posted.

Hi all, I am having a mysterious problem trying to load a user LaunchAgent under Big Sur - It is the .plist of gniemetz's automount.sh  https://github.com/gniemetz/automount for mounting SMB shares via pwd access from the Keychain - Placed the .sh into /usr/local/bin, chmod 644 and chown user:staff Placed the LaunchAgent .plist into ~/Library/LaunchAgents (created LaunchAgents it as it didn't exist), same chmod/chown. drwxr-xr-x		3	 users		 96 Nov	1 22:13 LaunchAgents ~/Library/LaunchAgentsrw-r--r--		1	 users	 1038 Nov	1 22:13 it.niemetz.automount.plist /usr/local drwxr-xr-x		4 root		wheel		128 Nov	1 21:52 bin /usr/local/binrwxr-xr-x		1 root		wheel	30310 Oct 29 21:58 automount.sh then the following: Load failed: 5: Input/output error For the life of me, I cannot find anywhere what this means... launchctl start ~/Library/LaunchAgents/it.niemetz.automount.plist completes with no errors, syntax also parses OK /Users//Library/LaunchAgents/it.niemetz.automount.plist: OK I have added Terminal and /bin/bash to Full Disk Access under Security... Launching the script manually as /usr/local/bin/automount.sh works fine. Console shows system.log shows this when load -w is run: 00:27:14 mac-mini-Big-Sur com.apple.xpc.launchd[1] (com.apple.xpc.launchd.user.domain.1000002.100006.Aqua): entering bootstrap mode Nov	3 00:27:14 mac-mini-Big-Sur com.apple.xpc.launchd[1] (com.apple.xpc.launchd.user.domain.1000002.100006.Aqua): exiting bootstrap mode For easy reference the .plist is pasted at the end - Anyone seen this error before? Thanks! ++ Label it.niemetz.automount LimitLoadToSessionType Aqua RunAtLoad WatchPaths /etc/resolv.conf /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist /Library/Preferences/SystemConfiguration/com.apple.airport.preferences.plist ProgramArguments /usr/local/bin/automount.sh --mountall