# STUNL

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

STUNL is a tunneling service similar to ngrok, but with multi-port support, TCP/UDP tunnels, and team features. One URL can route to multiple local services.

Website: https://stunl.com
Portal: https://portal.stunl.com
Docs: https://stunl.com/docs

## Installation

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

### Linux / macOS (Binary)
```bash
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/
```

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

## Quick Start

```bash
# Expose local port 3000 to the internet (HTTP)
stunl -port 3000
# Output: https://lazy-koala-x7k9.stunl.io → localhost:3000

# Custom subdomain (requires Pro account)
stunl -port 3000 -id myapp
# Output: https://myapp.stunl.io → localhost:3000

# TCP tunnel (databases, SSH, game servers)
stunl -port 5432 -protocol tcp
# Output: tcp://swift-fox-a1b2.stunl.io:10042 → localhost:5432

# UDP tunnel (DNS, gaming, VoIP)
stunl -port 53 -protocol udp
# Output: udp://brave-eagle-c3d4.stunl.io:10043 → localhost:53

# Password protection
stunl -port 3000 -password secretpass

# OAuth protection (GitHub org members only)
stunl -port 3000 -oauth github -oauth-github-org mycompany
```

## Multi-Port Tunnels

Expose multiple services on a single hostname with path-based routing:

```bash
stunl -ports "web:3000:http,api:8080:http,db:5432:tcp"
# Output:
#   https://example.stunl.io/web → localhost:3000
#   https://example.stunl.io/api → localhost:8080
#   tcp://example.stunl.io:10042 → localhost:5432
```

Routing strategies: `path` (default), `subdomain`, `header`, `mixed`, `round_robin`, `least_connections`

## Protocols

| Protocol | Flag | Use Cases |
|----------|------|-----------|
| HTTP/HTTPS | `-protocol http` (default) | Web apps, APIs, webhooks |
| TCP | `-protocol tcp` | Databases, SSH, game servers |
| UDP | `-protocol udp` | DNS, gaming, VoIP |
| WebSocket | Automatic | Real-time apps, Socket.io |

## CLI Reference

### Essential Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-port` | Local port to tunnel | 3000 |
| `-protocol` | Protocol: http, tcp, udp | http |
| `-id` | Custom subdomain (Pro) | auto-generated |
| `-password` | Basic auth password | none |
| `-e2e` | End-to-end encryption | false |

### Multi-Port Flags

| Flag | Description |
|------|-------------|
| `-ports` | Port mappings: `name:port:protocol,...` |
| `-routing-strategy` | How to route: path, subdomain, header, mixed |
| `-routing-rules` | JSON file with advanced routing rules |

### Security Flags

| Flag | Description |
|------|-------------|
| `-oauth` | OAuth provider: github, google, microsoft |
| `-oauth-github-org` | Restrict to GitHub org members |
| `-oauth-github-team` | Restrict to GitHub team (org/team format) |
| `-oauth-allow-domain` | Restrict to email domain |
| `-oauth-allow-email` | Restrict to specific emails |
| `-e2e` | End-to-end encryption (TLS passthrough) |
| `-e2e-cert` | Certificate for E2E termination |
| `-e2e-key` | Private key for E2E termination |

### Domain Flags

| Flag | Description |
|------|-------------|
| `-domain` | Custom domain (e.g., `example.com`) |
| `-autocert` | Request Let's Encrypt certificate |
| `-root` | Use root domain instead of subdomain |

### Connection Flags

| Flag | Description | Default |
|------|-------------|---------|
| `-server` | Tunnel server address | grpc.stunl.com |
| `-key` | API key for authentication | from config |
| `-timeout` | Connection timeout | 30s |
| `-max-retries` | Max reconnection attempts | unlimited |

### Output Flags

| Flag | Description |
|------|-------------|
| `-plain` | Plain text output (no colors/unicode) |
| `-version` | Show version |
| `-show-config` | Show merged configuration |
| `-init-config` | Create example config file |

## Configuration

Config file location: `~/.stunl/config.yaml`

```yaml
api_key: st_live_xxxxx
server: grpc.stunl.com
```

Environment variables (override config file):
- `STUNL_API_KEY` - API key
- `STUNL_SERVER` - Server address

## Pricing Tiers

### Anonymous (No Signup)
- **Price:** Free (no account required)
- **Limits:** 30 min sessions, 100MB bandwidth, HTTP only
- **Features:** Basic HTTP tunnels, auto-generated URLs

### Free (Permanent, No CC)
- **Price:** $0/month
- **Bandwidth:** 2GB/month
- **Tunnels:** 1 concurrent
- **Sessions:** 1 hour max
- **Features:**
  - HTTP/HTTPS, WebSocket tunneling
  - 1 multiport tunnel
  - Multiple domain choices

### Trial (3 Days)
- **Price:** Free (credit card required)
- **Features:** All Pro features for 3 days, then auto-converts to Pro

### Pro ($10/month)
- **Bandwidth:** 50GB/month
- **Tunnels:** 5 concurrent
- **Sessions:** Unlimited
- **Features:**
  - HTTP, TCP, UDP, WebSocket
  - 3 multiport tunnels
  - Custom subdomains
  - Password protection
  - File sharing
  - Terminal sharing
  - 3 reserved TCP/UDP ports
  - 2 reserved subdomains

### Team ($25/month)
- **Bandwidth:** Unlimited
- **Tunnels:** 15 concurrent
- **Sessions:** Unlimited
- **Features:**
  - All Pro features
  - 10 multiport tunnels
  - 5 reserved TCP/UDP ports
  - 5 reserved subdomains
  - 5 team members with bandwidth pooling
  - Bring your own domain (BYOD)

## Use Cases

### Web Development
```bash
# Share local dev server with team
stunl -port 3000 -id staging -oauth github -oauth-github-org myteam
```

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

### Database Access
```bash
# Expose PostgreSQL for remote access
stunl -port 5432 -protocol tcp -id mydb
# Connect: psql -h mydb.stunl.io -p 10042 -U postgres
```

### Game Servers
```bash
# Minecraft server with reserved port
stunl -port 25565 -protocol tcp -public-port 10042
```

### Full-Stack Apps
```bash
# Frontend + API + Database on one URL
stunl -ports "web:3000:http,api:8080:http,db:5432:tcp" -id myapp
```

## Available Domains

Pro users can use these domains:
- stunl.io (default)
- localshare.io
- pentest.run
- cheburashka.net
- unixfreak.net
- unixfreak.org
- unixsysadmin.org
- ihatethe.net

## File Sharing

```bash
# Share a file (generates temporary URL)
stunl share ./build.zip

# With password and expiration
stunl share ./report.pdf -password secret -expires 24h
```

## Terminal Sharing

```bash
# Share terminal (read-only)
stunl term

# Interactive mode (viewers can type)
stunl term -i
```

## End-to-End Encryption

For maximum privacy, enable E2E encryption. The server cannot decrypt traffic:

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

# With your own certificate
stunl -port 3000 -e2e -e2e-cert cert.pem -e2e-key key.pem
```

## Architecture

- **Control plane:** gRPC over TLS (grpc.stunl.com:9090)
- **Data plane:** HTTP/WebSocket proxy, TCP/UDP forwarding
- **Client:** Single binary, no dependencies
- **Security:** TLS 1.3, optional E2E encryption, OAuth integration

## Support

- Documentation: https://stunl.com/docs
- GitHub: https://github.com/stunl/cli
- Email: support@stunl.com