$ tunr share --port 3000

  🚀 Tunnel active:  https://abc1x2y3.tunr.sh

  Ctrl+C to stop...

What is tunr?

tunr exposes your local development server to the internet in under 3 seconds — with automatic HTTPS and zero configuration. Browser WebSockets (e.g. Next.js / Vite HMR) are bridged over the same control channel as HTTP when you use the tunr relay + CLI; see Troubleshooting for Next.js allowedDevOrigins and edge cases.

It's a developer-first alternative to ngrok and Cloudflare Tunnel, built in Go as a single static binary that runs on macOS, Linux, and Windows (ARM64 included).

Install

# macOS (Homebrew) — recommended
brew install ahmetvural79/tap/tunr

# Linux / macOS (one-liner)
curl -sSL https://tunr.sh/install | sh

# npm (Node.js projects)
npx tunr@latest share --port 3000

# Docker
docker run --rm -it --network host ghcr.io/ahmetvural79/tunr:v0.4.0 share --port 3000

# Python SDK
pip install tunr

# Node.js SDK
npm install @tunr/cli

# Build from source
git clone https://github.com/ahmetvural79/tunr.git
cd tunr
go build -o tunr ./cmd/tunr

Requires Go 1.22+ to build from source.

Free forever. The CLI and all core features are open source. Cloud features (custom subdomains, team dashboards) require a tunr.sh account.

Quick Start

# 1. Start your dev server
npm run dev  # → http://localhost:3000

# 2. Share it
tunr share --port 3000

# That's it. You get:
#   🚀 https://abc1x2y3.tunr.sh

Commands

# Share a local port (foreground)
tunr share --port 3000
tunr share --port 8080 --subdomain myapp  # custom subdomain (Pro)

# Route paths to different ports
tunr share --route /=3000 --route /api=8080

# Password protection & expiration
tunr share -p 8080 --password "secret" --ttl 30m

# Vibecoder demo superpowers
tunr share -p 3000 --demo --freeze --inject-widget
tunr share -p 3000 --auto-login "Cookie: session=demo"

# Secure & debug (Pinggy-powered)
tunr share -p 3000 --qr                     # QR code for mobile scanning
tunr share -p 3000 --auth-token "my-secret" # Bearer token access control
tunr share -p 3000 --allow-ip "1.2.3.0/24"  # IP whitelist (CIDR)
tunr share -p 3000 --header-add "X-Debug: 1"
tunr share -p 3000 --x-forwarded-for --original-url
tunr share -p 3000 --cors-origin "https://myapp.com"

# Custom domain
tunr share -p 3000 --domain demo.client.com

# Machine-readable output for CI/CD
tunr share -p 3000 --json

# Daemon mode (runs in background)
tunr start --port 3000
tunr stop
tunr status

# Inspect & debug
tunr open           # Open HTTP inspector dashboard
tunr logs           # Stream request logs
tunr logs --follow  # Real-time log stream
tunr replay <id>    # Re-send a captured request

# System
tunr doctor         # System health check
tunr version
tunr update         # Self-update to latest release
tunr uninstall      # Remove tunr from your system

# Auth
tunr login
tunr logout

# Config
tunr config show
tunr config init    # Creates .tunr.json in cwd

# AI / MCP
tunr mcp            # Start MCP server (Claude, Cursor, Windsurf)

# TCP tunnels
tunr tcp --port 5432
tunr tcp --port 22 --qr
tunr tcp --port 6379 --allow-ip 10.0.0.0/8 --region ams

# UDP tunnels (v0.4.0)
tunr udp --port 53                          # DNS server
tunr udp --port 27015 --region ams           # Game server

# TLS tunnels — end-to-end encryption (v0.4.0)
tunr tls --port 8443                         # Zero-trust: relay can't read traffic

# Multi-tunnel from config (v0.4.0)
tunr up                                      # Start all tunnels from .tunr.json
tunr down                                    # Stop all daemon tunnels

# System service (v0.4.0)
tunr service install --port 3000             # Auto-start on boot
tunr service status
tunr service uninstall

# Corporate proxy (v0.4.0)
tunr share -p 3000 --proxy http://proxy:8080

Full CLI Reference

Troubleshooting

Next.js: blank page over tunr share (port 3000)

Next.js dev blocks cross-origin access to dev-only endpoints unless you allow your tunnel host.

1. Add allowedDevOrigins in next.config.js / next.config.ts (see Next.js docs — allowedDevOrigins):

/** @type {import('next').NextConfig} */
const nextConfig = {
  allowedDevOrigins: ['*.tunr.sh', 'tunr.sh'],
}
module.exports = nextConfig

Use your real tunnel domain pattern if you use a custom subdomain or self-hosted edge.

2. For a stable public demo without HMR, prefer a production build:

npm run build && npm run start
tunr share --port 3000

“Chrome offline” / “This site can’t be reached” / dinosaur page when using --inject-widget

That page is the browser’s network error UI — the main HTML document never completed successfully (not the widget script failing in isolation).

WebSocket / HMR over the public URL

The tunr edge relay upgrades the public wss:// connection and streams frames to your CLI, which opens a local ws:// connection to your dev server. That gives you end-to-end HMR-style WebSockets without a separate tunnel product.

Still required for some frameworks: Next.js dev server may block cross-origin requests until you add your tunnel host to allowedDevOrigins in next.config (see above). If HMR still fails, fall back to next build && next start or test HMR on localhost.

Relay / edge: WebSocket bridging is implemented on the tunr relay; self-hosted edges must run a relay build that includes this feature.

Optional: for relay origin checks on the browser WebSocket handshake, set TUNR_WS_EXTRA_ALLOWED_ORIGIN_SUFFIXES (comma-separated hostname suffixes).

Vibecoder Demo Features

tunr ships with four proxy-level superpowers designed for freelancers and agencies demoing to clients:

❄️ Freeze Mode (--freeze)

If your local server crashes mid-demo, tunr serves the last successful response from memory. Your client never sees a broken page.

tunr share --port 3000 --freeze

🛡️ Read-Only Demo Mode (--demo)

Intercept destructive HTTP methods (POST, PUT, DELETE) at the proxy layer. The client can click "Place Order" — nothing actually writes to your database.

tunr share --port 3000 --demo

💬 Feedback Widget Injection (--inject-widget)

Injects a transparent overlay widget into every HTML page served through the tunnel. Clients can pin visual feedback and errors are forwarded to your terminal in real-time. Like Marker.io, but free and built-in.

tunr share --port 3000 --inject-widget

🔑 Auto-Login Bypass (--auto-login)

Inject an auth cookie so your client lands on the demo account automatically — no signup, no email verification.

tunr share --port 3000 --auto-login "Cookie: session=demo-token"

Combine them all for the ultimate demo setup:

tunr share --port 3000 --demo --freeze --inject-widget

Advanced Tunnel Features

🔒 Password Protected Tunnels (--password)

Add Basic Authentication to your public URL instantly without writing any code. Keep your development environments secure from unauthorized access while sharing with clients or third parties.

tunr share -p 8080 --password "secret"
# Or provide a specific username
tunr share -p 8080 --password "client:secret"

⏳ Auto-Expiring Tunnels (--ttl)

Forget to stop a tunnel exposing your local machine? Use a Time-To-Live (TTL). Once the duration expires, the tunnel daemon safely terminates the connection and shuts down the proxy.

tunr share -p 3000 --ttl 1h30m

🔀 Path Routing (--route)

Map different incoming URL paths to different upstream ports on your machine. This is perfect for testing microservices or serving your frontend and API from a single public proxy domain.

# Anything to / goes to 3000, /api goes to 8080
tunr share --route /=3000 --route /api=8080

🌐 Multi-Region Routing (--region)

Select a preferred relay region for lower latency to specific geographic areas.

# European relay (Amsterdam)
tunr share --port 3000 --region ams

# US West relay (Seattle)
tunr share --port 3000 --region sea

# Asia relay (Singapore)
tunr share --port 3000 --region sin

# TCP tunnel with region selection
tunr tcp --port 5432 --region ams

Currently available regions:

• ams — Amsterdam, EU (Europe)
• sea — Seattle, US West (Americas)
• sin — Singapore (Asia-Pacific)

🔌 TCP Tunnels (tunr tcp)

Expose raw TCP services — databases, SSH, Redis, game servers — through secure tunnels without HTTP overhead.

# PostgreSQL
tunr tcp --port 5432

# SSH with QR code for mobile sharing
tunr tcp --port 22 --qr

# Redis with IP restriction
tunr tcp --port 6379 --allow-ip 10.0.0.0/8

# MySQL in specific region
tunr tcp --port 3306 --region ams

TCP tunnels forward raw bytes over the same WebSocket control channel — no HTTP parsing on the relay side. Perfect for any TCP-based service.

Programming APIs

Python SDK

from tunr import TunrClient, TunnelOptions

client = TunrClient()

# Simple tunnel
tunnel = client.share(port=3000)
print(tunnel.public_url)

# TCP / UDP / TLS tunnels (v0.4.0)
db_tunnel = client.tcp(port=5432)
dns_tunnel = client.udp(port=53)
tls_tunnel = client.tls(port=8443)

# With options
opts = TunnelOptions(
    subdomain="myapp",
    password="demo123",
    allow_ips=["10.0.0.0/8"],
    freeze=True,
    inject_widget=True,
    proxy="http://proxy:8080",
    ttl="2h",
)
tunnel = client.share(port=8080, opts=opts)

# Inspect requests
requests = client.get_requests(tunnel.subdomain)

# Replay a request
client.replay_request(tunnel.subdomain, requests[0]['id'], port=3000)

# Observability (v0.4.0)
metrics = client.get_metrics()     # Prometheus format
health = client.health_check()     # {"status": "ok"}

# Clean up
tunnel.close()

Node.js SDK

import { TunrClient } from '@tunr/cli'

const client = new TunrClient()

// Simple tunnel
const tunnel = await client.share(3000)
console.log(tunnel.publicUrl)

// TCP / UDP / TLS tunnels (v0.4.0)
const dbTunnel = await client.tcp(5432)
const dnsTunnel = await client.udp(53)
const tlsTunnel = await client.tls(8443)

// With options
const appTunnel = await client.share(8080, {
  subdomain: 'myapp',
  password: 'demo123',
  allowIps: ['10.0.0.0/8'],
  freeze: true,
  injectWidget: true,
  proxy: 'http://proxy:8080',
  ttl: '2h',
})

// Event-based lifecycle
tunnel.on('ready', () => console.log('Tunnel live'))
tunnel.on('error', (err) => console.error(err))
tunnel.on('exit', () => console.log('Tunnel closed'))

// Inspect & replay
const requests = await client.getRequests('myapp')
await client.replayRequest('myapp', requests[0].id, 3000)

// Observability (v0.4.0)
const metrics = await client.getMetrics()    // Prometheus text
const health = await client.healthCheck()    // {status: "ok"}

// Clean up
await tunnel.close()

Security & Debugging (Pinggy-Inspired)

tunr now includes all the enterprise-grade tunnel security and debugging features from Pinggy, built natively:

📱 QR Code Tunnel Sharing (--qr)

Instantly generate a scannable QR code for your tunnel URL. Perfect for mobile testing and sharing URLs with clients.

🔑 Bearer Token Access (--auth-token)

Protect your tunnel with a simple API key/token. Requests must include Authorization: Bearer <token> or pass ?token=<token> in the query string.

tunr share -p 3000 --auth-token "my-super-secret-key"

🛡️ IP Whitelisting (--allow-ip)

Restrict tunnel access to specific IP ranges using CIDR notation. Only whitelisted IPs can reach your local server.

# Only allow your office network
tunr share -p 3000 --allow-ip "203.0.113.0/24"

# Multiple networks
tunr share -p 3000 --allow-ip "10.0.0.0/8,172.16.0.0/12"

🔧 Live Header Modification

Add, replace, or remove HTTP headers on the fly before they reach your local server.

# Inject a debug header
tunr share -p 3000 --header-add "X-Debug: true"

# Replace the Host header for internal routing
tunr share -p 3000 --header-replace "Host: internal.local"

# Remove fingerprinting headers
tunr share -p 3000 --header-remove "X-Powered-By"

🌐 Forwarded Headers (--x-forwarded-for, --original-url)

Inject standard proxy headers so your application knows the original client IP and URL.

tunr share -p 3000 --x-forwarded-for --original-url

• X-Forwarded-For — the real client IP address
• X-Original-URL — the full public tunnel URL that was requested

🔓 CORS Preflight (--cors-origin)

Allow browser CORS preflight requests from specific origins without server-side changes.

tunr share -p 3000 --cors-origin "https://myapp.com"

HTTP Inspector

tunr ships with a built-in HTTP request inspector (like ngrok's web UI, but local).

tunr open  # opens http://localhost:19842

Features:

• Live request/response stream
• Headers, body, timing
• One-click replay
• Export as curl command

MCP Integration (Claude, Cursor, Windsurf)

tunr implements the Model Context Protocol — AI agents can manage tunnels directly.

Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tunr": {
      "command": "tunr",
      "args": ["mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "tunr": { "command": "tunr", "args": ["mcp"] }
  }
}

Configuration (.tunr.json)

Create a workspace config file:

{
  "$schema": "https://tunr.sh/schema/.tunr.schema.json",
  "port": 3000,
  "inspectorEnabled": true,
  "dashboardPort": 19842,
  "mcp": { "enabled": true }
}

Architecture

tunr is a single Go binary that:

1. Starts a local HTTPS proxy with an embedded inspector
2. Opens a WebSocket connection to the tunr relay (edge server)
3. The relay issues a *.tunr.sh subdomain and forwards traffic
4. HTTPS terminates at the relay; CLI ↔ dev-server traffic runs over the same WebSocket stream

Browser → relay.tunr.sh → [WebSocket] → tunr binary → localhost:PORT

Protocol support: tunr tunnels HTTP/HTTPS + WebSocket, TCP, UDP, and TLS (end-to-end encrypted) traffic. UDP datagrams are forwarded through the WebSocket control channel. TLS tunnels use SNI-based routing for zero-knowledge passthrough.

Multi-region: The relay supports region selection via the --region flag. Currently available regions: ams (Amsterdam, EU), sea (Seattle, US West), sin (Singapore, Asia). The balancer infrastructure (relay/internal/relay/balancer.go) manages cross-region routing metadata.

Wildcards: The relay is configured with *.tunr.sh wildcard routing through Fly.io / Caddy; wildcard domain support for custom domains is available.

Self-Hosting: The relay can be self-hosted using the included docker-compose.yml (Relay + Caddy + Postgres). See docs/SELF_HOSTING.md for the complete guide.

Docker: The CLI is available as a ~15MB Alpine Docker image. Build with docker build -t tunr . or pull from ghcr.io/ahmetvural79/tunr.

Observability: The CLI exposes Prometheus metrics at /metrics and K8s-ready health probes at /healthz and /readyz on the inspector port (19842).

Security

tunr takes security seriously for an open-source CLI tool:

• Auth tokens stored in OS keychain (not plaintext files)
• All relay traffic over TLS 1.3
• No telemetry, no analytics, no phone-home by default
• Supply chain integrity via go mod verify and govulncheck in CI

Found a vulnerability? Do not open a public issue. See SECURITY.md.

How tunr Compares

tunr vs ngrok

Both tools share localhost, but tunr focuses on developer experience and vibecoding workflows:

Compare Pinggy vs ngrok

tunr vs Cloudflare Tunnel

Compare Pinggy vs Cloudflare Tunnel

tunr vs LocalXpose

Compare Pinggy vs LocalXpose

tunr vs LocalTunnel

LocalTunnel is free but minimal — tunr adds a full feature set on top of the same zero-cost model:

Compare Pinggy vs LocalTunnel

Roadmap

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Make your changes
4. Ensure CI passes (go test ./... + golangci-lint run)
5. Open a pull request

License

PolyForm Shield 1.0.0 — see LICENSE.

You are free to use, modify, and distribute this software. The only restriction is that you may not use it to build a competing product or service. See the license for full terms.