Deploying Twingate Connector on Ubiquiti Gateways

Overview

This guide walks you through deploying a Twingate Connector on a Ubiquiti Gateway (UDM Pro, UDM SE, UXG-Pro, UXG-Max, and similar devices). The setup script creates a lightweight systemd-nspawn container on the Gateway, installs the Connector inside it, and configures it to start automatically on boot.

The container is stored on the Gateway’s persistent /data partition, so it survives firmware upgrades.

Prerequisites

Before you begin, ensure you have the following:

• A Ubiquiti Gateway (UDM Pro, UDM SE, UXG-Pro, UXG-Max, or similar) running UniFi OS 3.x or later.
• SSH access to the Gateway as root.
• A Twingate account with access to the Admin Console.
• Internet connectivity on the Gateway.

Installation Steps

1. Generate Connector Access and Refresh Tokens

Start by generating new Access and Refresh tokens for a Connector. Follow these steps:

• Log in to the Twingate Admin Console.
• Navigate to Remote Networks.

  

• Select the Remote Network you want to add a Connector to.
• Add a Connector or select one that hasn’t been deployed yet.

  

• Select See More

  

• Select the Manual option.

  

• Scroll down to Step 2 and click Generate Tokens.

  

• Authenticate when prompted to complete token generation.
• Copy the Network name, Access Token, and Refresh Token displayed. These will be used in the next step. Your Network name is the subdomain of your Twingate URL (e.g., mycompany from https://mycompany.twingate.com).

2. Deploy the Connector

SSH into your Ubiquiti Gateway and run the following command, replacing the placeholder values with the credentials from Step 1:

curl -sSf https://raw.githubusercontent.com/Twingate-Community/ubiquiti-connector/main/setup.sh | sudo TWINGATE_NETWORK="mycompany" TWINGATE_ACCESS_TOKEN="<your-access-token>" TWINGATE_REFRESH_TOKEN="<your-refresh-token>" bash

The script will bootstrap a Debian container, install the Twingate Connector inside it, and configure it to start on boot.

You can also set the CONTAINER_NAME environment variable to override the default container name (twingate-connector). This is useful if you are deploying multiple Connectors on the same Gateway.

3. Verify Installation

• Navigate back to the Admin Console.
• Navigate to Remote Networks.
• Select the Remote Network you added your new Connector to.
• Select the new Connector.
• Verify that the Controller and Relay statuses are connected.

  

4. Access Your Ubiquiti Gateway Remotely

Now that your Connector is running, add the Gateway’s web UI as a Twingate Resource so you can access it from anywhere.

• Navigate to the Twingate Admin Console.
• Click on Resources in the top sub menu.
• Click the + Resource button in the top right corner.
• Select the Remote Network you installed your Connector on.
• Give the Resource a name (e.g., “Ubiquiti Gateway”).
• Add the Gateway’s private IP address. This is the same address you use to access the UniFi dashboard locally, typically in the format 192.168.x.x.
• Assign access to one of your Groups by selecting one in the list and clicking Grant Access.
• Connect to Twingate and navigate to the Gateway’s IP address in your browser. You should see the UniFi dashboard load as if you were on your local network.

Container Management

Use the following commands over SSH to manage the Connector container. If you set a custom CONTAINER_NAME during setup, replace twingate-connector with that name.

To open a shell inside the container:

nsenter -t $(machinectl show twingate-connector -p Leader --value) \
  -m -u -i -n -p -- /bin/bash

Uninstall

To completely remove the Connector and its container, run the uninstall script that is available in the GitHub repository.

sudo ./uninstall.sh

Troubleshooting

Token Errors

Verify that the Network name, Access Token, and Refresh Token were entered correctly. Tokens are single-use per Connector — if you need to redeploy, generate a new set in the Admin Console.

Container Fails to Start

Check the container status and logs:

machinectl status twingate-connector
journalctl -M twingate-connector -xe --no-pager

Connector Not Connecting

• Verify DNS resolution inside the container:
  Copy

  nsenter -t $(machinectl show twingate-connector -p Leader --value) -m -u -i -n -p -- curl -s https://binaries.twingate.com

• Check Connector logs:
  Copy

  nsenter -t $(machinectl show twingate-connector -p Leader --value) -m -u -i -n -p -- journalctl -u twingate-connector -n 50 --no-pager

Container Missing After Firmware Upgrade

The container data in /data/custom/machines/ persists across firmware upgrades. However, the symlink at /var/lib/machines/ and the nspawn config at /etc/systemd/nspawn/ may need to be recreated. Re-running the setup script will detect the existing container directory and handle this.

Bootstrap Takes a Long Time

This is normal on Gateway hardware. Expect approximately 5-10 minutes depending on your internet connection and device model.

If issues persist, take a look at the general troubleshooting docs.

Next Steps

Once Twingate is configured, you can explore additional resources to enhance your setup:

• Proxmox Setup Guide: Deploy a Connector on your Proxmox VE server.
• Home Assistant Setup Guide: Integrate Twingate with Home Assistant.
• Unraid Setup Guide: Deploy a Connector on Unraid with the official Community App.
• Setting Up Resources: Configure Twingate Resources to access private applications and services.