Linux Headless Mode

The Twingate Client for Linux may be run in headless mode, allowing it to be used in environments where a graphical user interface is not available. This is particularly useful in server environments where the Client is required to run as a background service.

Twingate’s 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.

Prerequisites

• A Twingate account with the necessary permissions to create and manage Services. See the Services documentation for more information on how to create a Service account and Service Keys.

Working with the Linux Client in systemd

Installation & configuration

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

For example:

curl https://binaries.twingate.com/client/linux/install.sh | 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

Troubleshooting

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"

Working with the Linux Client in Docker

The Linux Client may also be run in a Docker container. This may be useful in situations where only an individual service requires access to Twingate protected Resources.

Prior to running the Docker container, ensure that the Service Key is available on the host system. The Service Key should be mounted into the container using a volume.

Running the Client in Docker

The command below will run the Twingate Client in a Docker container, mounting the Service Key from the host system and starting the Client in headless mode. The command can be modified to suit the specific requirements of the environment, but the following parameters are required:

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

Without these two parameters the Client running inside of the container will not be able to connect to Twingate.

docker run -d\
  -v /path/to/service-key/:/etc/twingate-service-key/ \
  --device /dev/net/tun \
  --cap-add NET_ADMIN \
  ubuntu:latest bash -c "
    apt-get update &&
    apt-get install curl -y &&
    curl https://binaries.twingate.com/client/linux/install.sh | bash &&
    sudo twingate setup --headless /etc/twingate-service-key/service-key.json &&
    sudo twingate start &&
    sleep infinity
  "

Alternatively, you can use Docker Compose to manage the container. An example docker-compose.yml file is shown below:

version: "1.0"

services:
  tg-headless-client:
    image: ubuntu:latest
    command: >
      bash -c "apt-get update
      && apt-get install curl -y
      && curl https://binaries.twingate.com/client/linux/install.sh | bash
      && sudo twingate setup --headless /etc/twingate-service-key/service-key.json
      && sudo twingate start
      && sleep infinity"
    volumes:
      - /path/to/service-key/:/etc/twingate-service-key/
    devices:
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    restart: unless-stopped

Finally, if you are using the Client to support a specific service and want it to only be available for that service, you can use a Compose file to load both containers and tie them together:

version: "1.0"

volumes:
  uptime-kuma:
    external: true

services:
  tg-headless-client:
    image: ubuntu:latest
    container_name: tg-headless-client
    command: >
      bash -c "apt-get update
      && apt-get install curl -y
      && curl https://binaries.twingate.com/client/linux/install.sh | bash
      && sudo twingate setup --headless /etc/twingate-service-key/service-key.json
      && sudo twingate start
      && sleep infinity"
    volumes:
      - /path/to/service-key/:/etc/twingate-service-key/
    devices:
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - "3001:3001"
    restart: always
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    volumes:
      - uptime-kuma:/app/data
    network_mode: "service:tg-headless-client"
    depends_on:
      - tg-headless-client
    restart: always

In this example we are loading the Twingate Client in headless mode and then loading the Uptime Kuma service. Uptime Kuma is a commonly used open-source uptime monitoring and alerting system, and we want it to be able to access Resources in Remote Networks via the Twingate service. The network_mode: "service:tg-headless-client" line ties the Uptime Kuma service to the Twingate Client service, allowing it to access the network tunnel created by the Client.