Documentation / Getting Started

Getting Started

Get up and running with stunl in under 5 minutes

Installation

Install stunl using your preferred package manager or download the binary directly.

macOS (Homebrew) 
$ brew install stunl/tap/stunl
Linux 
$ curl -fsSL stunl.com/install.sh | bash
Direct Download (all platforms) 
# Download from GitHub releases
https://github.com/stunl/cli/releases/latest

Quick Start

1

Start a local server

# Start any local server (Python, Node, etc.)
$ python -m http.server 3000
# or
$ npm run dev  # typically starts on port 3000
2

Set your API key

Get your key at portal.stunl.com (free tier available)

$ export STUNL_API_KEY=st_live_xxx
3

Create a tunnel

$ stunl -port 3000

  ● STUNL

  ╭── ◎ ── HTTP
  │   HTTPS    https://abc123.stunl.io
  │   HTTP     http://abc123.stunl.io
  │   Local    localhost:3000
4

Share your URL

Your local server is now accessible from anywhere! Share the URL with teammates, clients, or use it for webhook testing.

Getting an API Key

Pro Free tier available

Sign up at portal.stunl.com to get your API key. Free tier with no credit card required. 

# Set your API key
$ export STUNL_API_KEY=st_live_xxx

# Create a tunnel
$ stunl -port 3000
  • ✓ Unlimited session duration
  • ✓ 25GB monthly bandwidth
  • ✓ HTTP, TCP, UDP, WebSocket
  • ✓ Custom tunnel IDs (-id myapp)
  • ✓ Password protection
  • ✓ Multiple domains available

Configuration

stunl can be configured via command-line flags, environment variables, or a config file.

Environment Variables 
# Set your API key (persists across sessions)
$ export STUNL_API_KEY=st_live_your_key_here

# Optional: Use a different server
$ export STUNL_SERVER=grpc.stunl.com
Config File (~/.stunl/config.yaml) 
# Generate example config
$ stunl -init-config

# View current configuration
$ stunl -show-config

Common Examples

Expose a React/Next.js app 
$ stunl -port 3000 -id my-react-app
Expose with password protection 
$ stunl -port 8080 -password secret123
Expose a different host (e.g., Docker container) 
$ stunl -host 172.17.0.2 -port 80
Expose a TCP service (PostgreSQL) 
$ stunl -protocol tcp -port 5432 -id mydb

Troubleshooting

Connection refused

Make sure your local server is running and listening on the specified port.

stunl -port 3000 -host localhost

API key not working

Make sure you've exported your API key correctly. Check for typos or extra spaces.

echo $STUNL_API_KEY

View debug logs

Logs are written to ~/.stunl/logs/. Check the latest log file for detailed information.

Next Steps