Setup LaunchAgent in Xcode

Do we have somewhere a documentation about how to setup a LaunchAgent in Xcode

No. The documentation for this stuff is sadly lacking )-:

I create the plist of the agent on side and run it manually, I could do this in a more automatic way

Yes. Use SMAppService for this.

How could I package a macOS applciation that will contains the agent, install it and load the agent?

Yes. SMAppService supports this specifically.

For a specific example of how to set this up, see this post.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Again thanks @eskimo , for your answers :)

Before diving into SMAppService, I try to load the agent manually and start a macOS app that will connect with the Agent. (I'd like to use a minimalist setup at first and add layers as much as I face limitations, this is the way I'd like to discover new topics :) )

I faced several issues:

• Sandbox: NetworkMonitorApp(2330) deny(1) mach-lookup com.tonygo.NetworkMonitorAgent from the agent log, then I add com.apple.security.temporary-exception.mach-lookup.global-name (I Imagine that SMAppService will remove this) - The message dissapeard.
• I still have a The connection to service named com.tonygo.NetworkMonitorAgent was invalidated from this process. from th macOS app.

Note: I also authorize Server and Client connextion from sandbox or even remove the sandbox, but it did not change...

Either it is not possible at all to do this kind of unsafe XPC connection, or I miss something :)

I Imagine that SMAppService will remove this

It will not.

If you plan to ship with sandboxing enabled, add an app group to your app and your agent and then make the XPC service name an immediate child of the app group name. For example, if your app group is com.example.waffle-varnish.group then your XPC service name might be com.example.waffle-varnish.group.xpc. Remember that, for sandboxed programs, the app group must be authorised by an entitlement. See App Groups: macOS vs iOS: Fight!.

For the moment, however, I recommend that you disable the App Sandbox. As you said, it’s best to start with the “minimalist setup at first”.

As to your invalidation problem, that’s likely because the service name isn’t being registered properly. What does your agent’s property list look like? And how are you loading it?

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

As to your invalidation problem, that’s likely because the service name isn’t being registered properly. What does your agent’s property list look like? And how are you loading it?

The code is:

import Foundation
import OSLog

class NetworkMonitorXPCService: NSObject, NetworkMonitorXPCProtocol, NSXPCListenerDelegate {
    func getNetworkStatus(reply: @escaping (Bool) -> Void) {
        // Implement your logic to determine the network status
        let networkStatus: Bool = true
        reply(networkStatus)
    }
    
    /// This method is where the NSXPCListener configures, accepts, and resumes a new incoming NSXPCConnection.
    func listener(_ listener: NSXPCListener, shouldAcceptNewConnection newConnection: NSXPCConnection) -> Bool {
        Logger.agent.debug("In listener")
        
        // Configure the connection.
        // First, set the interface that the exported object implements.
        newConnection.exportedInterface = NSXPCInterface(with: NetworkMonitorXPCProtocol.self)
        
        Logger.agent.debug("After Exported Interface")
        
        // Next, set the object that the connection exports. All messages sent on the connection to this service will be sent to the exported object to handle. The connection retains the exported object.
        newConnection.exportedObject = self
        
        Logger.agent.debug("After Exported Object")
        
        // Resuming the connection allows the system to deliver more incoming messages.
        newConnection.resume()
        
        Logger.agent.debug("After Exported Resume")
        
        // Returning true from this method tells the system that you have accepted this connection. If you want to reject the connection for some reason, call invalidate() on the connection and return false.
        return true
    }
}

Logger.agent.info("Start agent")

let delegate = NetworkMonitorXPCService()
let listener = NSXPCListener.init(machServiceName: MACH_SERVICE_NAME) // declared as: let MACH_SERVICE_NAME = "com.tonygo.NetworkMonitorAgent"
listener.delegate = delegate
listener.resume()

Logger.agent.info("Agent started")

RunLoop.main.run()

I have this .plist file:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.tonygo.NetworkMonitorAgent</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/tonygorez/Desktop/Builds/Release/NetworkMonitor</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>MachServices</key>
	<dict>
		<key>com.tonygo.NetworkMonitorAgent</key>
		<true/>
	</dict>
</dict>
</plist>

For the loading I just run:

launchctl load ~/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent.plist

➜  ~ launchctl list | grep tonygo

11588	0	com.tonygo.NetworkMonitorAgent

I also take a look at the console. (see joined screen)

For the loading I just run:

You’re doing that from Terminal app, logged in to the same GUI login context as the client app, right?

I also take a look at the console.

Do you see any additional log messages in the system log when you run your app and try to connect?

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

You’re doing that from Terminal app, logged in to the same GUI login context as the client app, right?

Yeah.

Do you see any additional log messages in the system log when you run your app and try to connect?

No, but I observe another thing, once the macOS is up, I see two launchd agents in the console.

➜  ~ launchctl list | grep tonygo

22718	0	application.com.tonygo.NetworkMonitorApp.138426740.138426852.1D8FCF73-1582-44D3-AA62-4888F3AC0D07
22433	0	com.tonygo.NetworkMonitorAgent

But this probably the app itself as, the build identifier is different and even if I comment the whole NSXPCConnection logic and re-run (after a clean build) again, I see the Xcode agent. So this is probably not related.

Maybe should I publish the code somewhere?

I spotted it; this is probably the moment you throw virtual tomatoes at me, haha.

This seems to come from how I instantiate the Client class:

The code that does not work:

struct ContentView: View {
    @State private var networkStatus: String = "Off"
    
    var body: some View {
        Text("Network status: \(networkStatus)")
            .onAppear {
                NetworkMonitorXPCClient().getNetworkStatus { status in
                    DispatchQueue.main.async {
                        self.networkStatus = status ? "Online" : "Offline"
                    }
                }
            }
    }
}

The code that works:

struct ContentView: View {
    @State private var networkStatus: String = "Off"
    
    private var xpc = NetworkMonitorXPCClient()
    
    var body: some View {
        Text("Network status: \(networkStatus)")
            .onAppear {
                xpc.getNetworkStatus { status in
                    DispatchQueue.main.async {
                        self.networkStatus = status ? "Online" : "Offline"
                    }
                }
            }
    }
}

This maybe due to how the onAppear code is executed?

Hey 👋

The next to me is to enable the App Sandbox again and use App groups.

So I did the following:

• Create an app group on Xcode

• Change the entitlements of each target

• Change the MACH_SERVICE_NAME var (used to establish connection)

let MACH_SERVICE_NAME = "W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc"

• Change the name of launchd agent in the .plist and change the name of the file

➜  LaunchAgents launchctl list | grep tonygo\

49603	0	W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc

I see logs of the loaded agent, But I still have the lookup error...

Did I miss something @eskimo ?

Note: I used "$(TeamIdentifierPrefix)com.tonygo.NetworkMonitorApp.xpc" and not "$(TeamIdentifierPrefix).com.tonygo.NetworkMonitorApp.xpc"

This seems to come from how I instantiate the Client class:

Probably. Both of your examples seem kinda wonky to me. I’d expect NetworkMonitorXPCClient to be a long-lived thing, and thus you shouldn’t instantiate on appear (your first example) or every time the view is created (your second). Rather, I’d expect it to either be part of your model or set up to persist across multiple creations of your view (using @State or the older @StateObject).

Create an app group on Xcode

You have double dots in that screen shot, that is, this:

W4MF6H9XZ6..com.tonygo.NetworkMonitorApp

when I’d expect this:

W4MF6H9XZ6.com.tonygo.NetworkMonitorApp

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Probably. Both of your examples seem kinda wonky to me.

Yeah this is garbage code anyway. I'll prolly use a singleton or instantiate it in the App stuct.

You have double dots in that screen shot, that is, this:

I already fixed this :) But it did not fixed it.

I put the code into this repo: https://github.com/tony-go/NetworkMonitor

The only missing part is the ~/Library/LaunchAgents/W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc.plist file:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc</string>
    <key>ProgramArguments</key>
    <array>
      <string>/Users/tonygorez/Desktop/Builds/Release/NetworkMonitor</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
    <key>MachServices</key>
        <dict>
                <key>com.tonygo.NetworkMonitorAgent</key>
                <true/>
        </dict>
</dict>
</plist>

    <key>Label</key>
    <string>W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc</string>

It’s unusual to prefix your job label with your Team ID.

    <key>MachServices</key>
    <dict>
        <key>com.tonygo.NetworkMonitorAgent</key>
        <true/>
    </dict>

In contrast, if your app is sandboxed, as is the case with the example you linked to, this must be prefixed by an app group.

Looking at the code snippet you posted, you have this:

let MACH_SERVICE_NAME = "W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc"

This confirms that you have your launchd property list set up backwards. You’re using this as the name of your named XPC endpoint, which means it must match MachService property, not the Label.

For context, a launchd job’s label is how launchd tracks the job. In contrast, the MachServices property lists all of the names that get registered in the Mach bootstrap service. If you’re using XPC [1] this value matches the name of your named XPC endpoint.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] Rather than raw Mach messaging, which is something I recommend that you avoid.

In contrast, if your app is sandboxed, as is the case with the example you linked to, this must be prefixed by an app group.

This is not really clear to me how it should look like, AFAIU the app group is W4MF6H9XZ6.com.tonygo.NetworkMonitorApp, then if I had to prefix it, it could be: W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.com.tonygo.NetworkMonitorAgent that seems way to strange tho.

Also I'm not sure about where the .xpc suffix should stand. It looks like it means the XPC endpoint for this particular app group... Not sure.

--

I try these combinations:

let MACH_SERVICE_NAME = "W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc

and

   <key>MachServices</key>
	<dict>
		<key>W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc</key>
		<true/>
	</dict>

let MACH_SERVICE_NAME = "W4MF6H9XZ6.com.tonygo.NetworkMonitorApp

and

   <key>MachServices</key>
	<dict>
		<key>W4MF6H9XZ6.com.tonygo.NetworkMonitorApp</key>
		<true/>
	</dict>

let MACH_SERVICE_NAME = "W4MF6H9XZ6.com.tonygo.NetworkMonitorApp

and

   <key>MachServices</key>
	<dict>
		<key>W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.xpc</key>
		<true/>
	</dict>

The Label property identifies your job to launchd. It’s traditionally a reverse DNS name that’s unique to your product.

The MachServices property lists the named XPC endpoints provided by your job. It usually has a single. The value is typically another reverse DNS name. It does not have to match the Label property, but sometimes it does.

If the client is sandboxed then there is a very specific constraints on the XPC endpoint name: It must be an immediate child of an app group of which the client is a member. For sandboxed apps, you must indicate membership using an unrestricted entitlement. See App Groups: macOS vs iOS: Fight!

That doc also explains that, on the Mac, app groups traditionally start with your Team ID.

Putting this all together:

• com.tonygo.NetworkMonitorApp would be fine for Label.

• You’ll want an app group like W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.group.

• And an XPC endpoint name like W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.group.xpc.

Note that there’s nothing special about the .group suffix. What matters is that the group starts with your Team ID and doesn’t collide with anything also.

There’s also nothing special about the .xpc suffix. What matters is that the XPC endpoint name be an immediate child of the app group.

So, in my test project for this stuff I have:

• Label set to com.example.apple-samplecode.SandboxedAgent.agent.

• An app group of SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent.group.

• An XPC endpoint name of SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent.group.agent.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hi @eskimo 👋

Sorry for the late reply. I was for the last few days. Thanks for your answer.

It worked :) Now I'd like to get rid of the manual launchctl load haha. Then I start exploring SMAppService.

Here is the code: https://github.com/tony-go/NetworkMonitor/tree/sma-app-service/

When I try to register the agent I had this error:

2024-02-09 19:28:18.503557+0100 NetworkMonitorApp[83508:3975925] [all] Unable to read plist at: /Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/Contents/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent

Unable to register Error Domain=SMAppServiceErrorDomain Code=108 "Unable to read plist: com.tonygo.NetworkMonitorAgent" UserInfo={NSLocalizedFailureReason=Unable to read plist: com.tonygo.NetworkMonitorAgent}

So I checked that the file is present in the app bundle (I added a copy script for this):

➜  ~ tree /Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/        
/Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/
└── Contents
    ├── Info.plist
    ├── Library
    │   └── LaunchAgents
    │       └── com.tonygo.NetworkMonitorAgent.plist
    ├── MacOS
    │   └── NetworkMonitorApp
    ├── PkgInfo
    ├── Resources
    │   └── NetworkMonitor
    └── _CodeSignature
        └── CodeResources

I also check file permissions:

➜  ~ ls -la /Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/Contents/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent.plist
-rw-r--r--  1 tonygorez  staff  513 Feb  9 19:14 /Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/Contents/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent.plist

The plist format too:

➜  ~ plutil -lint /Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/Contents/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent.plist
/Users/tonygorez/Library/Developer/Xcode/DerivedData/NetworkMonitor-ebjjqrpyyilqingmpoykggtnpdjb/Build/Products/Debug/NetworkMonitorApp.app/Contents/Library/LaunchAgents/com.tonygo.NetworkMonitorAgent.plist: OK

And finaly the com.apple.security.files.user-selected.read-only entitlements: https://github.com/tony-go/NetworkMonitor/blob/sma-app-service/NetworkMonitorApp/NetworkMonitorApp.entitlements#L11-L12

I run out of ideas haha :)

I took my inspiration from this: https://developer.apple.com/documentation/servicemanagement/updating-your-app-package-installer-to-use-the-new-service-management-api

I hope you a new track haha 😅

Have a good evening

Cheers

Don’t put code, in this case the NetworkMonitor executable, in Contents/Resources. See Placing Content in a Bundle for info on where it should be.

Don’t forget to adjust com.tonygo.NetworkMonitorAgent.plist to account for this change.

When you call SMAppService.agent(plistName:), include the .plist extension.

Do you actually want to sandbox this app? If so, let me know because that involves further work.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Hey @eskimo, ssup?

Don’t put code, in this case the NetworkMonitor executable, in Contents/Resources. See Placing Content in a Bundle for info on where it should be.

"privileged helper tool - macOS - Contents/Library/LaunchServices/" seems to be appropriate ?

Do you actually want to sandbox this app? If so, let me know because that involves further work.

yeah that is the whole, package a full-blown macOS application with a LaunchAgent (with notarization)

Contents/Library/LaunchServices/ seems to be appropriate ?

No. You want Contents/MacOS or Contents/Helpers. The Contents/Library/LaunchServices/ is meant for tools installed with SMJobBless.

yeah that is the whole, package a full-blown macOS application with a LaunchAgent (with notarization)

Notarising implies that you’re distributing the app directly, which means not on the Mac App Store. That means that sandboxing is optional. There are good reasons to sandbox your product, but be aware that it makes this particular task harder.

Specifically, if you sandbox your app then you need to sandbox your launchd agent. That means that you need to sign your agent with entitlements:

• com.apple.security.app-sandbox to enable the sandbox.

• com.apple.security.application-groups to facility XPC.

Specifically, to use XPC in a sandboxed process the XPC endpoint name must be an immediate child of one of your app group IDs. So, going back to my earlier example:

• The app group ID was SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent.group.

• The XPC endpoint name was SKMME9E2Y8.com.example.apple-samplecode.SandboxedAgent.group.agent.

You also need to give your agent an Info.plist. If you continue to use an executable as your agent (rather than putting it in its own bundle) set this up with the Info.plist File and Create Info.plist Section in Binary build settings.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Notarising implies that you’re distributing the app directly, which means not on the Mac App Store.

You mean that the app on store are not natorized?

Thanks for all these details @eskimo :)

Specifically, if you sandbox your app then you need to sandbox your launchd agent. That means that you need to sign your agent with entitlements: com.apple.security.app-sandbox to enable the sandbox. com.apple.security.application-groups to facility XPC.

These should be present in the entitlements file right?

Specifically, to use XPC in a sandboxed process the XPC endpoint name must be an immediate child of one of your app group IDs. So, going back to my earlier example:

Seems good on my side.

You also need to give your agent an Info.plist. If you continue to use an executable as your agent (rather than putting it in its own bundle) set this up with the Info.plist File and Create Info.plist Section in Binary build settings.

Do we need a Info.plist event with an executbale? When should I put it? "In Contents/MacOS too ?

Also, add .plist to the SMAppService call worked :) But the agent never started, here is the agent plist

You mean that the app on store are not natorized?

Not in the way that that term is usually used.

Note I’m talking about macOS here. We recently announced notarisation for iOS, which I’m not going to discuss on this thread.

On macOS:

• Code that’s distributed directly, using Developer ID signing, must be notarised in order to pass Gatekeeper.

• Apps distributed on the Mac App Store do not need to be notarised.

Notarisation performs a bunch of checks. Doing those checks separately is not required for an App Store app. The App Store performs (more or less) equivalent checks as part of its standard submission process.

These should be present in the entitlements file right?

Yes.

Do we need a Info.plist event with an executbale?

There are two cases:

• If your agent lives within a bundle structure [1], that bundle needs an Info.plist.

• If not — that is, your agent is a standalone execution — you must embed the contents of the Info.plist into your agent using the Create Info.plist Section in Binary build setting.

But the agent never started, here is the agent plist

Did it crash? Did that generate a crash report?

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] I’m not talking about the bundle structure of your app here, but rather a bundle for the agent that’s nested within your app’s main bundle.

Hey @eskimo :)

Thanks for this clarification about notarisation :)

Did it crash? Did that generate a crash report?

No at all. When I try to run the application I saw these logs:

Unable to register Error Domain=SMAppServiceErrorDomain Code=1 "Operation not permitted" UserInfo={NSLocalizedFailureReason=Operation not permitted}
Received XPC error: Error Domain=NSCocoaErrorDomain Code=4099 "The connection to service named W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.group.agent was invalidated: failed at lookup with error 3 - No such process." UserInfo={NSDebugDescription=The connection to service named W4MF6H9XZ6.com.tonygo.NetworkMonitorApp.group.agent was invalidated: failed at lookup with error 3 - No such process.}

That makes totaly sense as the agent never starts ... I checked with the Console application like I usually did, but I see no messages.

I put all my last changed on this branch: https://github.com/tony-go/NetworkMonitor/tree/sma-app-service

I’m not sure if there’s anything else going on, but there’s a mismatch between your app group entitlement (TTT.com.tonygo.NetworkMonitorApp) and your service name (TTT.com.tonygo.NetworkMonitorApp.group.agent). Remember that the service name must be an immediate child of the app group.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"