Windows Headless Mode
Minimum supported client version
Windows v1.0.11 or later is required for Service and headless mode support.
Headless mode requires a Service Key
See the Services documentation for information on how to create a Service account and Service Keys.
Twingate’s existing Windows client may also be used in headless mode.
- Headless mode is enabled by installing the Client from the command line using the
service_secretswitch with the path to a valid Service Key. The Service Key is obtained from the Service configuration in the Twingate Admin console.
- The Client is controlled from Windows Services by starting and stopping the
Working with the Windows Client in headless mode
Installation & configuration
The Windows Client is installed by running the installation from the command line and specifying the path to a Service Key. The latest Windows Client MSI installer can be downloaded from our public changelog.
The following command line options are available, which can also be set in the
headless.conf file (see below):
service_secret: Supply a path to a valid Service Key file
log_level: Set the log level. Defaults to
info; available levels are documented in the
/qn: Silent installation switch. Useful for automated deployment.
Some examples are shown below.
# Silently install the client in headless mode TwingateWindowsInstaller.msi service_secret=C:\path\to\service_key.json /qn # (Optional) Set the log level at installation time # Note: log_level=info is the default log level TwingateWindowsInstaller.msi service_secret=C:\path\to\service_key.json log_level=debug /qn
Additional optional configuration options, including the log level setting, are available at the following path:
C:\Program Files (x86)\Twingate\headless.conf
In Windows Client v1.0.26 and newer, the Service Key is securely stored and managed by the Client. There’s no need to keep the original Service Key file in its original location. However, a valid Service Key is required when updating or reinstalling the Client.
Starting & stopping the Client
Twingate Service service can be controlled directly from Windows Services. The Client will not start automatically by default, but the Windows service settings can be modified directly to set the desired behavior.
While running in headless mode, Client logs are output to the following path:
Key rotation and Upgrades
Updating the Service Key
Windows Client v1.0.26 and newer:
Since v1.0.26, there are two ways to update the Service Key. One option is to run the
sc command with Administrator permissions to stop the service and restart it with a new Service Key:
sc stop twingate.service sc start twingate.service --config --service-secret C:\path\to\service\secret.json
The other option is to re-run the installation command with the
service_secret switch pointing to the path of the new Service Key:
Windows Client v1.0.25 and older: In Windows Client v1.0.25 and older, you may do one of the following:
- Modify the
headless.conffile to specify the new key file location.
- Run the installation command with the
service_secretswitch with the new key file location.
- Update the key in its existing location.
For all of the above options, you must restart the service for changes to take effect.
Deleting the Service Key
In Windows Client v1.0.26 and newer, the stored Service Key may be deleted by running the following with Administrator permissions:
sc start twingate.service --config --reset
Deleting the Service Key will disconnect the Client from Twingate and require a new Service Key to be stored, either via the directions above or by running the installation command once more.
Upgrading the Client
To upgrade the client, run the installation command again with the
service_secret switch pointing to a valid Service Key.
Last updated 8 hours ago