--- title: "macOS headless Client" slug: "macos-headless-client-v6-5" description: "Explore how headless Clients operate in the background, enabling secure connections and resource access without a UI on Windows, macOS, and Linux." updated: 2025-12-17T14:45:21Z published: 2025-12-17T14:45:21Z canonical: "support.appgate.com/macos-headless-client-v6-5" --- > ## 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 SDP 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 SDP 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 SDP 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. ## Background information There are some system limitations which need to be taken into account: - Device on-boarding has to be done from the Appgate SDP headless Client for a user on a specific computer. If this device is already registered (using the full Appgate SDP 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) 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-28T04%3A08%3A48Z&se=2026-10-28T05%3A08%3A48Z&sr=c&sp=r&sig=7W%2F9efaKb%2FlRGM5UAuHgNtqlbbed8tHNzyoqTQOjsqA%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. i.e. `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) 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) 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 SDP. | | 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` Appgate SDP (Software Defined Perimeter) is a security solution that provides secure access to resources based on user identity and context, leveraging a zero trust security model. A component that extends connectivity to remote sites and unmanaged resources without requiring the use of a standalone Client. The Controller is the central management appliance in the Appgate ZTNA system, responsible for user authentication, policy distribution, and overall system administration. A Policy is a set of rules that govern access control and permissions for users and devices within the Appgate ZTNA system. Policies determine what resources users can access based on their entitlements. Key-value pairs related to the identity and content of the user or device and are specific to each session.