GreenTunnel: a local proxy that splits the TLS ClientHello to defeat DPI blocking

The specific block GreenTunnel is built to defeat

Many ISPs inspect the traffic that passes through them and drop or reset connections based on the hostname visible in the handshake. GreenTunnel targets exactly that class of block. It runs a proxy on your own machine, and when a client connects through it, the TLS ClientHello is split so the hostname you are visiting never appears whole in a single packet. The README states this plainly: the utility "splits the TLS ClientHello so the hostname you are visiting never appears whole in a single packet, and resolves DNS over an encrypted channel so your resolver cannot be used to block or observe you either."

The audience is narrow on purpose. This is for someone who can install a Node package or run a container, understands what a system proxy setting is, and is willing to configure a browser or an application to point at 127.0.0.1:8000. It is not a consumer VPN and the README is direct about that: "GreenTunnel does not hide your IP address and is not a VPN. It defeats hostname-based blocking, nothing more." If your traffic is blocked by IP address, or by a full traffic-shaping policy, fragmentation of a hostname does nothing for you.

How the fragmentation engine and DNS layer fit together

The repository is an npm workspace with packages/* and apps/*. The Dockerfile explains the split: "Only `packages/cli` takes part in the image, `apps/desktop` is an Electron app and pulling its devDependencies in would add ~200 MB of build tooling that never ships. `packages/cli` is the whole of GreenTunnel: the engine lives in its `src/core`." So the engine, the CLI and the desktop UI are separate workspaces, and the container ships only the engine.

On the wire, two mechanisms run in sequence. First, the ClientHello is chopped into pieces. The CLI exposes --fragment-size (default 40 bytes), --fragment-delay (default 0 ms) and --tls-records, which re-frames the pieces as valid TLS records. The README describes the last one as the option for "DPI that reassembles TCP", which is the honest way to put it: plain fragmentation defeats middleboxes that match on a single packet, and re-framing as TLS records is the stronger setting when the middlebox is willing to reassemble. Second, DNS is resolved over an encrypted channel, with --dns taking doh, dot or plain, a DoH endpoint defaulting to Cloudflare, and a DoT server defaulting to 1.1.1.1 on port 853.

The v3 release notes describe the engine as a ground-up TypeScript rewrite with "real backpressure and timeouts" and RFC 8484 DoH and DoT. That is a claim about the implementation, not a benchmark, and the README does not publish throughput numbers. What it does publish is a dependency count: runtime dependencies are down to two, with yargs, chalk, ora, debug, dns-socket, validator and winreg removed in favour of things Node ships with. For a tool that sits between you and every request you make, a smaller dependency surface is a defensible design goal.

Installing GreenTunnel with npm

The README lists Node.js 24 or newer as the requirement for the CLI and the library, and notes that the desktop app and the Docker image bring their own runtime. The recommended install is global:

npm install -g green-tunnel

After that, the command is either gt or green-tunnel. Running gt with no arguments starts the proxy on 127.0.0.1:8000 and, by default, sets the system proxy for you. The README's basic example is just:

gt

If you would rather not have the tool touch your OS settings, there is a flag for that, and it is the one to reach for first on a machine you care about:

gt --no-system-proxy

With that flag the proxy still listens, but you configure the client yourself. Point your browser or application at 127.0.0.1:8000 and load a host you know is blocked. If the page loads, fragmentation is doing its job. If it does not, the README points you to a "Good to know" section rather than promising a fix.

When a site stays blocked, the first knob to try is the stricter fragmentation mode:

gt --tls-records --log-level debug

The debug log level is documented as one of silent, error, warn, info, debug or trace, and -q, --quiet suppresses the banner and logs entirely.

Running GreenTunnel in Docker and what the container will not do

The image is published as sadeghhayeri/green-tunnel and the README gives a one-liner:

docker run -p 8000:8000 sadeghhayeri/green-tunnel

The container never touches a system proxy, which the README states directly: "point your client at it." That makes Docker the cleaner deployment if you want GreenTunnel on a home server or a router-adjacent box and would rather not have a desktop process editing proxy settings.

Configuration inside the container is by environment variable, and the README's table is the reference. HOST defaults to 0.0.0.0 and PORT to 8000, DNS_MODE to doh, FRAGMENT_SIZE to 40, FRAGMENT_DELAY to 0, and LOG_LEVEL to info. TLS_RECORDS, NO_FRAGMENT and HTTPS_ONLY are switches. There is a trap in that table worth quoting: "Boolean variables are on when set to anything and off when unset, HTTPS_ONLY=false still turns it on." That is a real footgun for anyone used to Compose files where false means false. A custom port and a restart policy look like this:

docker run -d --restart unless-stopped -e PORT=9000 -p 9000:9000 sadeghhayeri/green-tunnel

The Dockerfile also documents a versioning detail: the release number is supplied by the publish workflow from the git tag, and "without this `gt --version` would report 0.0.0 inside the image." A plain local docker build therefore reports 0.0.0, which the file calls honest because that image is not a release. If you build your own image, do not read 0.0.0 as a bug.

Where GreenTunnel is the wrong tool

The limitation is stated by the project itself, and it is not a small one: no IP hiding. If an ISP blocks by address, or if a service geo-restricts by source IP, fragmenting a hostname changes nothing. Anyone reaching for GreenTunnel as a VPN substitute has misread it.

The second boundary is platform. The README documents an npm package, a Docker image, and a desktop app with installers for macOS (.dmg), Windows (.exe) and Linux (.AppImage or .deb). It does not document an Android or iOS build, and the release list contains no mobile artifact. A reader searching for a GreenTunnel APK will not find one documented here.

Third, the desktop installers are unsigned, and the README says so: "macOS Gatekeeper and Windows SmartScreen will warn on first launch. On macOS, right-click the app and choose Open." That is a friction point for anyone distributing the app to non-technical users.

Fourth, the system-proxy layer is convenient and invasive at the same time. It snapshots your settings and restores them, the v3 notes say, "even after a crash", but the mechanism is still a process rewriting an OS-level setting. On a machine where other tools also manage the proxy, that is a conflict waiting to happen. --no-system-proxy exists precisely because of this.

Finally, DPI that reassembles TCP is a moving target. --tls-records is the documented answer, but the README does not claim it defeats every middlebox, and there is no published measurement of what fraction of networks it handles.

How GreenTunnel differs from GoodbyeDPI and PowerTunnel

The closest comparisons people search for are GoodbyeDPI and PowerTunnel, and the difference is mostly about where the code runs and what it is written in. GoodbyeDPI is a Windows-side tool that works at the packet level on the host; GreenTunnel is a cross-platform Node application that presents itself as a local proxy, which is why it can ship as an npm package and a Linux container.

PowerTunnel is the nearer architectural relative: it is also a local proxy that manipulates the handshake. The practical difference with GreenTunnel v3 is the runtime. GreenTunnel is TypeScript on Node 24 or newer, with the engine in packages/cli/src/core and the UI in an Electron app, and the v3 notes emphasise that runtime dependencies are down to two. If you already run Node services and want a proxy you can start from a container or a systemd unit, that packaging story is the reason to pick it. If you want a Windows-only tool that installs as a service and never involves a Node runtime, GoodbyeDPI is the more direct fit.

One more difference is governance rather than technology. The maintainer's note in the README asks contributors to "Contribute prompts, not pull requests", with large diffs declined and prompt requests opened as labelled issues that the maintainer runs and commits under the contributor's email. Small focused PRs, bug fixes, typos and dead links, are still accepted. Whether that model suits you is a judgement about how you want to contribute, not about whether the software works.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-13. The most recent release in the list is v3.0.5 from 2026-07-26, following v2.0.2 and v2.0.1 in March 2026. That is a codebase with recent activity, though the README does not publish a support policy or a compatibility guarantee between minor versions.

The licence is MIT, declared in the repository's package.json and shown as a badge in the README. MIT is permissive: you can use, modify and redistribute the code, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not legal advice; if you are redistributing the desktop app or bundling the engine, read LICENSE and take your own counsel.

The upgrade cost is concrete. Node 24 or newer is required for the CLI and the library, and the workspace engines field pins >=24.0.0. The v3 rewrite removed yargs, chalk, ora, debug, dns-socket, validator and winreg, so any script that depended on those transitive packages, or on the v2 CLI surface, needs checking against the current --help output before you move. The Dockerfile notes that npm ci validates the whole workspace tree against the lockfile, meaning a missing workspace member is an error even when it is not an install target; if you fork and delete apps/desktop, expect that to break the container build until you adjust the manifests. Rollback is not documented in the README, so pin a version you have verified rather than tracking latest.

Editorial conclusion

Adopt GreenTunnel if your ISP blocks by hostname and you want a self-hosted, MIT-licensed proxy you can point a browser at, or run in Docker with the environment variables in the README. Do not adopt it if you need IP anonymity, if you are on a phone (no Android build appears in the repository or the release list), or if the block is IP-based rather than name-based. Before rolling it out, run gt --no-system-proxy and confirm the local proxy actually reaches a blocked host, and check that your Node version is 24 or newer.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. SadeghHayeri/GreenTunnel on GitHub