TrustTunnel v1.1.0

Clients · App Store (iOS) · App Store (macOS) · Play store

---

Table of Contents

• Introduction
• Server Features
• Client Features
• Quick start
  • Endpoint setup
    • Install the endpoint
    • Updating the endpoint
    • Endpoint configuration wizard
    • Let's Encrypt certificate lifecycle
    • Running endpoint
    • Export client configuration
  • Client setup
    • Install the client
    • Updating the client
    • Client configuration wizard
    • Running client
• Clients
• See also
• Roadmap
• License

---

Introduction

TrustTunnel is a modern, open-source VPN protocol originally developed by AdGuard VPN and now available for anyone to use and audit.

It delivers fast, secure, and reliable VPN connections without the usual trade-offs. By design, TrustTunnel traffic is indistinguishable from regular HTTPS traffic, allowing it to bypass throttling and deep-packet inspection while maintaining strong privacy protections.

The TrustTunnel project includes the VPN endpoint (this repository), the library and CLI for the client, and the GUI application.

Server Features

• VPN Protocol: The library implements the VPN protocol compatible with HTTP/1.1, HTTP/2, and QUIC. By mimicking regular network traffic, it becomes impossible to detect and block.

• Flexible Traffic Tunneling: TrustTunnel can tunnel TCP, UDP, and ICMP traffic to and from the client.

• Platform Compatibility: The server is compatible with Linux and macOS. The client is available for Android, Apple, Windows, and Linux.

• Subscription Endpoint: Optionally serve a per-user subscription URL over HTTPS. When [subscription] is enabled in vpn.toml, each client can fetch its own JSON configuration (connection parameters, credentials, DNS upstreams, and more) over HTTPS using HTTP Basic Auth, enabling self-service and auto-refreshing client configuration without manual file redistribution.

---

Client Features

• Traffic Tunneling: The library is capable of tunneling TCP, UDP, and ICMP traffic from the client to the endpoint and back.

• Cross-Platform Support: It supports Linux, macOS, and Windows platforms, providing a consistent experience across different operating systems.

• System-Wide Tunnel and SOCKS5 Proxy: It can be set up as a system-wide tunnel, utilizing a virtual network interface, as well as a SOCKS5 proxy.

• Split Tunneling: The library supports split tunneling, allowing users to exclude connections to certain domains or hosts from routing through the VPN endpoint, or vice versa, only routing connections to specific domains or hosts through the endpoint based on an exclusion list.

• Custom DNS Upstream: Users can specify a custom DNS upstream, which is used for DNS queries routed through the VPN endpoint.

---

Quick start

Endpoint setup

Install the endpoint

An installation script is available that can be run with the following command:

curl -fsSL https://raw.githubusercontent.com/TrustTunnel/TrustTunnel/refs/heads/master/scripts/install.sh | sh -s -

The installation script will download the prebuilt package from the latest GitHub release for the appropriate system architecture and unpack it to /opt/trusttunnel. The output directory could be overridden by specifying -o DIR flag at the end of the command above.

If you want to install a specific version (instead of the latest), use -V <version>:

curl -fsSL https://raw.githubusercontent.com/TrustTunnel/TrustTunnel/refs/heads/master/scripts/install.sh | sh -s - -V <version>

[!NOTE] Prebuilt packages are available for linux-x86_64, linux-aarch64, and macos-universal (Intel and Apple Silicon) architectures.

Updating the endpoint

The installation script always installs the latest available version. So, to update your installation, run the install command again:

curl -fsSL https://raw.githubusercontent.com/TrustTunnel/TrustTunnel/refs/heads/master/scripts/install.sh | sh -s -

This re-runs the installer and replaces the binaries in the installation directory (/opt/trusttunnel by default, or the directory you specified with -o DIR).

[!NOTE] Don't forget to stop the endpoint before updating:

sudo systemctl stop trusttunnel

To start the endpoint again after updating:

sudo systemctl start trusttunnel

Endpoint configuration wizard

Please refer to the CONFIGURATION.md for the more detailed documentation on how to configure the endpoint.

The installation directory contains setup_wizard binary that helps generate the config files required for the endpoint to run:

cd /opt/trusttunnel/
./setup_wizard -h

The setup wizard supports interactive mode, so you could run it and it will ask for data required for endpoint configuration.

cd /opt/trusttunnel/
sudo ./setup_wizard

[!NOTE] sudo is required to manage TLS certificates properly.

The wizard will ask for the following fields, some of them have the default values you could safely use:

• The address to listen on - specify the address for the endpoint to listen on. Use 0.0.0.0:443 for native deployments (HTTPS on all interfaces). If you run with Docker port mapping 443:8443, set it to 0.0.0.0:8443.
• Path to credentials file - path where the user credentials for authorization will be stored.
• Username - the username the user will use for authorization.
• Password - the user's password.
• Add one more user? - select yes if you want to add more users, or no to continue the configuration process.
• Path to the rules file - path to store the filtering rules.
• Connection filtering rules - you can add rules that the endpoint will use to allow or disallow user's connections based on:
  • Client IP address
  • TLS random prefix
  • TLS random with mask