gotunnel Documentation

gotunnel provides secure HTTP/HTTPS tunnels for local development with built-in proxy capabilities, OpenTelemetry observability, and enterprise-friendly configuration options.

Installation

Package Managers

Homebrew (macOS/Linux):

brew tap ferg-cod3s/gotunnel
brew install gotunnel

Scoop (Windows):

scoop bucket add ferg-cod3s https://github.com/ferg-cod3s/scoop-bucket
scoop install gotunnel

APT (Debian/Ubuntu):

curl -fsSL https://github.com/johncferguson/gotunnel/releases/latest/download/gotunnel_0.1.0-beta_amd64.deb -o gotunnel.deb
sudo dpkg -i gotunnel.deb

Direct Installation

Install Script (Unix):

curl -sSL https://raw.githubusercontent.com/johncferguson/gotunnel/main/scripts/install.sh | bash

Go Install:

go install github.com/johncferguson/gotunnel/cmd/gotunnel@latest

Quick Start

Basic Usage

Start a tunnel without root privileges:

# Tunnel your app running on port 3000
gotunnel --proxy=builtin --no-privilege-check start \
  --port 3000 --domain myapp --https=false

Access your app:

• Local: http://localhost:3000
• Tunnel: http://myapp.local:8080 (with non-privileged ports)

With HTTPS (default)

gotunnel start --port 3000 --domain myapp
# Access at: https://myapp.local

Multiple Tunnels

# Terminal 1: Frontend
gotunnel start --port 3000 --domain frontend

# Terminal 2: API  
gotunnel start --port 8080 --domain api

# Terminal 3: Database Admin
gotunnel start --port 5432 --domain pgadmin

CLI Options

Global Flags

gotunnel [global options] command [command options] [arguments...]

GLOBAL OPTIONS:
   --no-privilege-check         Skip privilege check
   --sentry-dsn value           Sentry DSN for error tracking [$SENTRY_DSN]
   --environment value          Environment (development, staging, production) [$ENVIRONMENT]
   --debug                      Enable debug logging and tracing [$DEBUG]
   --proxy value                Proxy mode: builtin, nginx, caddy, auto, config, none [$GOTUNNEL_PROXY]
   --proxy-http-port value      HTTP port for proxy (default: 80) [$GOTUNNEL_PROXY_HTTP_PORT]
   --proxy-https-port value     HTTPS port for proxy (default: 443) [$GOTUNNEL_PROXY_HTTPS_PORT]

Commands

gotunnel start --port 3000 --domain myapp    # Start tunnel
gotunnel stop myapp                           # Stop specific tunnel  
gotunnel list                                 # List active tunnels
gotunnel stop-all                            # Stop all tunnels

Configuration File

Create ~/.config/gotunnel/config.yaml:

proxy:
  mode: "builtin"
  http_port: 8080
  https_port: 8443

observability:
  sentry:
    dsn: "YOUR_SENTRY_DSN_HERE"
  logging:
    level: "info"
  tracing:
    enabled: true
    sample_rate: 1.0

Environment Variables

Docker Deployment

Docker Compose

version: '3.8'
services:
  gotunnel:
    image: ghcr.io/johncferguson/gotunnel:latest
    ports:
      - "80:80"
      - "443:443"
    environment:
      - ENVIRONMENT=production
      - SENTRY_DSN=YOUR_SENTRY_DSN_HERE
    volumes:
      - ./certs:/app/certs
      - ./config:/app/config
    restart: unless-stopped

Metrics

gotunnel exposes Prometheus metrics at :9090/metrics:

• gotunnel_tunnels_active - Number of active tunnels
• gotunnel_requests_total - Total HTTP requests processed
• gotunnel_request_duration_seconds - Request processing time
• gotunnel_errors_total - Total errors by type

Tracing

Distributed tracing via OpenTelemetry:

# With OTLP endpoint
gotunnel --debug start --port 3000 --domain myapp

Common Issues

"Permission denied" on ports 80/443

# Use non-privileged ports
gotunnel --proxy-http-port 8080 --proxy-https-port 8443 start --port 3000 --domain myapp

"Domain not accessible"

# Check /etc/hosts
cat /etc/hosts | grep myapp.local

# Check DNS resolution
dig myapp.local
nslookup myapp.local

Debug Mode

# Enable debug logging
gotunnel --debug start --port 3000 --domain myapp

# Check observability
curl http://localhost:9090/metrics