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.

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 to info; available levels are documented in the headless.conf configuration file.
  • (Optional) /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

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

If you wish to update the service key being used, you may do one of the following:

  1. Modify the headless.conf file to specify the new key file location.
  2. Run the installation command with the service_secret switch with the new key file location.
  3. Update the key in its existing location.

For all of the above options, you must start and stop the service for changes to take effect.

Upgrading the Client

To upgrade the client, run the installation command again with the service_secret switch pointing to a valid Service Key.


What’s Next
Did this page help you?