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_secret
switch 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
Twingate Service
.
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.
Client requires .NET Desktop Runtime
Since version 2023.206, the Windows client requires the .NET Desktop Runtime 6.0.0 (x64) or higher. The MSI installer does not include the .NET Desktop Runtime. When installing the client via the MSI, you must manually install .NET Desktop Runtime alongside the client if not already installed.
You can download the .NET Desktop Runtime directly from Microsoft.
The following command line options are available, which can also be set in the headless.conf
file (see below):
- (Required)
service_secret
: Supply a path to a valid Service Key file - (Optional)
log_level
: Set the log level. Defaults toinfo
; available levels are documented in theheadless.conf
configuration file. - (Optional)
/qn
: Silent installation switch. Useful for automated deployment.
Some examples are shown below.
# Silently install the client in headless modeTwingateWindowsInstaller.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 levelTwingateWindowsInstaller.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\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
The 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.
Troubleshooting
While running in headless mode, Client logs are output to the following path:
C:\ProgramData\Twingate\logs
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.servicesc 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:
TwingateWindowsInstaller.msi service_secret=C:\path\to\service_key.json
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.conf
file to specify the new key file location. - Run the installation command with the
service_secret
switch 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 7 months ago