XChaCha20-Poly1305 pre-shared key proxy with two transports:
- TCP proxy server + local SOCKS5 client
- UDP proxy server + local SOCKS5 client
- Go 1.25+
- Windows PowerShell (for
build.ps1) - Optional:
make(forMakefiletargets on Unix-like systems)
build.ps1 and Makefile force GOTOOLCHAIN=go1.25.4+auto to avoid broken local Go runtime installations.
Main settings live in config.json:
| Field | Meaning |
|---|---|
serverListen |
Server bind address (example: 0.0.0.0:8443; on Windows avoid ports inside excluded ranges) |
clientListen |
Local SOCKS5 address (example: 127.0.0.1:1080) |
serverAddr |
Remote server address for the client |
transport |
tcp or udp |
timeout |
Timeout in seconds (number) |
bufferSize |
Client TCP copy buffer size in bytes (default 32768) |
verbose |
true or false (or 1 / 0) for debug logs |
pskKey |
Shared key, exactly 64 hex characters |
routing |
Optional client routing (see below) |
Generate a key:
.\build.ps1 genkeyPut the output into pskKey in config.json.
Makefile uses jq only to sanity-check pskKey before run-server / run-client. The client is started with --config config.json so routing and all client fields come from JSON.
Only the client applies routing: each SOCKS target gets an outbound — proxy (through whitenoise), direct (plain TCP connect), or block (reject).
Add a routing object to config.json:
| Field | Meaning |
|---|---|
geoipFile |
Path to geoip.dat (v2ray/xray format) |
geositeFile |
Path to geosite.dat |
domainStrategy |
AsIs (default), IpIfNonMatch, or IpOnDemand (last two behave like Xray for our matcher set) |
rules |
Ordered rules (first match wins) |
final |
Outbound when nothing matches (default proxy) |
Each rule:
domain— string list:geosite:TAG,ext:other.dat:TAG,regexp:…,domain:…,full:…,keyword:…, plain substring (like Xray), plusgeosite:TAG@attrfor@attribute filters when present in the list data.ip— string list:geoip:XX,geoip:!XX,ext-ip:file.dat:TAG, or a literal1.2.3.0/24/::1/128.network— optional["tcp"],["udp"], or both (omit for both).protocol— optional["bittorrent"](TCP only, detected by sniffing BitTorrent handshake).outbound—proxy,direct, orblock.
Geo databases (same family as Xray-core), e.g. community builds:
This repo reads .dat entries sequentially (like Xray’s streaming find in infra/conf/router.go): only the matching country/tag slice is unmarshalled, not the whole file into RAM. Domain matching reuses the MPH matcher from Xray (internal/strmatcher, MPL-2.0).
UDP: block is honored; direct is not implemented yet (falls through to proxy and logs at debug).
Protocol matching: currently only bittorrent is supported and only for TCP. If the client can't sniff a protocol, rules with protocol won't match.
Example fragment:
"routing": {
"geoipFile": "C:/path/to/geoip.dat",
"geositeFile": "C:/path/to/geosite.dat",
"domainStrategy": "AsIs",
"rules": [
{ "domain": ["geosite:category-ads-all"], "outbound": "block" },
{ "ip": ["geoip:private"], "outbound": "direct" }
],
"final": "proxy"
}Client with the same JSON as build.ps1:
go run ./cmd/whitenoize client --config config.json -vYou can still pass server, key, and -l on the CLI after loading the file to override values from JSON.
If you have make and jq (for config.json):
make build
make run-server
make run-client
make genkey
make cleanServer:
go run ./cmd/whitenoize server <64-hex-psk> --listen 0.0.0.0:8443 -T tcp -t 30 -vClient (config file recommended):
go run ./cmd/whitenoize client --config config.json -vClient (classic positional args, no routing unless --config):
go run ./cmd/whitenoize client 127.0.0.1:8443 <64-hex-psk> --listen 127.0.0.1:1080 -T tcp -t 30 -vSwitch -T to udp for UDP transport.
Build binary:
.\build.ps1 buildRun TCP server:
# config.json: "transport": "tcp"
.\build.ps1 run-serverRun TCP client (SOCKS5):
# config.json: "transport": "tcp"
.\build.ps1 run-clientRun UDP server/client:
# config.json: "transport": "udp"
.\build.ps1 run-server
.\build.ps1 run-clientCleanup:
.\build.ps1 clean