# Windows Headless Mode

### Headless mode requires a Service Key

See the [Services](/content/docs/services/index.html) 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](/content/docs/windows-headless#working-with-the-windows-client-in-headless-mode/index.html)

#### [Installation & configuration](/content/docs/windows-headless#installation--configuration/index.html)

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 EXE installer can be downloaded from our [public changelog](/content/changelog/clients/index.html).

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) **`/quiet`**: Silent installation switch. Useful for automated deployment.

Some examples are shown below.

```powershell
# Silently install the client in headless mode
TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json /quiet

# (Optional) Set the log level at installation time
# Note: log_level=info is the default log level
TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json log_level=debug /quiet
```

Additional optional configuration options, including the log level setting, are available at the following path:

```text
C:\Program Files\Twingate\headless.conf
```

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](/content/docs/windows-headless#starting--stopping-the-client/index.html)

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](/content/docs/windows-headless#troubleshooting/index.html)

While running in headless mode, Client logs are output to the following path:

```text
C:\ProgramData\Twingate\logs
```

## [Key rotation and Upgrades](/content/docs/windows-headless#key-rotation-and-upgrades/index.html)

#### [Updating the Service Key](/content/docs/windows-headless#updating-the-service-key/index.html)

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:

```powershell
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:

```powershell
TwingateWindowsInstaller.exe service_secret=C:\path\to\service_key.json
```

For all of the above options, you **must restart the service for changes to take effect**.

If you have previously installed the Client without a Service Key, you must perform a fresh installation with the `service_secret` switch pointing to a valid Service Key. You cannot simply run the `sc` command to update the Service Key in this case.

#### [Deleting the Service Key](/content/docs/windows-headless#deleting-the-service-key/index.html)

The stored Service Key may be deleted by running the following with Administrator permissions:

```powershell
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](/content/docs/windows-headless#upgrading-the-client/index.html)

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

Last updated 2 days ago