Skip to content

Installation

Build from Source

Requires Go 1.26+.

go build -o bin/tw ./cmd/tw

Cross-Compile

make build-linux
# or manually:
GOOS=linux GOARCH=amd64 go build -o bin/tw ./cmd/tw

make build-windows
# or manually:
GOOS=windows GOARCH=amd64 go build -o bin/tw.exe ./cmd/tw

make build-darwin
# or manually:
GOOS=darwin GOARCH=amd64 go build -o bin/tw-darwin ./cmd/tw

make build-all

Makefile Targets

Target Description
make build Build for current OS
make build-linux Cross-compile for Linux amd64
make build-windows Cross-compile for Windows amd64
make build-darwin Cross-compile for macOS amd64
make build-all Build Linux, Windows, and macOS
make run Build and run locally
make clean Remove build artifacts

Version Injection

All build targets inject the version at build time via -ldflags. The version is auto-detected from the latest git tag:

make build                    # version from git describe
make build VERSION=v1.2.3     # explicit override

Release builds (GitHub Actions) inject the exact git tag (e.g. v1.2.3) into the binary.

Verify

tw --version    # prints: tw version v1.2.3
tw --help
tw status       # works on any machine, even before setup

Terraform (cloud relays only)

Terraform >= 1.0 (tested with 1.16); needed only for tw relay create with a cloud provider — the manual bring-your-own-VM path does not use it.

wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(grep -oP '(?<=UBUNTU_CODENAME=).*' /etc/os-release || lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

brew tap hashicorp/tap && brew install hashicorp/tap/terraform

choco install terraform

choco installs the community package; alternatively use the download page linked below.

Verify:

terraform -version

Other platforms and downloads: developer.hashicorp.com/terraform/install.

Shell Completion (zsh)

# add to ~/.zshrc
source <(tw completion)

Completion is dynamic: it offers stored context names and IDs, usernames, server IDs, and application names. See Status, Service & Completion.

Install as a System Service

After building, you can register tw as a system service so it starts on boot and runs in the background.

1. Copy the binary to a system path:

sudo cp bin/tw /usr/local/bin/tw
sudo chmod +x /usr/local/bin/tw

2. Install and start the service:

sudo tw service install
sudo tw service start

This creates a systemd unit at /etc/systemd/system/tw.service that runs tw dashboard with automatic restart on failure.

3. Manage the service:

sudo tw service stop        # stop the service
sudo tw service uninstall   # remove the service
sudo systemctl status tw    # check service status
sudo journalctl -u tw -f   # follow service logs

1. Place the binary in a permanent location:

mkdir C:\tw
copy bin\tw.exe C:\tw\tw.exe

2. Install and start the service (run as Administrator):

C:\tw\tw.exe service install
C:\tw\tw.exe service start

This registers a Windows service that starts automatically on boot.

3. Manage the service:

tw.exe service stop         # stop the service
tw.exe service uninstall    # remove the service

You can also manage it from the Services console (services.msc) — service name tw, display name Tunnel Whisperer.

1. Copy the binary to a system path:

sudo cp bin/tw-darwin /usr/local/bin/tw
sudo chmod +x /usr/local/bin/tw

2. Allow the binary in macOS security settings:

On first run, macOS Gatekeeper will block the unsigned binary. To allow it:

  1. Open System Settings > Privacy & Security
  2. Scroll to the Security section — you will see a message about tw being blocked
  3. Click Allow Anyway
  4. Run tw again and click Open in the confirmation dialog

Alternatively, remove the quarantine attribute directly:

sudo xattr -d com.apple.quarantine /usr/local/bin/tw

3. Install and start the service:

sudo tw service install
sudo tw service start

This creates a launchd plist at /Library/LaunchDaemons/com.tunnelwhisperer.tw.plist that keeps the service running and starts it on boot.

4. Manage the service:

sudo tw service stop        # stop the service
sudo tw service uninstall   # remove the service
sudo launchctl list | grep tw   # check if service is loaded
cat /var/log/tw.log         # view service logs
cat /var/log/tw.err.log     # view error logs

The service runs tw dashboard, which auto-starts the server or client based on your config mode. See Status, Service & Completion for details.

Config Directory

Tunnel Whisperer stores configuration in a platform-specific directory:

Platform Path
Linux /etc/tw/config/
macOS /etc/tw/config/
Windows C:\ProgramData\tw\config\

Override with the TW_CONFIG_DIR environment variable or the --config-dir flag.

Next: Pick Your Role

Every machine plays one of three roles. Continue with the section for yours:

  • Relay — you own the relay VM and admit servers
  • Server — you expose services and manage users
  • Client — you connect to a server's ports
  • Global — the role model and shared commands (contexts, status, service, proxy, dashboard)