​
HTTP Tunnels for Local Development

This guide covers setting up HTTP tunnels to expose your local development environment to the internet, essential for testing webhooks and OAuth integrations.

​
Overview

HTTP tunnels allow external services to communicate with your local development server, enabling:
  • Webhook testing from third-party services
  • OAuth callback testing
  • Integration testing with external APIs
  • Sharing your local environment with team members

​
Quick Start

For quick testing and development: 
# Start tunnel for main app
cloudflared tunnel --url https://localhost:3000

# Start tunnel for Supabase storage
cloudflared tunnel --url http://localhost:54321
This gives you a temporary URL that changes each time you restart the tunnel.

​
Permanent Tunnel Setup

​
1. Install Cloudflared

# Install cloudflared
brew install cloudflared

# Verify installation
cloudflared --version

​
2. Login to Cloudflare

You need access to the HeyBilly Cloudflare account: 
# Login to Cloudflare (requires account access)
cloudflared tunnel login

# This will open a browser window for authentication
# Contact @spyl-pennylane for access to the HeyBilly account

​
3. Create Your Personal Tunnel

# Create a new tunnel
cloudflared tunnel create your-name

# Replace "your-name" with your preferred identifier
# Example: cloudflared tunnel create john-dev

​
4. Configure DNS Routing

# Route DNS to your tunnel
cloudflared tunnel route dns your-name your-name.tunnels.heybilly.io

# This creates: https://your-name.tunnels.heybilly.io

​
5. Create Configuration File

Create .cloudflared/your-name.yml: 
url: https://localhost:3000
tunnel: <Tunnel-UUID>
credentials-file: /Users/<Your-user>/.cloudflared/<Tunnel-UUID>.json
Important: Replace <Tunnel-UUID> with the actual UUID from step 3, and <Your-user> with your username.

​
6. Run Your Tunnel

# Start your tunnel
cloudflared tunnel --config=.cloudflared/your-name.yml run your-name

# Keep this running in a separate terminal

​
Multiple Tunnel Configuration

​
Main Application Tunnel

# .cloudflared/your-name.yml
url: https://localhost:3000
tunnel: <Tunnel-UUID>
credentials-file: /Users/<Your-user>/.cloudflared/<Tunnel-UUID>.json

​
Supabase Storage Tunnel

# .cloudflared/your-name-storage.yml
url: http://localhost:54321
tunnel: <Storage-Tunnel-UUID>
credentials-file: /Users/<Your-user>/.cloudflared/<Storage-Tunnel-UUID>.json

​
Running Multiple Tunnels

# Terminal 1: Main app tunnel
cloudflared tunnel --config=.cloudflared/your-name.yml run your-name

# Terminal 2: Storage tunnel
cloudflared tunnel --config=.cloudflared/your-name-storage.yml run your-name-storage

​
Environment Configuration

​
Update Environment Variables

Add these to your .env.local: 
# Local tunnels
SUPABASE_STORAGE_TUNNEL_URL=https://your-name-storage.tunnels.heybilly.io
APP_TUNNEL_URL=https://your-name.tunnels.heybilly.io

​
Integration-Specific URLs

Update your integration configurations to use the tunnel URLs:

​
HubSpot

HUBSPOT_REDIRECT_URI=https://your-name.tunnels.heybilly.io/oauth/hubspot/redirect_uri

​
Pipedrive

PIPEDRIVE_REDIRECT_URI=https://your-name.tunnels.heybilly.io/oauth/pipedrive/redirect_uri

​
Spendesk

SPENDESK_REDIRECT_URI=https://your-name.tunnels.heybilly.io/oauth/spendesk/redirect_uri

​
Use Cases

​
Webhook Testing

# Start your tunnel
cloudflared tunnel --config=.cloudflared/your-name.yml run your-name

# Update webhook URLs in external services to use:
# https://your-name.tunnels.heybilly.io/webhooks/[service]

​
OAuth Development

# Update OAuth redirect URIs to use your tunnel
# Example: https://your-name.tunnels.heybilly.io/oauth/hubspot/redirect_uri

​
Team Collaboration

Share your tunnel URL with team members for:
  • Code review and testing
  • Integration testing
  • Demo purposes
  • Troubleshooting sessions

​
Troubleshooting

​
Common Issues

​
Tunnel Won’t Start

# Check if tunnel is already running
cloudflared tunnel list

# Kill existing tunnel processes
pkill cloudflared

# Verify configuration file syntax
cloudflared tunnel --config=.cloudflared/your-name.yml run your-name

​
DNS Resolution Issues

# Check DNS resolution
nslookup your-name.tunnels.heybilly.io

# Recreate DNS route if needed
cloudflared tunnel route dns your-name your-name.tunnels.heybilly.io

​
Credential File Issues

# Check credential file location
ls -la ~/.cloudflared/

# Verify file permissions
chmod 600 ~/.cloudflared/*.json

​
Debug Mode

Enable verbose logging: 
# Run with debug information
cloudflared tunnel --config=.cloudflared/your-name.yml run your-name --loglevel debug

# Check tunnel status
cloudflared tunnel info your-name

​
Getting Help

​
Monitoring

Monitor tunnel health and performance: 
# Check tunnel status
cloudflared tunnel info your-name

# View tunnel metrics
cloudflared tunnel metrics your-name

# List active tunnels
cloudflared tunnel list