--- title: "macOS headless client" slug: "macos-headless-client-v6-7" description: "Headless Clients enable secure, unattended connections to AppGate ZTNA, supporting Windows, macOS, and Linux while managing entitlements and configurations." updated: 2026-05-20T17:55:15Z published: 2026-05-20T17:55:15Z canonical: "support.appgate.com/macos-headless-client-v6-7" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # macOS headless client ## How does it work? Headless clients run without a UI in the background. They enable un-attended systems such as servers or container instances to connect to the AppGate ZTNA system. Stand alone headless clients are available for Windows, macOS and Linux; these are also embedded by AppGate into the Windows SSO client, always-on clients, Kubernetes Injector, and Connector. Once a profile and credentials have been applied to the headless client, on boot-up the client will immediately try to sign in to the Controller(s) (and continue to retry if it fails). For this reason it is strongly advised to always have a valid policy for headless clients, otherwise the retries will effectively become a DoS attack on the Controllers and consume large amounts of disk space with log warning messages. Once signed-in, the headless client will get its own entitlements (based on its policy) to access any permitted resources protected by AppGate ZTNA and will automatically (try to) establish secure connections with the Gateways. If the headless client has been installed on a remote server then the entitlements might include down rules so that users of the AppGate ZTNA system could access it. The headless client does not support auto-update. This can be updated using the dmg file in the usual way - then run the headless installation step again. > [!NOTE] > NOTE > > To use the macOS client, you must turn off *Limit IP address tracking* on your device. If this is not disabled, DNS settings will be ignored. You can disable the setting manually or through an Apple MDM profile. To manually disable this setting: > > 1. On your macOS device, navigate to Settings > Network. > 2. Select your ethernet connection or Wi-Fi. > 3. Select the **Details…** button. > 4. Disable *Limit IP address tracking* and select **OK**. ## Background information There are some system limitations which need to be taken into account: - Device on-boarding has to be done from the AppGate ZTNA headless client for a user on a specific computer. If this device is already registered (using the full AppGate ZTNA client) the headless client will fail. - MFA at sign-in is not supported on headless client. - Custom on-demand device claims are not supported on headless client. ### Installation Install using the same .dmg as for the full client. If you do not have access to the machine then to remotely install the client do: `hdiutil attach "$INSTALLER_FILE_NAME" -mountpoint $TMPMOUNTcd $TMPMOUNT/; installer -pkg Appgate\ SDP\ Installer.pkg -target "/"; cd /;hdiutil detach $TMPMOUNT` A folder `/Library/Application Support/Appgate` is created containing various files including the script headless-installer. Run this as root by doing `sudo ./headless-installer`. This will setup and run the headless LaunchDaemon, and will enable autostart for the headless client service. The installer can optionally be used to inject the required credentials the client needs to connect to the Controller. If these are specified then the three items: username, password and profile link will be stored in the Keychain. If you skip this option initially, you can run the headless-installer again to add these later. | OPTION | Description | | --- | --- | | --username | Set username to use for sign in with credentials. | | --password | Set password to use for sign in with credentials. | | --profilelink | Specify the client profile link to be used. Can be copied from the [Client Profiles](/v1/docs/configure-client-profiles-v6-7) UI. | > [!NOTE] > NOTE > > All three options must be included at the same time. ### How to set (or change) the configuration The headless client will always use the three options above if they are present in the Keychain (whether inserted by hand or using the installer). However there is a fall back mechanism for when they are not present; in this situation the appgate.conf file found in the folder /etc will be used. We recommend first testing the setup with the appgate.conf file before trying to use the Keychain. ![Configuration file for Appgate service with settings and credentials details listed.](https://cdn.us.document360.io/e7482ce5-acfa-4c3b-b76c-b6c32472644a/Images/Documentation/ag60-conf_file_mac.png?sv=2026-02-06&spr=https&st=2026-10-27T02%3A40%3A37Z&se=2026-10-27T03%3A40%3A37Z&sr=c&sp=r&sig=enJ2ThMu6BfXrWJyM6U9c1cbfCQq1aeh81nHBrxCk80%3D) To add credentials, you can edit this file and add the required settings here: `sudo nano /etc/appgate.conf` Once done you will need to reload the configuration using the service configurator tool (see below). #### Using appgate.conf Un-comment the required items and add your configuration, such as: `Password = my-password` | LogLevel | (Default: Info) Specify loglevel (Dump, Trace, Debug, Info, Warn, Error, Fatal) | | --- | --- | | Username | Set username to use for sign in with credentials' | | Password | Set password to use for sign in with credentials | | ProfileLink | Specify the client profile link to be used. Can be copied from the [Client Profiles](/v1/docs/configure-client-profiles-v6-7) UI. | | AuthenticationCertificatePath | Set the path to the certificate to be used in certificate authentication | | AuthenticationCertificatePassword | Set any password relating to the authentication certificate | | AuthenticationCertificateSubjectName | Fetch the certificate with that SubjectName from the system Keychain | Refer to [LDAP Certificate IdP](/v1/docs/ldap-certificate-identity-providers-v6-7) if using certificate authentication. The certificate should be saved in the file system - we suggest `/var/lib/appgate/` as this has the correct permissions. If you need to protect the certificate then a certificate password should be used - and this can be stored in the keychain using the following command: `sudo security add-internet-password -a AppgateCertificatePassword -s "appgate-headless" -j "Appgate SDP" -l "appgate-headless" -w [THE_PASSWORD] -T "/Library/Application Support/AppGate/AppGate Service.app/Contents/MacOS/AppGate Service" /Library/Keychains/System.keychain` > [!NOTE] > **NOTE** > > The -T option to the security command is very important, otherwise any application will be able to access the stored password. ### Using the client To prevent the full client auto-starting on boot do: defaults write com.appgate.sdp.service autostart 0 Normally the client will autostart however you can start and stop the headless client by doing: `sudo launchctl load /Library/LaunchDaemons/com.appgate.sdp.headless.plist` `sudo launchctl unload /Library/LaunchDaemons/com.appgate.sdp.headless.plist` You can get the current status and/or configuration of the headless client by using the `appgate_service_configurator` located in `/Library/Application Support/AppGate`. #### Using the Service Configurator tool In the folder `/Library/Application Support/Appgate` there is also the appgate_service_configurator tool. The configuration tool uses different options to provide specific functionality. Enter: `sudo /Library/Application Support/Appgate/appgate_service_configurator OPTION` | OPTION | Action | | --- | --- | | getconfig | Displays the current configuration of the client. | | reload | Will sign out the headless client if connected and reconnect automatically. Useful to try another configuration without having to restart the client service. | | status | Used to get the status of the running service. | | Status message | Description | | Waiting for configuration | Client is waiting to be configured | | Applying the new configuration | Client is applying the configuration and trying to sign in to AppGate ZTNA. | | Connecting | Client has successfully signed in and is connecting. | | Connected | Client has successfully signed in and is connected. Details of the entitlements, Gateways, and Sites are included. | | Partially Connected | Client has successfully signed in but can only connect to some sites. | | Suspended. Full client is currently connected (Always-on only) | Client is suspended because the full client is in operation. | | None connected | Client has successfully signed in but can't connect to any Site. | | Disconnecting | Client is disconnecting and will soon try to sign in again. | ### Logs Logs for the headless client are found in `/var/log/appgate-headless`