TrustTunnel: AdGuard's obfuscated VPN protocol, reviewed for self-hosters

What TrustTunnel is, and who it is actually for

TrustTunnel is a VPN protocol plus a server-side endpoint implementation. The README describes it as "originally developed by AdGuard VPN and now available for anyone to use and audit," and the repository is licensed Apache-2.0. The project is split across three codebases: this repository holds the endpoint, a separate TrustTunnelClient repository holds the client library and CLI, and a TrustTunnelFlutterClient repository holds the GUI application. The endpoint itself is a Rust workspace with members for deeplink, endpoint, lib, macros and tools.

The intended audience is not the person who wants to tap install and forget about it. It is the operator who wants to run the server side of a tunnel on hardware they control, on Linux or macOS, and hand out credentials to a small set of users. The README's feature list is written from that perspective: the server tunnels TCP, UDP and ICMP, and the client supports split tunneling, a SOCKS5 proxy mode, and a custom DNS upstream. Those are operator-facing knobs, not consumer-app settings.

The design goal is stated plainly. TrustTunnel traffic is meant to be "indistinguishable from regular HTTPS traffic," which the README frames as a way to avoid throttling and deep-packet inspection. That is a different proposition from a protocol that optimizes purely for throughput or battery life. If your threat model does not include an adversary that fingerprints protocols, you are paying a complexity cost for a property you do not need.

How the protocol mimics HTTPS, and what the repo layout tells you

The README says the library implements a VPN protocol "compatible with HTTP/1.1, HTTP/2, and QUIC." That is the mechanism in one sentence: instead of a bespoke wire format that a middlebox can pattern-match, the tunnel is carried inside the same transports a browser would use. The repository keeps a PROTOCOL.md file at the top level, which is where the actual framing details live; the README only states the compatibility claim and does not reproduce the handshake.

The workspace layout reflects a deliberate split. The lib crate holds the shared logic, endpoint holds the server binary, macros holds build-time helpers, deeplink holds deep-link handling, and tools holds auxiliary binaries. A bench directory exists alongside these, and the Cargo.toml sets debug = true in the release profile, which keeps symbols in release builds. That is a useful choice for an operator who has to read a stack trace from a production binary, and an unusual one for a project optimizing for binary size.

Configuration is split across several files rather than one monolith. The Dockerfile comments name them explicitly: vpn.toml, hosts.toml, credentials.toml, rules.toml, and a certs directory, all persisted under /trusttunnel_endpoint in the container image. The Makefile exposes CONFIG_FILE ?= vpn.toml and HOSTS_CONFIG_FILE ?= hosts.toml as overridable variables, so the same binaries can run against different config sets. The filtering rules described in the README operate on client IP address, TLS random prefix, or TLS random with mask, which means the server can allow or deny connections based on properties of the handshake rather than only on credentials.

Installing the endpoint and completing a first run

The documented install path is a shell script that downloads a prebuilt package from the latest GitHub release and unpacks it to /opt/trusttunnel. The README gives this exact command:

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

Piping a remote script into a shell is a real supply-chain decision, and the repository does ship a VERIFY_RELEASES.md file, so the project is aware of the concern. Prebuilt packages cover linux-x86_64, linux-aarch64 and macos-universal. To pin a version instead of tracking latest, the README appends the version flag:

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

After installation, the directory contains a setup_wizard binary. Running it without arguments starts interactive mode, and the README notes that sudo is required because the wizard manages TLS certificates:

cd /opt/trusttunnel/
sudo ./setup_wizard

The wizard prompts for the listen address, the credentials file path, a username and password, whether to add another user, the rules file path, and connection filtering rules. For a native deployment the README suggests 0.0.0.0:443. For Docker port mapping 443:8443 it says to use 0.0.0.0:8443 instead. That mismatch is the single most likely first-run failure: the wizard's answer and the compose port mapping have to agree.

If you prefer containers, the repository ships a docker-compose.yml that builds the trusttunnel-endpoint target, maps 443 to 8443 over both TCP and UDP, and adds port 80 for the Let's Encrypt HTTP-01 challenge. It also defines a healthcheck that greps ss -ltn for the port named by TT_HEALTHCHECK_PORT, which defaults to 8443 in the compose file. State lives in the named volume trusttunnel_endpoint_data.

Updating the endpoint, and the rollback gap

The README is explicit that the install script always fetches the latest release, so updating means re-running the same install command. It also warns to stop the service first, because the installer replaces binaries in place:

sudo systemctl stop trusttunnel
curl -fsSL https://raw.githubusercontent.com/TrustTunnel/TrustTunnel/refs/heads/master/scripts/install.sh | sh -s -
sudo systemctl start trusttunnel

What the README does not document is rollback. There is no described way to return to the previous release if a new version breaks your configuration, and because the installer overwrites /opt/trusttunnel, the previous binaries are gone unless you archived them yourself. The -V flag can pin a version on a fresh install, which is the closest thing to an escape hatch, but the documentation does not present it as a downgrade procedure. An operator running this in production should snapshot the install directory before every update, and that is advice the project does not give.

The service name trusttunnel appears in the update instructions, which implies systemd integration, but the README does not show the unit file or say whether the installer creates it. That is a gap worth checking on your own machine before you rely on systemctl stop working.

Where TrustTunnel is the wrong tool

The clearest limitation is client coverage. The README lists the endpoint as compatible with Linux and macOS, and the client as available for Android, Apple, Windows and Linux. OpenWrt appears in the search terms people use around this project, but nothing in the README or the repository layout confirms a router build, so treating it as a router-grade client is not supported by the documentation. If your deployment depends on a router, you are outside what the project describes.

There is also no web panel in the materials. Configuration is file-based and wizard-driven, with credentials and rules living in TOML files under the install directory. Anyone expecting a browser UI for user management will not find one here. The README points to CONFIGURATION.md for details and to a separate Flutter client for the GUI side, which is a client application, not a server admin console.

The obfuscation goal cuts both ways. Because the protocol is designed to be indistinguishable from HTTPS, debugging it with ordinary network tools is harder than debugging a protocol with a distinctive handshake. The README does not describe a diagnostic mode or a way to disable the HTTPS mimicry for troubleshooting. If you need to inspect traffic on the wire to understand why a connection fails, this design works against you, and the documentation does not offer a workaround.

TrustTunnel compared with WireGuard

WireGuard is the obvious reference point, and the difference is architectural rather than incremental. WireGuard defines a compact, fixed wire format over UDP. That format is fast and simple, and it is also recognizable: network operators and censors have had years to build classifiers for it. TrustTunnel takes the opposite bet. Its README states the protocol is compatible with HTTP/1.1, HTTP/2 and QUIC so that it looks like ordinary web traffic, and it tunnels TCP, UDP and ICMP rather than only IP packets over a single UDP flow.

That trade has costs. TrustTunnel's endpoint is a Rust workspace with a multi-file TOML configuration, a setup wizard, and a certificate lifecycle to manage, including Let's Encrypt issuance through an HTTP-01 challenge on port 80. WireGuard's server configuration is a few lines of key material and an interface definition. If your problem is simply connecting two networks you control, WireGuard is the smaller commitment. If your problem is that a WireGuard-shaped flow gets throttled or blocked on the path you need, TrustTunnel is addressing exactly that, and the extra operational surface is the price.

The comparison to VLESS and Xray comes up in search data around this project, but the materials here do not describe those protocols, so a feature-by-feature comparison is not something this repository supports. What can be said from the README alone is that TrustTunnel's stated transport compatibility is HTTP/1.1, HTTP/2 and QUIC, and that its filtering rules can key on the TLS random prefix, which is a handshake-level control rather than a routing rule.

Editorial conclusion

Adopt TrustTunnel if you want an HTTPS-shaped tunnel you control and you are comfortable with a Rust workspace, a wizard-driven config, and systemd or Docker for process management. Do not adopt it if you need a documented rollback path for upgrades, a web admin panel, or a client for a platform outside Android, Apple, Windows and Linux. Before deploying, read CONFIGURATION.md end to end, confirm the wizard's listen address matches your port mapping, and check the credentials and rules files it writes.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. TrustTunnel/TrustTunnel on GitHub