WireRift

Tear a rift through the wire. Expose localhost to the world.

Open-source, zero-dependency tunnel server and client written in Go. Expose any local service to the internet through a secure tunnel — like ngrok, but fully self-hosted.

---

Table of Contents

• Features
• Installation
• Quick Start
• Server Reference
• Client Reference
• Dashboard
• Configuration
• Access Control
• Traffic Inspector
• Docker
• API Reference
• Architecture
• Benchmarks
• Development
• License

---

Features

Category	Features
Tunneling	HTTP tunnels, TCP tunnels, WebSocket passthrough, stream multiplexing, flow control
Security	Let's Encrypt ACME, self-signed TLS, Basic Auth, IP whitelist (CIDR), PIN protection, HMAC cookies, CSP nonce
Monitoring	Web dashboard (dark/light theme), traffic inspector, request replay, cURL export, JSON highlighting
Operations	Health check (/healthz), X-Request-ID tracing, graceful shutdown, auto-reconnect, rate limiting
Config	YAML and JSON config files, CLI flags, environment variables, user-defined tokens
Platform	Zero dependencies, single binary, Linux/macOS/Windows/FreeBSD, amd64/arm64

---

Installation

Download Binary (Recommended)

Download the latest release for your platform from GitHub Releases.

Linux (amd64)

curl -Lo wirerift-server https://github.com/WireRift/WireRift/releases/latest/download/wirerift-server-linux-amd64
curl -Lo wirerift https://github.com/WireRift/WireRift/releases/latest/download/wirerift-linux-amd64
chmod +x wirerift-server wirerift
sudo mv wirerift-server wirerift /usr/local/bin/

Linux (arm64 / Raspberry Pi)

curl -Lo wirerift-server https://github.com/WireRift/WireRift/releases/latest/download/wirerift-server-linux-arm64
curl -Lo wirerift https://github.com/WireRift/WireRift/releases/latest/download/wirerift-linux-arm64
chmod +x wirerift-server wirerift
sudo mv wirerift-server wirerift /usr/local/bin/

macOS (Apple Silicon / M1+)

curl -Lo wirerift-server https://github.com/WireRift/WireRift/releases/latest/download/wirerift-server-darwin-arm64
curl -Lo wirerift https://github.com/WireRift/WireRift/releases/latest/download/wirerift-darwin-arm64
chmod +x wirerift-server wirerift
sudo mv wirerift-server wirerift /usr/local/bin/

macOS (Intel)

curl -Lo wirerift-server https://github.com/WireRift/WireRift/releases/latest/download/wirerift-server-darwin-amd64
curl -Lo wirerift https://github.com/WireRift/WireRift/releases/latest/download/wirerift-darwin-amd64
chmod +x wirerift-server wirerift
sudo mv wirerift-server wirerift /usr/local/bin/

Windows (amd64)

Download from Releases: - wirerift-server-windows-amd64.exe - wirerift-windows-amd64.exe

Or via PowerShell:

Invoke-WebRequest -Uri "https://github.com/WireRift/WireRift/releases/latest/download/wirerift-server-windows-amd64.exe" -OutFile "wirerift-server.exe"
Invoke-WebRequest -Uri "https://github.com/WireRift/WireRift/releases/latest/download/wirerift-windows-amd64.exe" -OutFile "wirerift.exe"

Windows (arm64)

Download from Releases: - wirerift-server-windows-arm64.exe - wirerift-windows-arm64.exe

Build from Source

Requires Go 1.23+:

git clone https://github.com/WireRift/WireRift.git
cd WireRift
go build -o wirerift-server ./cmd/wirerift-server
go build -o wirerift ./cmd/wirerift

Or with Make:

make build          # builds both server and client to bin/
make test           # run all tests
make test-race      # run tests with race detector
make fuzz           # run fuzz tests
make bench          # run benchmarks
make docker         # build Docker image
make release        # cross-compile all platforms to dist/

---

Quick Start

1. Start the Server

# With a fixed token (recommended)
wirerift-server --token my-secret-token

# Or let the server generate a random token (shown on startup)
wirerift-server

The server prints a connection banner:

╔══════════════════════════════════════════════╗
║              WireRift Server                 ║
╠══════════════════════════════════════════════╣
  Control:   :4443
  HTTP:      :80
  Dashboard: http://localhost:4040
  Domain:    wirerift.com
╠══════════════════════════════════════════════╣
  Token (-token flag):
  my-secret-token
╠══════════════════════════════════════════════╣
  Quick start:
  wirerift http 8080 -server localhost:4443 -token my-secret-token
╚══════════════════════════════════════════════╝

2. Connect a Client

# Expose local port 8080 via HTTP tunnel
wirerift http 8080 --token my-secret-token

# With custom subdomain
wirerift http 8080 myapp --token my-secret-token

# TCP tunnel (e.g., PostgreSQL)
wirerift tcp 5432 --token my-secret-token

# Serve static files
wirerift serve ./dist --token my-secret-token

3. Open Dashboard

Visit http://localhost:4040 and enter your token to see: - Active tunnels and sessions - Live traffic inspector - Request replay and cURL export

---

Server Reference

wirerift-server [options]

Options:
  --token string        Auth token (default: auto-generated random)
  --domain string       Base domain for tunnels (default: wirerift.com)
  --control string      Control plane address (default: :4443)
  --http string         HTTP edge address (default: :80)
  --https string        HTTPS edge address (default: :443)
  --dashboard-port int  Dashboard port (default: 4040)
  --tcp-ports string    TCP tunnel port range (default: 20000-29999)
  --auto-cert           Generate self-signed certificates
  --cert-dir string     Certificate directory (default: certs)
  --acme-email string   Email for Let's Encrypt (enables ACME)
  --acme-staging        Use Let's Encrypt staging server
  --v                   Verbose logging
  --json                JSON log format
  --version             Show version

Environment Variables:
  WIRERIFT_TOKEN         Auth token (flag takes precedence)
  WIRERIFT_DOMAIN        Base domain
  WIRERIFT_CONTROL_ADDR  Control plane address
  WIRERIFT_HTTP_ADDR     HTTP edge address

Examples

# Development (localhost, self-signed TLS)
wirerift-server --token dev123 --auto-cert

# Production (Let's Encrypt)
wirerift-server --domain mytunnel.com --acme-email admin@mytunnel.com --token prod-secret

# Custom ports
wirerift-server --control :8443 --http :8080 --dashboard-port 9090 --token mytoken

# Via environment
export WIRERIFT_TOKEN=my-secret
export WIRERIFT_DOMAIN=tunnel.example.com
wirerift-server --acme-email admin@example.com

---

Client Reference

wirerift <command> [options]

Commands:
  http <port> [subdomain]   Create an HTTP tunnel
  tcp <port>                Create a TCP tunnel
  serve <directory>         Serve static files via HTTP tunnel
  start [config-file]       Start tunnels from config file
  list                      List active tunnels
  config                    Show/edit configuration
  version                   Show version info

Common Options (all commands):
  --server string     Server address (default: localhost:4443)
  --token string      Auth token (or set WIRERIFT_TOKEN env var)
  --v                 Verbose output

HTTP/Serve Options:
  --subdomain string  Requested subdomain
  --auth string       Basic auth "user:password"
  --pin string        PIN protection
  --whitelist string  IP whitelist "ip1,ip2,cidr"
  --header string     Response headers "Key:Val,Key:Val"
  --inspect           Enable traffic inspector

Note: Both --flag and -flag syntax work. Flags can appear before or after positional arguments.

Examples

# Simple HTTP tunnel
wirerift http 3000 --token mytoken

# HTTP tunnel with all features
wirerift http 8080 myapp \
  --token mytoken \
  --auth "admin:pass" \
  --pin 1234 \
  --whitelist "10.0.0.0/8,192.168.1.0/24" \
  --header "X-Frame-Options:DENY,X-Robots-Tag:noindex" \
  --inspect

# TCP tunnel (database, game server, SSH, etc.)
wirerift tcp 5432 --token mytoken
wirerift tcp 25565 --token mytoken   # Minecraft
wirerift tcp 22 --token mytoken      # SSH

# Serve a directory
wirerift serve ./build --subdomain mysite --token mytoken

# Start from config file
wirerift start wirerift.yaml
wirerift start wirerift.json

---

Dashboard

The built-in dashboard at http://localhost:4040 provides:

• Dark/Light theme — toggle with button or persisted preference
• Tabbed navigation — Tunnels / Sessions / Inspector with live count badges
• Keyboard shortcuts — R refresh, T tunnels, S sessions, I inspector
• Tunnel management — copy URL to clipboard, status indicators
• Traffic Inspector — real-time request/response log with:
• Method badges (GET=green, POST=blue, PUT=amber, DELETE=red)
• Status code coloring (2xx=green, 4xx=red, 5xx=red)
• Expandable request/response headers
• JSON syntax highlighting
• cURL command export
• Request replay
• Animated counters — bytes and uptime update smoothly
• Search/filter — filter across all tables
• Toast notifications — action feedback

---

Configuration

YAML Format

# wirerift.yaml
server: localhost:4443
token: my-secret-token

tunnels:
  - type: http
    local_port: 8080
    subdomain: myapp

  - type: http
    local_port: 9090
    subdomain: admin
    auth: "admin:secret"
    pin: "mysecret"
    whitelist: "10.0.0.0/8"
    inspect: true
    headers: "X-Robots-Tag:noindex"

  - type: tcp
    local_port: 5432

JSON Format

{
  "server": "localhost:4443",
  "token": "my-secret-token",
  "tunnels": [
    {
      "type": "http",
      "local_port": 8080,
      "subdomain": "myapp"
    },
    {
      "type": "http",
      "local_port": 9090,
      "subdomain": "admin",
      "auth": "admin:secret",
      "pin": "mysecret",
      "whitelist": "10.0.0.0/8",
      "inspect": true,
      "headers": "X-Robots-Tag:noindex"
    },
    {
      "type": "tcp",
      "local_port": 5432
    }
  ]
}

wirerift start wirerift.yaml    # YAML
wirerift start wirerift.json    # JSON (auto-fallback if .yaml not found)
wirerift config init            # generate sample wirerift.yaml

Token Configuration

Token is resolved in order: --token flag > WIRERIFT_TOKEN env > auto-generated.

# Flag (highest priority)
wirerift-server --token my-secret
wirerift http 8080 --token my-secret

# Environment variable
export WIRERIFT_TOKEN=my-secret
wirerift-server              # reads from env
wirerift http 8080           # reads from env

# Auto-generated (shown on server startup banner)
wirerift-server              # generates random token, prints to stderr

---

Access Control

Basic Auth

wirerift http 8080 --auth "user:password"

Returns 401 Unauthorized with WWW-Authenticate: Basic header. Uses constant-time comparison.

IP Whitelist

wirerift http 8080 --whitelist "203.0.113.50,10.0.0.0/8,192.168.0.0/16"

Supports IPv4, IPv6, CIDR notation. HTTP returns 403 Forbidden, TCP silently drops.

PIN Protection

wirerift http 8080 --pin mysecret

Three ways to provide PIN: | Method | Example | |--------|---------| | Browser form | Dark-themed PIN page, sets HttpOnly HMAC cookie (24h) | | HTTP header | X-WireRift-PIN: mysecret | | Query parameter | https://myapp.tunnel.com/?pin=mysecret (redirects to clean URL) |

---

Traffic Inspector

Enable inspection on any tunnel:

wirerift http 8080 --inspect --token mytoken

Dashboard shows live traffic at http://localhost:4040 (Inspector tab): - Method, path, status, duration, client IP - Expandable request/response headers - JSON body with syntax highlighting - Replay — resend any captured request - cURL export — copy request as curl command

API Access

# List captured requests
curl -H "Authorization: Bearer TOKEN" http://localhost:4040/api/requests?limit=50

# Filter by tunnel
curl -H "Authorization: Bearer TOKEN" http://localhost:4040/api/requests?tunnel_id=tun_abc

# Replay a request
curl -X POST -H "Authorization: Bearer TOKEN" http://localhost:4040/api/requests/req_xyz/replay

---

Docker

Docker Run

docker build -t wirerift-server .

docker run -d \
  -p 4443:4443 \
  -p 80:80 \
  -p 443:443 \
  -p 4040:4040 \
  -e WIRERIFT_TOKEN=my-secret \
  -v wirerift-certs:/data/certs \
  wirerift-server \
  -domain mytunnel.com -auto-cert

Docker Compose

docker compose up -d

The included docker-compose.yml