--- title: "macOS headless client" slug: "macos-headless-client-v7-0" description: "Headless clients enable secure, unattended connections to AppGate ZTNA on Windows, macOS, and Linux, ensuring efficient resource access and management." tags: ["Client Management", "macOS Headless Client", "macOS Client"] updated: 2026-11-03T21:04:35Z published: 2026-11-03T21:04:35Z canonical: "support.appgate.com/macos-headless-client-v7-0" --- > ## 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 Headless clients run in the background without a UI. They let unattended systems such as servers or container instances connect to AppGate ZTNA. Standalone headless clients are available for Windows, macOS, and Linux. AppGate also embeds headless clients in the Windows SSO client, always-on clients, Kubernetes Injector, and Connector. After you apply a profile and credentials, the client immediately tries to sign in to the Controllers at boot and continues to retry. > [!NOTE] > NOTE > > Always assign a valid policy to headless clients—without one, the retries can create a DoS condition on the Controllers and fill disk space with log warning messages. After sign-in, the headless client receives its own entitlements based on its policy, granting access to permitted resources protected by AppGate ZTNA. It automatically establishes secure connections with Gateways. If the headless client is installed on a remote server, the entitlements may include down rules so AppGate ZTNA users can access it. The headless client does not support auto-update. Update using the `.dmg` file in the usual way, then run the headless installation step again. > [!NOTE] > NOTE > > To use the macOS client, turn off ***Limit IP address tracking*** on your device. If this setting is enabled, the client ignores DNS settings. You can disable it manually or through an Apple MDM profile. To disable it manually: > > 1. On your macOS device, go 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**. --- ## System limitations The macOS headless client has the following limitations: - You must onboard a device from the headless client for a user on a specific computer. If the device is already registered using the full client, the headless client fails. - Multifactor authentication (MFA) at sign-in is not supported on the headless client. - Custom scripted device claims are not supported on the headless client. --- ## Installing the macOS headless client Install the macOS headless client using the same `.dmg` as for the full client. ### Downloading the installer from the command line To manually install **the latest version** of the client, run: ```bash curl -L -o "/tmp/AppGate-SDP-client.dmg" "https://bin.appgate-sdp.com/latest/macos/AppGate-SDP-client.dmg" ``` To install a specific version, run the following command and replace `x.y.z` and `x.y`with the correct version numbers: ```bash curl -L -o "/tmp/AppGate-SDP-client.dmg" "https://bin.appgate-sdp.com/x.y/client/Appgate-SDP-x.y.z-Installer.dmg" ``` To manually install the client, run the following command and replace `x.y.z` and `x.y` with the correct version numbers: ```bash curl -L -o "/tmp/AppGate-SDP-client.dmg" "https://bin.appgate-sdp.com/x.y/client/Appgate-SDP-x.y.z-Installer.dmg" ``` ### Installing the client from the command line To install the client remotely, run the following and replace `x.y.z` with the correct version number: ```bash hdiutil attach "/tmp/AppGate-SDP-x.y.z-Installer.dmg" -mountpoint /tmp/appgate sudo installer -pkg /tmp/appgate/Appgate\ SDP\ Installer.pkg -target "/" hdiutil detach /tmp/appgate ``` This creates a folder at `/Library/Application Support/Appgate`. It contains several files, including the `headless-installer` script. Run the script as root: ```bash sudo ./headless-installer ``` This sets up and runs the headless LaunchDaemon and enables auto-start for the headless client service. The installer can optionally inject the credentials the client needs to connect to the Controller. If you specify them, the installer stores the username, password, and profile link in the Keychain. If you skip this step initially, run the `headless-installer` again to add credentials later. The headless installer accepts the following options: | Option | Description | | --- | --- | | `--username` | Sets the username for sign-in with credentials. | | `--password` | Sets the password for sign-in with credentials. | | `--profilelink` | Specifies the client profile link. Can be copied from **Client Profiles** (Identity > Client Profiles). | > [!NOTE] > NOTE > > All three options must be included at the same time. For example: ```bash sudo /Library/Application\ Support/Appgate/headless-installer \  --username \  --password \  --profilelink "" ``` --- ## How to set or change the configuration If the three Keychain options above are present, the headless client uses them—whether added by hand or using the installer. A fallback exists for when they are not present: the `appgate.conf` file in the `/etc` folder. Test the setup with the `appgate.conf` file before using 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-11-21T21%3A39%3A52Z&se=2026-11-21T22%3A39%3A52Z&sr=b&sp=r&sig=ATBGPC30wkoQz0kN%2F%2Bln6wk0abHIXsvg0m19pica9f0%3D) To add credentials, edit the file `sudo nano /etc/appgate.conf` After editing, reload the configuration using the [Service Configurator](/v1/docs/macos-headless-client-v7-0#using-the-service-configurator-tool1) tool. Uncomment the required items and add your configuration, for example, `Password = my-password`. The `appgate.conf` file accepts the following settings: | Setting | Description | | --- | --- | | `LogLevel` | Specify log level (default: Info). Options: Dump, Trace, Debug, Info, Warn, Error, Fatal. | | `Username` | Sets the username for sign-in with credentials. | | `Password` | Sets the password for sign-in with credentials. | | `ProfileLink` | Specifies the client profile link. Can be copied from **Client Profiles** (Identity > Client Profiles). | | `AuthenticationCertificatePath` | Sets the path to the certificate for certificate authentication. | | `AuthenticationCertificatePassword` | Sets the password for the authentication certificate. | | `AuthenticationCertificateSubjectName` | Fetches the certificate with that subject name from the system Keychain. | See [LDAP Certificate IdP](/v1/docs/ldap-certificate-provider-v7-0) if using certificate authentication. Save the certificate in the file system, in `/var/lib/appgate/`, which has the correct permissions. To protect a certificate with a password, store the password in the Keychain: ```bash 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** > > You must include the `-T` option. Without it, any application can access the stored password. --- ## Using the client To prevent the full client from auto-starting at boot, run: ```bash defaults write com.appgate.sdp.service autostart 0 ``` To start and stop the headless client manually: ```bash sudo launchctl load /Library/LaunchDaemons/com.appgate.sdp.headless.plist sudo launchctl unload /Library/LaunchDaemons/com.appgate.sdp.headless.plist ``` To get the current status or configuration, use the `appgate_service_configurator` in `/Library/Application Support/AppGate`. ### Using the Service Configurator tool The `appgate_service_configurator` tool is in `/Library/Application Support/Appgate`. Enter: ```bash sudo /Library/Application Support/Appgate/appgate_service_configurator OPTION ``` The Configurator tool accepts the following options: | Option | Action | | --- | --- | | `getconfig` | Displays the current configuration. | | `reload` | Signs out and reconnects automatically. Useful for testing a new configuration. | | `status` | Gets the status of the running service. | The `status` option returns one of the following messages: | 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. | | `Connecting` | Client has successfully signed in and is connecting. | | `Connected` | Client is signed in and connected. Details of the entitlements, Gateways, and Sites are included. | | `Partially Connected` | Client is 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 cannot connect to any Site. | | `Disconnecting` | Client is disconnecting and will soon try to sign in again. | --- ## Uninstalling the macOS headless client See [Uninstalling macOS clients](/v1/docs/macos-clients-v7-0#uninstalling-macos-clients). --- ## Logs Headless client logs are in `/var/log/appgate-headless`. To watch live headless logs, run: ```bash tail -f /var/log/appgate-headless ```