Introduction to LocalUp
LocalUp is a modern QUIC-based tunnel system that enables you to expose local servers to the internet through geographically distributed exit nodes. Built with security and performance in mind, LocalUp supports multiple protocols (TCP, TLS/SNI, HTTP, HTTPS) with automatic HTTPS certificates, wildcard domains, and QUIC-based multiplexing.
Installation
Install LocalUp using one of the following methods:
Homebrew (macOS/Linux)
brew tap localup-dev/tap
brew install localup
Quick Install Script
curl -fsSL https://raw.githubusercontent.com/localup-dev/localup/main/scripts/install.sh | bash
Verify Installation
localup --version
Upgrading
# Homebrew
brew update && brew upgrade localup
# Or re-run the install script
curl -fsSL https://raw.githubusercontent.com/localup-dev/localup/main/scripts/install.sh | bash
For detailed installation options and manual downloads, see the Getting Started Guide.
Quick Start
Get a tunnel running in 60 seconds:
# 1. Start a local server (example: Python HTTP server)
python3 -m http.server 3000 &
# 2. Generate a JWT token
export TOKEN=$(localup generate-token --secret "my-secret" --sub "demo" --token-only)
# 3. Create tunnel to a relay server
localup --port 3000 --relay relay.example.com:4443 --subdomain demo --token "$TOKEN"
# Your local server is now accessible at https://demo.relay.example.com
For self-hosting your own relay server, see the complete Getting Started Guide.
What is LocalUp?
LocalUp provides two primary tunneling modes:
Traditional Tunnels (Public Exposure)
Expose your local development servers to the internet for testing webhooks, sharing demos, or accessing services remotely.
Local Service → Client → Relay → Internet
:3000 QUIC :443 Public URL
https://myapp.relay.com
Use this for:
- Testing webhooks from GitHub, Stripe, Twilio, etc.
- Sharing local demos with clients or team members
- Mobile app development (test against local backend)
- Quick prototyping without deploying
Reverse Tunnels (Private Access)
Securely access private services behind NAT/firewall without exposing them to the public internet. Only authorized clients with valid JWT tokens can connect.
Private Service ← Agent ← Relay ← Client
:5432 localhost :4443 Authenticated
(private) (QUIC) only you
Use this for:
- Accessing databases on private networks
- Managing IoT devices behind NAT
- Remote administration without VPN complexity
- Secure access to internal APIs
Key Features
Multi-Protocol Support
LocalUp supports four tunnel protocols, each optimized for different use cases:
- TCP Tunnels: Port-based routing for databases, SSH, and custom TCP services
- TLS/SNI Tunnels: SNI-based routing with TLS passthrough for end-to-end encryption
- HTTP Tunnels: Host-based routing for web applications and APIs
- HTTPS Tunnels: TLS termination with automatic certificates
Learn more about each protocol:
QUIC-Native Transport
Built on QUIC (Quick UDP Internet Connections), the same protocol powering HTTP/3:
- Built-in Multiplexing: Multiple streams over a single connection
- 0-RTT Connection Establishment: Near-instant reconnections
- TLS 1.3 Security: Modern encryption with perfect forward secrecy
- Better Performance: Optimized for mobile and unreliable networks
- Per-Stream Flow Control: No head-of-line blocking
Automatic HTTPS
Integrated Let's Encrypt support for automatic HTTPS certificates:
- Automatic certificate generation and renewal
- Wildcard domain support (
*.yourdomain.com) - Custom domain support
- Self-signed certificates for local development
Flexible Routing
Three routing strategies for different protocols:
- Port-based (TCP): Route by destination port number
- SNI-based (TLS): Route by Server Name Indication
- Host-based (HTTP/HTTPS): Route by HTTP Host header
Smart Reconnection
Automatic reconnection with state preservation:
- Maintains port allocation (TCP tunnels)
- Preserves subdomain assignments (HTTP/HTTPS tunnels)
- Exponential backoff for failed connections
- Seamless failover to backup relay servers
JWT Authentication
Secure token-based authentication:
- Industry-standard JWT tokens
- HMAC-SHA256 signatures (HS256)
- Token expiration and rotation support
- Separate tokens for agents and clients (reverse tunnels)
How It Works
LocalUp uses a three-tier architecture for optimal performance and security:
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ LocalUp Architecture │
└─────────────────────────────────────────────────────────────────┘
Client Relay Server Internet
(Your Machine) (Public Server) (End Users)
│ │ │
│ ①─ QUIC/TLS 1.3 ───→│ │
│ (JWT Auth) │ │
│ │ │
│ ②─ Register ────────→│ │
│ Tunnel │ │
│ │ │
│ │←──── ③ Request ────────│
│ │ (TCP/HTTP/TLS) │
│ │ │
│←─── ④ Forward ────────│ │
│ Request │ │
│ │ │
│──── ⑤ Response ──────→│ │
│ │ │
│ │─────⑥ Response ────────→│
Flow:
- Client Connection: Client establishes QUIC connection to relay, authenticates with JWT
- Tunnel Registration: Client registers tunnel (requests subdomain or port allocation)
- External Request: End user connects to relay (e.g.,
https://myapp.relay.com) - Request Forwarding: Relay forwards request through QUIC tunnel to client
- Local Processing: Client forwards to local service (e.g.,
localhost:3000) - Response: Response flows back through same path to end user
Multiplexing Architecture
All communication uses QUIC multiplexing where a single connection carries multiple logical streams:
┌─────────────────────────────────────────────────────────────┐
│ QUIC Connection │
├─────────────────────────────────────────────────────────────┤
│ Stream 0: Control │ Stream 1: TCP │ Stream 2: HTTP│
│ (Connect, Ping) │ (TcpConnect,Data) │ (Request,Resp)│
├───────────────────────┼────────────────────┼────────────────┤
│ Stream 3: TCP │ Stream N... │ │
│ (TcpConnect,Data) │ (one per request) │ │
└─────────────────────────────────────────────────────────────┘
Benefits:
- ✅ Natural isolation - one slow request doesn't block others
- ✅ No mutexes needed - each stream is independent
- ✅ Better performance - parallel streams utilize available bandwidth
- ✅ Proper flow control - per-stream backpressure
Use Cases
Web Development
Webhook Testing:
localup --port 3000 --protocol https --relay relay.example.com:4443 --subdomain webhooks --token "$TOKEN"
# Share https://webhooks.relay.example.com with GitHub, Stripe, etc.
Demo Sharing:
localup --port 8080 --protocol http --relay relay.example.com:4443 --subdomain demo --token "$TOKEN"
# Share http://demo.relay.example.com with clients
Database Access
PostgreSQL Tunnel:
localup --port 5432 --protocol tcp --relay relay.example.com:4443 --token "$TOKEN"
# Connect from anywhere: psql -h relay.example.com -p 15432
Private Database (Reverse Tunnel):
# On private network: Run agent
localup agent --relay relay.example.com:4443 --agent-id "prod-db" --target-address "localhost:5432" --token "$AGENT_TOKEN"
# From laptop: Connect through relay
localup connect --relay relay.example.com:4443 --agent-id "prod-db" --local-address "localhost:19432" --token "$CLIENT_TOKEN"
Mobile Development
Local API Testing:
localup --port 8000 --protocol https --relay relay.example.com:4443 --subdomain api --token "$TOKEN"
# Test mobile app against https://api.relay.example.com
IoT & Home Automation
Remote Device Access:
# On home network: Run agent for IoT device
localup agent --relay relay.example.com:4443 --agent-id "home-camera" --target-address "localhost:8080" --token "$AGENT_TOKEN"
# From anywhere: Access device
localup connect --relay relay.example.com:4443 --agent-id "home-camera" --local-address "localhost:18080" --token "$CLIENT_TOKEN"
Team Collaboration
Share Local Environment:
localup --port 3000 --protocol https --relay relay.example.com:4443 --subdomain team-review --token "$TOKEN"
# Share https://team-review.relay.example.com with teammates
Why LocalUp?
Performance
Traditional Solutions:
- Custom multiplexing layer adds complexity
- TCP head-of-line blocking on slow connections
- Manual connection management and retries
LocalUp (QUIC-Native):
- Built-in multiplexing (no custom layer)
- 0-RTT connection establishment
- Per-stream flow control (no head-of-line blocking)
- Automatic connection migration on network changes
Security
Zero-Knowledge Architecture:
- End-to-end encryption with QUIC (TLS 1.3)
- Relay cannot decrypt payload
- Perfect forward secrecy
- JWT-based authentication
Reverse Tunnels:
- No inbound firewall rules required
- Mutual authentication (agent + client)
- Localhost-only access (prevents lateral movement)
- Token-based authorization
Flexibility
Multiple Protocol Support:
- TCP for databases and custom services
- TLS/SNI for end-to-end encrypted connections
- HTTP for plain web traffic
- HTTPS with automatic certificates
Deployment Options:
- Self-hosted relay servers
- Cloud-hosted relays
- Docker containers
- Kubernetes deployments
Developer Experience
Simple CLI:
# Create tunnel with one command
localup --port 3000 --relay relay.example.com:4443 --subdomain myapp --token "$TOKEN"
Automatic Features:
- Port allocation (TCP tunnels)
- Subdomain generation (HTTP/HTTPS tunnels)
- TLS certificate management
- Connection retries and failover
Ready to get started?
→ Installation & Setup Guide - Install LocalUp and create your first tunnel in 2 minutes
Explore specific protocols:
- TCP Relay → - Databases, SSH, custom TCP services
- TLS/SNI Relay → - End-to-end encrypted connections
- HTTP/HTTPS Relay → - Web applications and APIs
- Reverse Tunnels → - Secure private service access