GreenTunnel: splits the TLS ClientHello so the hostname never lands whole in a packet, and says plainly that it is not a VPN
GreenTunnel is an anti-censorship utility designed to bypass the DPI system that is put in place by various ISPs to block access to certain websites.
At a glance
- What is it?
- GreenTunnel is SadeghHayeri's MIT licensed TypeScript utility for defeating hostname based DPI blocking, rewritten in v3 with backpressure, RFC 8484 DoH and DoT, and a system proxy layer that restores your settings after a crash. Its own documentation limits its claim to hostname blocking and nothing more, and its maintainer now asks for prompts instead of large pull requests.
- Who is it for?
- GreenTunnel fits a specific and narrow problem: a network where a hostname is blocked because a middlebox read it out of the TLS handshake, and where the full tunnel of a VPN is more than you need or more than you are permitted. It does not fit anything requiring anonymity, because the project states outright that it does not hide your IP address and defeats hostname based blocking, nothing more.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- SadeghHayeri/GreenTunnel4,955 ★ · +41
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| SadeghHayeri/GreenTunnel | 4.9k | 5k |
41 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The scope limit is stated before anything else in the file
The README opens its technical description with a scope note. GreenTunnel does not hide your IP address and is not a VPN, and it defeats hostname based blocking, nothing more. That sentence bounds every claim that follows, so read it as the acceptance criterion rather than as a disclaimer. The mechanism it documents is correspondingly narrow: a local proxy that splits the TLS ClientHello so the hostname being visited never appears whole in a single packet, plus DNS resolution over an encrypted channel so the resolver cannot be used to block or observe you either. Both halves target the same inspection point. A middlebox that reads the Server Name Indication extension during the handshake sees fragments instead of a name, and a resolver that logs queries sees encrypted transport instead of a hostname. What neither does is conceal the connection itself, which is why the IP statement is there.
Fragmentation is four knobs, and one of them re-frames the pieces
The fragmentation settings are the core of the tool and there are exactly four. `--fragment-size <n>` sets bytes per piece and defaults to 40. `--fragment-delay <ms>` pauses between pieces and defaults to 0, which means pieces go out back to back unless you change it. `--tls-records` re-frames the pieces as valid TLS records, and the example section recommends it for DPI that reassembles TCP. `--no-fragment` forwards the ClientHello untouched. The README says GreenTunnel splits the handshake at the moment it forwards it, starting with a TCP split of the ClientHello. The reason SNI is the target at all is stated plainly: it sends the target hostname in plaintext during the handshake, and that is the one part of an HTTPS connection a DPI box can still read.
Boolean environment variables are on when set to anything, including false
This is the configuration detail most likely to surprise you in a deployment, so it is worth reading twice. Boolean variables are on when set to anything and off when unset, and the example given is that `HTTPS_ONLY=false` still turns it on. So the container has no way to express false as a value. The documented variables are TLS_RECORDS, NO_FRAGMENT and HTTPS_ONLY, all defaulting to off, and to turn one off in Docker you must leave it unset rather than assign a false-looking string. The rest of the table has ordinary string values: HOST for the address to bind inside the container defaulting to 0.0.0.0, PORT defaulting to 8000, DNS_MODE accepting doh, dot or plain and defaulting to doh, DOH_URL defaulting to Cloudflare, DOT_HOST for the DoT server when DNS_MODE=dot defaulting to 1.1.1.1, DNS_SERVER for the plain resolver defaulting to system, FRAGMENT_SIZE at 40, FRAGMENT_DELAY at 0, and LOG_LEVEL running from silent to trace with info as default.
The container binds all interfaces while the CLI binds loopback
Compare the two defaults and you have a real deployment decision. The CLI usage block gives `--host <ip>` a default of 127.0.0.1 and `--port <n>` a default of 8000, where 0 means random. The container's HOST variable defaults to 0.0.0.0. So the same program started two ways exposes itself differently: run from a terminal it listens on loopback only, run from Docker with the published port it listens on every interface of the container, which the -p flag then maps to the host. The documentation does state that the container never touches a system proxy and that you should point your client at it, so the intent is that the operator knows the address. The documented Docker forms cover a basic run, a custom port through `-e PORT=9000` with a matching mapping, and a backgrounded run with `-d --restart unless-stopped`. None of them restrict the bind address, so exposing that port is an explicit choice rather than an accident waiting to happen.
The system proxy layer snapshots your settings and puts them back
The v3 rewrite added a system proxy layer, and the recovery story is the substantive part of it. The desktop app snapshots your system proxy settings before changing them and restores them when it stops, including after a crash, on the next launch. So a crash does not leave your machine pointed at a proxy that is no longer running, and the recovery happens on the next start rather than requiring you to know what was changed. The CLI auto-sets the system proxy on a basic run, with `--no-system-proxy` documented as the way to leave the OS alone and configure the client yourself. The library exposes the same pieces as code, importing Proxy, SystemProxy and DEFAULT_BYPASS from green-tunnel, enabling the system proxy against the address the proxy reports after start, listening on a tunnel:open event, and later disabling the system proxy and stopping the proxy. The desktop app itself is a 340 px window with an on and off switch, a tray icon, and an Advanced panel for DNS transport, port, fragmentation and log level.
Seven runtime dependencies were removed in v3, leaving two
The dependency story is the clearest statement of how complete the rewrite was. Runtime dependencies are down to two, dns-packet and lru-cache. Everything else that v2 pulled in is gone: yargs, chalk, ora, debug, dns-socket, validator and winreg, all replaced by things Node ships with. That is visible in the repository structure too, where the root manifest is a private workspace named green-tunnel-workspace at version 0.0.0, with workspaces for packages/* and apps/*, and the Dockerfile explains that only packages/cli is part of the image while apps/desktop is an Electron app whose devDependencies would add roughly 200 MB of build tooling that never ships. Node.js 24 or newer is required for the CLI and the library, while the desktop app and the Docker image bring their own runtime. Compatibility was kept deliberately: the engine and the gt command ship as one package, so the v2 import of Proxy from green-tunnel still works unchanged.
The maintainer asks for prompts, and takes large diffs no longer
The contribution policy is unusual enough to state accurately because it changes what a contributor should do. The instruction is to contribute prompts, not pull requests. Large diffs are not taken. If you want to change something in GreenTunnel, you send the prompt instead, described as the final one, the one you would hand to your own agent: open an issue, label it `PROMPT REQUEST`, and paste it in. The maintainer then runs it against the codebase, reviews the output, and opens the pull request, committed with your email so it lands in the history as your contribution. The stated reason is that a sharp prompt is worth more to the project than a big patch, because it is the part the maintainer cannot write for you and the part that decides what the code becomes. Prompts are also expected to name the files, say what done looks like, and say how to verify, and several prompts in sequence are welcome. Small focused pull requests are still welcome, a bug fix, a typo, a dead link.
Three install paths and an unsigned desktop build
Installation is npm, a desktop installer, or a container. The npm route is:
npm install -g green-tunnelAfter installation you run it as either `gt` or `green-tunnel`. The desktop app ships a .dmg for macOS, a .exe for Windows, and an .AppImage or a .deb for Linux. Those builds are currently unsigned, which means macOS Gatekeeper and Windows SmartScreen will warn on first launch, and the documented workaround for macOS is to right-click the app and choose Open. The container route is `docker run -p 8000:8000 sadeghhayeri/green-tunnel`. So the CLI is the least frictionful and most scriptable path, the desktop app is the one that gives you the proxy restore behaviour on a desktop, and the container is the one that never touches the system proxy at all. Which one you pick determines whether your operating system configuration is modified behind your back, and that is the more consequential difference than the interface. A basic run is just `gt`, which starts the proxy and sets the system proxy for you.
Editorial conclusion
GreenTunnel fits a specific and narrow problem: a network where a hostname is blocked because a middlebox read it out of the TLS handshake, and where the full tunnel of a VPN is more than you need or more than you are permitted. It does not fit anything requiring anonymity, because the project states outright that it does not hide your IP address and defeats hostname based blocking, nothing more. Read three configuration traps before you rely on it. Every boolean environment variable is on when set to anything, so `HTTPS_ONLY=false` still enables it. The container binds 0.0.0.0 by default while the CLI binds 127.0.0.1, so an exposed port is exposed to your network. And the desktop builds are unsigned, so expect Gatekeeper and SmartScreen warnings. The engine ships with two runtime dependencies, dns-packet and lru-cache, after v3 dropped seven others. The last push is dated 2026-10-30 and the newest release is v3.0.5 from 2026-07-26.
Frequently asked questions
what is green tunnel
GreenTunnel is an MIT licensed utility from SadeghHayeri that defeats DPI based hostname blocking. It runs a local proxy that splits the TLS ClientHello so the hostname never appears whole in a single packet, and resolves DNS over an encrypted channel so the resolver cannot be used to block or observe you. It is not a VPN and does not hide your IP address.
how to use greentunnel
Install it with `npm install -g green-tunnel` on Node.js 24 or newer, then run `gt`, which starts the proxy on 127.0.0.1 port 8000 and sets the system proxy. Fragmentation defaults to 40 byte pieces, DNS defaults to DoH, and `--no-system-proxy` leaves your operating system untouched if you would rather configure the client yourself.
is greentunnel safe
The project states that it does not hide your IP address and is not a VPN, and that it defeats hostname based blocking and nothing more, so it offers no anonymity. Its scope is narrow by design: a local proxy that fragments the TLS ClientHello and encrypts DNS. It is MIT licensed, and after the v3 rewrite its only runtime dependencies are dns-packet and lru-cache.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/sadeghhayeri-greentunnel)Star history chart for your README
[](https://hysenlabs.com/projects/sadeghhayeri-greentunnel)Was this useful?