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 ZTNAusers can access it.
The headless client does not support auto-update. Update it by reinstalling in the usual way.
System limitations
The Linux headless client has the following limitations:
You must onboard the device from the headless client for a user on a specific computer. If the device is already registered using the normal client, the headless client fails.
Multifactor authentication (MFA) at sign-in is not supported on the AppGate ZTNA headless client.
NOTE
Custom scripted device claims (formerly on-demand device claims) are not supported on headless clients.
Standard executables
The Linux headless client consists of four main components:
AppGate Service: The main client executable that runs in the background and handles all connections.
AppGate Driver: The virtual network adapter.
AppGate Configuration file: The settings file containing the parameters required to sign in.
AppGate Service Configurator: Controls the headless client. Requires the AppGate Service to be running.
Downloading the client
See the Downloads page, or use the following commands and replace x.y and x.y.z with the correct version numbers:
Ubuntu
curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp_x.y.z_amd64.deb"Ubuntu ARM
curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp_x.y.z_arm64.deb"Fedora
curl -L -o "/tmp/AppGate-SDP-client.rpm" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp-x.y.z-fc41.x86_64.rpm"RHEL
curl -L -o "/tmp/AppGate-SDP-client.deb" "https://bin.appgate-sdp.com/x.y/client/appgate-sdp-6.7.3-el9.x86_64.rpm"Installing the Linux headless client
NOTE
Remove any existing AppGate ZTNA installation before installing the headless client.
Use the command for your operating system and replace x.y.z with the correct version number:
Ubuntu
sudo apt install ./appgate-sdp-headless_x.y.z_amd64.debUbuntu ARM
sudo apt install ./appgate-sdp-headless_x.y.z_arm64.debFedora
sudo dnf install ./appgate-sdp-headless-x.y.z-fc41.x86_64.rpmRHEL
sudo rpm -i appgate-sdp-headless-x.y.z-el9.x86_64.rpmAfter installation, confirm that two services are running: appgatedriver.service and appgateservice.service.
Checking the installed version
To check the installed version, run:
dpkg -s appgate-headless | grep Version:Starting and stopping the headless service
To start the headless service:
sudo systemctl start appgate-headlessTo stop the headless service:
sudo systemctl stop appgate-headlessConfiguring the Linux headless client
To configure the Linux headless client, run the following and replace <HEADLESS_USER> and <PASSWORD> with IdP credentials, and <full profile URL> with the client profile link. For example:
sudo /opt/appgate/headless-installer \
--username <HEADLESS_USER> \
--password <PASSWORD> \
--profilelink "<full profile URL>"How to set or change the configuration
The configuration file appgate.conf in /etc is used to set up the headless client.

Open the configuration file with a suitable editor:
sudo gedit /etc/appgate.confThe file includes options for the following:
DNS: the option to specify a
dns_scriptif required.Log level and script timeout settings: default log level is
Info. Options are: Dump, Trace, Debug, Info, Warn, Error, Fatal.Credentials: uncomment the required lines and edit the values accordingly.
The configuration file accepts the following settings:
Setting | Description |
|---|---|
| Specifies the client profile link. Can be copied from Client Profiles (Identity > Client Profiles). |
| Sets the username for sign-in with credentials. |
| Sets the password for sign-in with credentials. |
| Path to an executable that the headless service runs to return the password. |
| Sets the path to the certificate for certificate authentication. |
| Sets the password for the authentication certificate. |
See LDAP Certificate IdP if using certificate authentication. To get the current status or configuration, use the appgate_service_configurator.
Service Configurator tool
The appgateservice.service must be running to use this tool. The tool is located in /usr/sbin.
Open a command prompt and enter:
sudo appgate_service_configurator -hThis lists available commands, as does --help. Then:
sudo appgate_service_configurator OPTIONThe Configurator tool accepts the following options:
Option | Action |
|---|---|
| Displays the current configuration of the client. |
| Signs out and reconnects automatically. Useful for testing a new configuration without restarting the client service. |
| 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 signed in and is connecting. |
| Client is signed in and connected. Details of entitlements, Gateways, and Sites are included. |
| Client is signed in but can only connect to some Sites. |
| Client is signed in but cannot connect to any Site. |
| Client is disconnecting and will soon try to sign in again. |
Uninstalling the Linux headless client
Use the following commands to uninstall the headless client binaries but keep all configuration settings:
Operating system | Install command |
|---|---|
Ubuntu |
|
Fedora |
|
RHEL9 |
|
To uninstall headless client binaries and all configuration settings, use the purge option in the above commands: remove --purge
For example: sudo apt remove --purge appgate-headless
Logs
View headless client daemon logs using:
journalctl -u appgateserviceTo watch live headless logs, run:
tail -f /var/log/appgate-headless