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
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
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:
On your macOS device, go to Settings > Network.
Select your ethernet connection or Wi-Fi.
Select the Details… button.
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 client, run the following command and replace x.y.z and x.y with the correct version numbers:
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:
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/appgateThis creates a folder at /Library/Application Support/Appgate. It contains several files, including the headless-installer script. Run the script as root:
sudo ./headless-installerThis 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 |
|---|---|
| Sets the username for sign-in with credentials. |
| Sets the password for sign-in with credentials. |
| Specifies the client profile link. Can be copied from Client Profiles (Identity > Client Profiles). |
NOTE
All three options must be included at the same time.
For example:
sudo /Library/Application\ Support/Appgate/headless-installer \
--username <HEADLESS_USER> \
--password <PASSWORD> \
--profilelink "<full profile URL>"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.

To add credentials, edit the file sudo nano /etc/appgate.conf
After editing, reload the configuration using the Service Configurator tool. Uncomment the required items and add your configuration, for example, Password = my-password.
The appgate.conf file accepts the following settings:
Setting | Description |
|---|---|
| Specify log level (default: Info). Options: Dump, Trace, Debug, Info, Warn, Error, Fatal. |
| Sets the username for sign-in with credentials. |
| Sets the password for sign-in with credentials. |
| Specifies the client profile link. Can be copied from Client Profiles (Identity > Client Profiles). |
| Sets the path to the certificate for certificate authentication. |
| Sets the password for the authentication certificate. |
| Fetches the certificate with that subject name from the system Keychain. |
See LDAP Certificate IdP 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:
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.keychainNOTE
You must include the
-Toption. Without it, any application can access the stored password.
Using the client
To prevent the full client from auto-starting at boot, run:
defaults write com.appgate.sdp.service autostart 0To start and stop the headless client manually:
sudo launchctl load /Library/LaunchDaemons/com.appgate.sdp.headless.plist
sudo launchctl unload /Library/LaunchDaemons/com.appgate.sdp.headless.plistTo 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:
sudo /Library/Application Support/Appgate/appgate_service_configurator OPTIONThe Configurator tool accepts the following options:
Option | Action |
|---|---|
| Displays the current configuration. |
| Signs out and reconnects automatically. Useful for testing a new configuration. |
| Gets the status of the running service. |
The status option returns one of the following messages:
Status message | Description |
|---|---|
| Client is waiting to be configured |
| Client is applying the configuration and trying to sign in. |
| Client has successfully signed in and is connecting. |
| Client is signed in and connected. Details of the entitlements, Gateways, and Sites are included. |
| Client is signed in but can only connect to some Sites. |
| Client is suspended because the full client is in operation. |
| Client has successfully signed in but cannot connect to any Site. |
| Client is disconnecting and will soon try to sign in again. |
Uninstalling the macOS headless client
See Uninstalling macOS clients.
Logs
Headless client logs are in /var/log/appgate-headless.
To watch live headless logs, run:
tail -f /var/log/appgate-headless