Go 1.26 (go.mod).
- macOS:
ifconfigandroute. The client must run as root. The packaged desktop app asks for sudo. - Windows:
netsh. Run the client as administrator. - Linux:
ip(iproute2). The client does not need full root. It needscap_net_raw,cap_net_bind_service, andcap_net_admin. If those are missing it asks for a sudo password and runssetcapon its own binary.
A C compiler, plus:
- Linux:
gcc,pkg-config,libgl1-mesa-dev,xorg-dev,libxkbcommon-dev, andlibwayland-dev../build-fyne.sh linuxonly builds on a Linux host. - macOS: Xcode command line tools.
./build-fyne.sh darwinonly builds on a Mac. - Windows:
x86_64-w64-mingw32-gccorzig(zig cc -target x86_64-windows-gnu).
Linux (goreleaser builds amd64, arm64, and arm). iptables and ip6tables are required only when the WireGuard module is enabled (-wg or -allinone). The auth controller alone does not use them.
pnpm. frontend-admin/package.json pins pnpm@10.10.0.
$ ./build-fyne.sh linux # or windows|darwin|all
$ ./bin/tunnels-app-linux-amd64Windows output is bin/tunnels-app-windows-amd64.exe. macOS output is a universal bin/Tunnels.app (arm64 and amd64).
To set the Linux capabilities by hand:
$ sudo setcap 'cap_net_raw,cap_net_bind_service,cap_net_admin+eip' ./bin/tunnels-app-linux-amd64go build . in this directory names the binary main. make build-client writes ./builds/tunnels-cli instead.
$ cd ./cmd/main
$ go build .
$ ./mainThe same Linux setcap string applies to whichever client binary you run.
go build . here names the binary server. make build-server writes ./builds/tunnels-server.
There is no --config flag. -configPath defaults to ./config.json and -wgConfigPath defaults to ./wg-config.json. A bare ./server starts neither the auth controller nor WireGuard.
$ cd ./server
$ go build .
# first run: configs, self-signed cert, admin user, default server, then auth + WireGuard
$ ./server -allinone -createCert selfsign
# later runs
$ ./server -auth -wg-auth is the control plane. -wg is the WireGuard module. -createCert example.com requests a Let's Encrypt certificate instead of selfsign.
The control-plane admin UI lives in frontend-admin. The server embeds server/admin_dist.
$ ./build-ui-admin.shThat script builds frontend-admin and copies frontend-admin/dist to server/admin_dist. Restart the server after rebuilding so the embedded files are the new ones.
We accept any code, even from machine learning models as long as the code makes sense, even small spellfixing contributions. Just remember to run the linter before submitting.
The WireGuard module installs iptables and ip6tables rules when it starts: accept the WireGuard port, drop host input from the tunnel interface, forward, NAT, and TCPMSS. Nothing in this repo installs an OUTPUT RST drop.
$ ./server -showActiveRules
$ ./server -wg -showNewRules-showActiveRules prints matching rules already on the host and exits. -showNewRules needs -wg (or -allinone) and a controller the module can fetch. It prints the rules it would install and exits without applying them.
The make test* targets run ./server/... only. client, ui, wg-server, and other packages have their own tests.
# Server tests
$ make test
# Server tests, verbose
$ make test-server
# Server tests with a coverage report (coverage.html)
$ make test-coverage
# Count server tests
$ make test-count
# Server tests with the race detector
$ make test-verbose
$ go test ./server/...
$ go test ./client/... ./ui/... ./wg-server/...$ golangci-lint run --timeout=10m --config .golangci.yml
# Or use make
$ make lint
- Windows: administrator
- macOS: root (sudo)
- Linux:
sudo setcap 'cap_net_raw,cap_net_bind_service,cap_net_admin+eip' <client-binary>
Goreleaser builds two binaries. The desktop app is built separately with Fyne.
| Binary | Source | Notes |
|---|---|---|
tunnels-cli |
./cmd/main |
Headless client. Linux, Windows, and macOS (amd64 and arm64). |
tunnels-server |
./server |
Control plane. Linux only (amd64, arm64, arm). |
tunnels-app |
./cmd/fyne |
Fyne desktop app. Linux amd64, Windows amd64, and universal macOS. GitHub Actions builds it. Goreleaser does not. |
- Snapshot binaries, no GitHub release:
./releaser-build-snapshot.sh(goreleaser build --snapshot) - Local snapshot release:
make release(goreleaser release --snapshot) - Publish:
./releaser-build-release.sh(goreleaser release, requiresGITHUB_TOKEN)
# Build using make
$ make build # ./builds/tunnels-cli and ./builds/tunnels-server
$ make build-server # ./builds/tunnels-server
$ make build-client # ./builds/tunnels-cli
$ make build-app # Linux desktop only, via ./build-fyne.sh linux
# Test before building
$ make pre-commit # go mod tidy, server tests, and lint
$ make ci # server tests and lintNative GUI in the same binary as the client (./cmd/fyne). The window
calls client functions directly (no HTTP hop for UI actions).
./build-fyne.sh linux # or windows|darwin|allPull requests and pushes to main, master, and develop build all three in the Tests workflow. A v* tag attaches the same three packages to the draft release. Actions → Build Desktop Client rebuilds them by hand.
These are the real MVPs:
- n00bady: creator of bluam https://github.com/n00bady/bluam
- 0xMALVEE: for major contributions to the front-end
- keyb1nd_'s twitch chat for the backseat debugging and support!
- comahacks for security reviews
- klauspost for development advice