gitwtfhub

wtf is mirage?

henryswisvip/mirage — explained in plain English

Analysis updated 2026-05-18

101GoAudience · developerComplexity · 4/5Setup · moderate

TL;DR

Mirage is a from-scratch, censorship-resistant encrypted tunnel in Go, running as a single binary that acts as both server and Mac client for private internet access.

Mindmap

mindmap
  root((mirage))
    What it does
      Encrypted tunnel
      Server and client in one binary
      Decoy fallback
    Tech stack
      Go
      SOCKS5
      AES 256 GCM
    Use cases
      Private internet access
      Censorship resistance
      Protocol reference
    Audience
      Developers
      Privacy focused users

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Run a private encrypted tunnel between a rented server and your Mac to reach the open internet.

REASON 2

Resist network probing by having the server respond to unauthenticated connections as a decoy website.

REASON 3

Route individual apps or your whole Mac's traffic through a local SOCKS5 proxy backed by the tunnel.

REASON 4

Study the protocol spec as a reference for a minimal, dependency-free encrypted tunnel design.

What's in the stack?

GoSOCKS5AES-256-GCM

How it stacks up

henryswisvip/mirage0xmassi/pocketdevaymanhs/nanotdb
Stars101101102
LanguageGoGoGo
Setup difficultymoderatemoderatemoderate
Complexity4/53/53/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Requires a remote server you control plus a Mac client, no forward secrecy if the shared key leaks.

No license information is stated in the README.

Wtf does this do

Mirage is a small encrypted tunnel written from scratch in Go, built by one person as an alternative to existing tools like Xray, V2Ray, or Shadowsocks rather than a wrapper around them. A single small binary, about 2.5 megabytes, acts as both the server, which you run on a rented server abroad, and the client, which runs on your Mac. Apps on your Mac connect to a local proxy, and everything sent from there to the server is encrypted so it looks like random bytes to anyone watching the network. The README explains its design goals for resisting network censorship: after the initial connection, the traffic has no recognizable pattern for filtering systems to detect, since there are no plaintext headers or fixed-size handshakes. If someone tries to probe the server to check whether it is a proxy, the server does not respond like one. Instead it either silently ignores the connection or forwards it to a real, unrelated website so the prober just sees ordinary web traffic. Each session uses a fresh random value and a timestamp to prevent replay attacks, and the encryption itself relies on standard, well reviewed building blocks: AES-256-GCM and HKDF-SHA256, both part of Go's standard library, with no custom-built ciphers. Setting it up involves cloning the repository onto a remote server and running an install script that sets up the service, generates a secret key, and prints a link you paste into a Mac client, either a SwiftUI app or a command line script. The client then exposes a local proxy that other apps can point to, either individually or by switching the whole Mac's network settings. The author is explicit about the project's limits: it has no forward secrecy, so a leaked key could expose past traffic, it does not disguise itself as a real TLS connection the way some competing tools do, it only tunnels TCP traffic and not UDP, and it has not been independently security audited. The README closes by asking that it be used lawfully.

Yoink these prompts

Prompt 1
Walk me through setting up a Mirage server on a remote VM and connecting from my Mac.
Prompt 2
Explain how Mirage's decoy fallback works when someone probes the server.
Prompt 3
What are Mirage's stated security limitations compared to more established tunnel tools?
Prompt 4
How do I rotate my Mirage pre-shared key if I think it has been exposed?

Frequently asked questions

wtf is mirage?

Mirage is a from-scratch, censorship-resistant encrypted tunnel in Go, running as a single binary that acts as both server and Mac client for private internet access.

What language is mirage written in?

Mainly Go. The stack also includes Go, SOCKS5, AES-256-GCM.

What license does mirage use?

No license information is stated in the README.

How hard is mirage to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is mirage for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.