CodeNomad Tunnel

STEP 1

Configure DNS

Add a wildcard A record pointing to your VPS IP.

dns

# In your DNS provider dashboard:
*.tunnel.yourdomain.com  IN  A  YOUR_VPS_IP

STEP 2

Deploy Hub to VPS

One command. Auto-downloads binary, sets up systemd service, starts tunnel hub.

bash

# Basic (port 80, HTTP)
curl -fsSL https://raw.githubusercontent.com/dyyz1993/codenomad-tunnel/master/deploy.sh | \
  sudo bash -s -- hub --domain "*.tunnel.yourdomain.com"

bash

# With HTTPS (behind reverse proxy like Caddy/Nginx)
curl -fsSL https://raw.githubusercontent.com/dyyz1993/codenomad-tunnel/master/deploy.sh | \
  sudo bash -s -- hub --domain "*.tunnel.yourdomain.com" \
    --http-port 8080 --api-port 8080 \
    --public-url "https://tunnel.yourdomain.com"

STEP 3

Connect from Local Machine

Run on any machine (Mac/Linux/Windows) to expose a local service.

bash

# Expose localhost:3000
curl -fsSL https://raw.githubusercontent.com/dyyz1993/codenomad-tunnel/master/deploy.sh | \
  bash -s -- client --hub-url "https://api.tunnel.yourdomain.com" \
    --local "http://localhost:3000" --insecure

output

# You'll see:
Tunnel registered: a3x7k9
Public URL:  https://a3x7k9.tunnel.yourdomain.com
Relay URL:   wss://tunnel.yourdomain.com/relay/t_a3x7k9
Connected to relay

STEP 4

Done

Anyone can now access your local service via the public URL.

bash

curl https://a3x7k9.tunnel.yourdomain.com/api/data

Management API

Hub exposes REST API for tunnel CRUD, health checks, and request logs.

GET /api/health

WebSocket Relay

Client maintains persistent WebSocket to hub, relaying HTTP requests bidirectionally.

/relay/{tunnelId}

Auto Reconnect

Client auto-reconnects on disconnect with exponential backoff. No manual intervention needed.

3s retry interval

Platforms

Pre-built binaries for Linux, macOS, Windows on amd64 and arm64.

5 platforms

ADVANCED

CLI Reference

hub flags

--domain       tunnel.yourdomain.com   # Base domain (required)
--api-domain   api.tunnel.yourdomain.com # API domain (auto-derived)
--http-port    80                      # Proxy port
--api-port     8080                    # API port
--public-url   https://...             # Override derived URL
--tls-cert     /path/to/cert.pem      # TLS cert
--tls-key      /path/to/key.pem       # TLS key

client flags

--hub-url      https://api.tunnel...  # Hub API URL (required)
--local        http://localhost:3000 # Local service (required)
--subdomain    myapp                 # Request specific subdomain
--name         my-service            # Tunnel name
--insecure                             # Skip TLS verification

DOCKER

Docker Deployment

bash

docker compose up -d