# STUNL - Complete Reference

> Secure tunnels to localhost. Expose local servers to the internet instantly.

STUNL is a tunneling service that exposes local servers to the internet. Key differentiators from ngrok:
- Multi-port tunnels (one URL → multiple services)
- Native TCP and UDP support
- Multiple domain choices
- Team bandwidth pooling
- Transparent pricing ($10/mo Pro)

## Quick Reference

```bash
# HTTP tunnel (default)
stunl -port 3000

# TCP tunnel
stunl -port 5432 -protocol tcp

# UDP tunnel
stunl -port 53 -protocol udp

# Multi-port
stunl -ports "web:3000:http,api:8080:http,db:5432:tcp"

# Password protected
stunl -port 3000 -password mypass

# OAuth protected
stunl -port 3000 -oauth github -oauth-github-org mycompany

# End-to-end encrypted
stunl -port 3000 -e2e

# Custom subdomain
stunl -port 3000 -id myapp
```

---

## Table of Contents

1. [Installation](#installation)
2. [Basic Usage](#basic-usage)
3. [Protocol Types](#protocol-types)
4. [Multi-Port Tunnels](#multi-port-tunnels)
5. [Security Features](#security-features)
6. [Custom Domains](#custom-domains)
7. [File & Terminal Sharing](#file--terminal-sharing)
8. [Configuration](#configuration)
9. [CLI Reference](#cli-reference)
10. [Pricing & Limits](#pricing--limits)
11. [Troubleshooting](#troubleshooting)

---

## Installation

### macOS (Homebrew) - Recommended
```bash
brew install stunl/tap/stunl
```

### Linux / macOS (Binary)
```bash
# Auto-detect platform
curl -fsSL https://github.com/stunl/cli/releases/latest/download/stunl_$(uname -s)_$(uname -m).tar.gz | tar xz
sudo mv stunl /usr/local/bin/

# Specific platforms:
# Linux AMD64: stunl_Linux_x86_64.tar.gz
# Linux ARM64: stunl_Linux_arm64.tar.gz
# macOS Intel: stunl_Darwin_x86_64.tar.gz
# macOS Apple Silicon: stunl_Darwin_arm64.tar.gz
```

### Windows
Download from: https://github.com/stunl/cli/releases/latest
- `stunl_Windows_x86_64.zip` for 64-bit Windows

### Go Install
```bash
go install github.com/stunl/stunl/cmd/stunl@latest
```

### Verify Installation
```bash
stunl -version
```

---

## Basic Usage

### Expose a Web Server
```bash
# Start your local server
npm run dev  # runs on localhost:3000

# In another terminal, create tunnel
stunl -port 3000

# Output:
#   ● STUNL
#   ╭── ◎ ── HTTP lazy-koala-x7k9
#   │   HTTPS https://lazy-koala-x7k9.stunl.io
#   │   HTTP  http://lazy-koala-x7k9.stunl.io
#   │   Local localhost:3000
```

### Custom Subdomain (Pro Required)
```bash
stunl -port 3000 -id myapp
# Output: https://myapp.stunl.io → localhost:3000
```

### Different Local Host
```bash
# Tunnel to a different machine on your network
stunl -port 3000 -host 192.168.1.100
```

---

## Protocol Types

### HTTP/HTTPS (Default)
Best for: Web applications, REST APIs, webhooks

```bash
stunl -port 3000
# or explicitly:
stunl -port 3000 -protocol http
```

Features:
- Automatic HTTPS (Let's Encrypt)
- WebSocket support (automatic)
- HTTP/2 support
- Request inspection (coming soon)

### TCP
Best for: Databases, SSH, game servers, custom protocols

```bash
stunl -port 5432 -protocol tcp
# Output: tcp://swift-fox-a1b2.stunl.io:10042 → localhost:5432
```

Connection example (PostgreSQL):
```bash
psql -h swift-fox-a1b2.stunl.io -p 10042 -U postgres
```

Reserved ports (Pro):
```bash
# Always get port 10042
stunl -port 5432 -protocol tcp -public-port 10042
```

### UDP
Best for: DNS servers, game servers, VoIP, streaming

```bash
stunl -port 53 -protocol udp
# Output: udp://brave-eagle-c3d4.stunl.io:10043 → localhost:53
```

### WebSocket
WebSocket is automatically supported through HTTP tunnels. No special flag needed.

```bash
# Your WebSocket server on port 8080
stunl -port 8080
# ws:// and wss:// work automatically
```

---

## Multi-Port Tunnels

Expose multiple services on one hostname. Perfect for full-stack applications.

### Basic Syntax
```bash
stunl -ports "name:port:protocol,name:port:protocol,..."
```

### Example: Full-Stack App
```bash
stunl -ports "web:3000:http,api:8080:http,db:5432:tcp" -id myapp
```
Output:
- `https://myapp.stunl.io/web` → localhost:3000
- `https://myapp.stunl.io/api` → localhost:8080
- `tcp://myapp.stunl.io:10042` → localhost:5432

### Routing Strategies

| Strategy | Description | Example URL |
|----------|-------------|-------------|
| `path` (default) | Route by URL path | `/api`, `/web` |
| `subdomain` | Route by subdomain | `api.myapp.stunl.io` |
| `header` | Route by HTTP header | `X-Service: api` |
| `mixed` | Combine strategies | Various |
| `round_robin` | Load balance | Any URL |
| `least_connections` | Load balance | Any URL |

```bash
# Subdomain-based routing
stunl -ports "web:3000:http,api:8080:http" -routing-strategy subdomain -id myapp
# web.myapp.stunl.io → localhost:3000
# api.myapp.stunl.io → localhost:8080
```

### Advanced Routing Rules
Create a JSON file for complex routing:

```json
{
  "rules": [
    {"path": "/api/*", "target": "api"},
    {"path": "/admin/*", "target": "admin", "auth": "github"},
    {"path": "/*", "target": "web"}
  ]
}
```

```bash
stunl -ports "web:3000:http,api:8080:http,admin:9000:http" \
      -routing-rules rules.json
```

---

## Security Features

### Password Protection
```bash
stunl -port 3000 -password secretpass
```
Visitors see HTTP Basic Auth prompt. Works with all HTTP clients.

### OAuth Authentication

#### GitHub
```bash
# Allow any GitHub user
stunl -port 3000 -oauth github

# Restrict to organization members
stunl -port 3000 -oauth github -oauth-github-org mycompany

# Restrict to specific team
stunl -port 3000 -oauth github -oauth-github-team mycompany/developers
```

#### Google
```bash
# Allow any Google user
stunl -port 3000 -oauth google

# Restrict to email domain
stunl -port 3000 -oauth google -oauth-allow-domain example.com
```

#### Microsoft
```bash
stunl -port 3000 -oauth microsoft
```

#### Email Restrictions
```bash
# Specific emails only
stunl -port 3000 -oauth github -oauth-allow-email "alice@example.com,bob@example.com"

# Domain restriction
stunl -port 3000 -oauth google -oauth-allow-domain "example.com,mycompany.org"
```

### End-to-End Encryption
Server cannot decrypt traffic. Maximum privacy.

```bash
# Auto-generated certificate
stunl -port 3000 -e2e

# Your own certificate
stunl -port 3000 -e2e -e2e-cert server.crt -e2e-key server.key
```

With E2E:
- Traffic encrypted client-to-client
- STUNL servers only see encrypted bytes
- Perfect for sensitive data

---

## Custom Domains

### Using Allowed Domains (Pro)
Pro users can use these domains:
- `stunl.io` (default)
- `localshare.io`
- `pentest.run`
- `cheburashka.net`
- `unixfreak.net` / `unixfreak.org`
- `unixsysadmin.org`
- `ihatethe.net`

```bash
stunl -port 3000 -id myapp -domain localshare.io
# Output: https://myapp.localshare.io
```

---

## File & Terminal Sharing

### File Sharing
```bash
# Share a file
stunl share ./document.pdf

# With password
stunl share ./document.pdf -password secret

# With expiration
stunl share ./document.pdf -expires 24h

# One-time download
stunl share ./document.pdf -once
```

Output: Shareable URL like `https://files.stunl.io/abc123`

### Terminal Sharing
Share your terminal session for pair programming.

```bash
# Read-only (viewers can watch)
stunl term

# Interactive (viewers can type)
stunl term -i

# With SSH access
stunl term -ssh
```

Output: URL and optional SSH command for viewers.

---

## Configuration

### Config File
Location: `~/.stunl/config.yaml`

```yaml
# API key for authentication
api_key: st_live_xxxxxxxxxxxxx

# Server address (rarely needed)
server: grpc.stunl.com

# Default port
port: 3000

# Default subdomain
id: myapp
```

### Environment Variables
Environment variables override config file.

| Variable | Description |
|----------|-------------|
| `STUNL_API_KEY` | API key |
| `STUNL_SERVER` | Server address |
| `STUNL_DEV_SERVER` | Dev server (legacy) |

### Create Example Config
```bash
stunl -init-config
```

### Show Current Config
```bash
stunl -show-config
```

---

## CLI Reference

### All Flags

```
Usage: stunl [flags]

Tunnel Configuration:
  -port int          Local port to tunnel (default 3000)
  -host string       Local host to tunnel (default "localhost")
  -protocol string   Protocol: http, tcp, udp (default "http")
  -id string         Custom tunnel ID/subdomain (Pro)
  
Multi-Port:
  -ports string           Port mappings (e.g., "web:3000:http,api:8080:http")
  -routing-strategy string  Routing: path|subdomain|header|mixed (default "path")
  -routing-rules string   JSON file with routing rules

Security:
  -password string   Password protect tunnel (HTTP Basic Auth)
  -oauth string      OAuth provider: github, google, microsoft
  -oauth-github-org string   Restrict to GitHub org members
  -oauth-github-team string  Restrict to GitHub team (org/team)
  -oauth-allow-domain string Email domain restriction
  -oauth-allow-email string  Specific email restriction
  -e2e              Enable end-to-end encryption
  -e2e-cert string  Certificate for E2E (PEM)
  -e2e-key string   Private key for E2E (PEM)

Domain:
  -domain string    Custom domain
  -autocert         Request Let's Encrypt certificate
  -root             Use root domain (not subdomain)

Connection:
  -server string    Server address (default "grpc.stunl.com")
  -key string       API key
  -timeout duration Connection timeout (default 30s)
  -max-retries int  Max reconnection attempts (default unlimited)

TCP/UDP:
  -public-port int  Request specific public port (10001-19999)

TLS:
  -ca string        CA certificate for verification
  -cert string      Client certificate (mTLS)
  -key-file string  Client private key (mTLS)
  -insecure         Disable TLS (NOT RECOMMENDED)
  -skip-verify      Skip certificate verification (NOT RECOMMENDED)
  -security string  Security protocol version (default "v2.0")

Output:
  -plain            Plain text output (no colors)
  -version          Show version
  -show-config      Show current configuration
  -init-config      Create example config file
  -anonymous        No-auth tunnel (30min, 100MB, HTTP only)
```

---

## Pricing & Limits

### Anonymous (No Account)
- **Price:** Free
- **Session:** 30 minutes max
- **Bandwidth:** 100MB per session
- **Protocols:** HTTP only
- **Features:** Auto-generated URL only

### Trial (3 Days)
- **Price:** Free (credit card required)
- **Bandwidth:** 25GB
- **Tunnels:** 10 concurrent
- **Features:** All Pro features

### Pro ($10/month or $100/year)
- **Bandwidth:** 25GB/month
- **Tunnels:** 10 concurrent
- **Session:** Unlimited duration
- **Protocols:** HTTP, TCP, UDP, WebSocket
- **Multi-port:** 1 multiport tunnel
- **Subdomains:** Custom subdomains
- **Security:** Password, OAuth
- **Sharing:** Files, Terminal
- **Ports:** 2 reserved ports included
- **Team:** 5 members, bandwidth pooling

### Add-ons
- Reserved port: $1/month
- Reserved subdomain: $1/month
- Bandwidth pack: $2/GB or $4/5GB

---

## Troubleshooting

### Tunnel Won't Connect
```bash
# Check connectivity
curl -v https://grpc.stunl.com:9090

# Check API key
stunl -show-config

# Verbose logging (check ~/.stunl/logs/)
stunl -port 3000
```

### WebSocket Not Working
WebSocket should work automatically. Check:
1. Your app uses standard WebSocket (not Socket.io polling fallback)
2. No proxy blocking `Upgrade` header
3. Client connects to HTTPS URL

### TCP/UDP Tunnel Issues
- Ensure you're connecting to the assigned port (e.g., 10042), not your local port
- UDP may be blocked by some firewalls
- Check with `nc -v hostname port`

### Performance Issues
- Check bandwidth usage in portal
- Enable `-plain` mode for lower CPU
- Use `-e2e` only when needed (adds latency)

### Logs Location
```bash
ls ~/.stunl/logs/
# Logs named: stunl_20260125_093000.log
```

---

## Support

- **Docs:** https://stunl.com/docs
- **GitHub:** https://github.com/stunl/cli
- **Issues:** https://github.com/stunl/cli/issues
- **Email:** support@stunl.com
- **Portal:** https://portal.stunl.com

---

## Quick Examples

### Local Development
```bash
# React dev server
stunl -port 3000 -id myreactapp

# Django with custom host
stunl -port 8000 -host 127.0.0.1 -id django-dev
```

### Webhook Testing
```bash
# Stripe webhooks
stunl -port 3000 -id stripe-webhook
# Configure: https://stripe-webhook.stunl.io/webhook

# GitHub webhooks
stunl -port 3000 -id github-events
```

### Database Access
```bash
# PostgreSQL
stunl -port 5432 -protocol tcp -id postgres-tunnel
# psql -h postgres-tunnel.stunl.io -p 10042

# MySQL
stunl -port 3306 -protocol tcp -id mysql-tunnel
# mysql -h mysql-tunnel.stunl.io -P 10042

# Redis
stunl -port 6379 -protocol tcp -id redis-tunnel
# redis-cli -h redis-tunnel.stunl.io -p 10042
```

### Game Server
```bash
# Minecraft
stunl -port 25565 -protocol tcp -id minecraft -public-port 10100
# Connect: minecraft.stunl.io:10100
```

### Secure Demo
```bash
# Client presentation with password
stunl -port 3000 -password demo2024 -id client-demo

# Internal staging with GitHub auth
stunl -port 3000 -oauth github -oauth-github-org mycompany -id staging
```