Linux Headless Mode


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 Linux Client may be used in either interactive mode or headless mode.

  • Interactive mode is the default mode and is documented in our Linux Client documentation. The same platform support and installation instructions apply.
  • Headless mode is accessed by passing a --headless parameter to the twingate setup command with the path to a valid Service Key specified. The Service Key is obtained from the Service configuration in the Twingate Admin console.

Working with the Linux Client in headless mode


Running in headless mode within a Docker container

The Twingate Client needs access to certain capabilities on the host system in order to set up a network tunnel. You must add the following parameters to the Docker run command for the Client to operate correctly:

--device /dev/net/tun --cap-add NET_ADMIN

Installation & configuration

  1. The Linux Client is installed by following the existing installation process.
  2. Configure the Linux Client in headless mode by running the twingate setup command with the --headless parameter.

For example:

curl | sudo bash
sudo twingate setup --headless /path/to/service_key.json

Additional command line parameters, including the ability to set the default log level, are available. More information is available by running twingate help setup.

Starting & stopping the Client

# Start the client
sudo twingate start

# Check client status
twingate status

# Stop the client
sudo twingate stop


The Linux Client runs as a systemd service with logs retrievable via journalctl.

# Retrieve recent client logs
sudo journalctl -u twingate --since "1 hour ago"

What’s Next
Did this page help you?