flaredantic 0.1.5

Create Cloudflare, Microsoft, and Serveo tunnels with ease.

Flaredantic

Flaredantic is a Python library that simplifies the process of creating tunnels to expose your local services to the internet. It supports Cloudflare, Serveo, and Microsoft Dev Tunnel services, making it a user-friendly alternative to ngrok, localtunnel, and similar tools.

🌟 Features

• 🔌 Zero-configuration tunnels
• 🔒 Secure HTTPS endpoints
• 🚀 Easy-to-use Python API
• 💻 Command-line interface (CLI)
• 📦 Automatic binary management
• 🔄 Multiple tunnel providers (Cloudflare, Serveo, Microsoft Dev Tunnels)
• 🌐 TCP forwarding support (Serveo)
• 🎯 Cross-platform support (Windows, macOS, Linux)
• 📱 Android support via Termux
• 🔄 Context manager support
• 📊 Download progress tracking
• 📝 Detailed logging with verbose mode

🎯 Why Flaredantic?

While tools like ngrok are great, Flaredantic offers several advantages:

• Free and unlimited tunnels
• Multiple tunnel providers to choose from
• Better stability and performance
• TCP forwarding with Serveo
• No rate limiting

Flaredantic makes it dead simple to use tunnels in your Python projects!

⚠️ Warning: Exposing local services to the internet can be a security risk. Never expose sensitive or unprotected endpoints. Use at your own risk.

🚀 Installation

pip install flaredantic

After installation, you can use either the CLI command flare or the Python API.

📖 Quick Start

Command Line Usage

The simplest way to create a tunnel is using the CLI:

# Basic usage with Cloudflare (default) - expose port 8080 with verbose output
flare --port 8080 -v

# Use Serveo tunnel instead
flare --port 8080 --tunnel serveo

# Use Microsoft Dev Tunnels
flare --port 8080 --tunnel microsoft

# TCP forwarding with Serveo
flare --port 5432 --tcp

CLI Options:

-p, --port     Local port to expose (required)
-t, --timeout  Tunnel start timeout in seconds (default: 30)
-v, --verbose  Show detailed progress output
--tunnel       Tunnel provider to use [cloudflare, serveo, microsoft] (default: cloudflare)
--tcp          Use Serveo with TCP forwarding (overrides --tunnel)

Python API Usage

Basic Usage with Cloudflare

from flaredantic import FlareTunnel, FlareConfig

# Create a tunnel for your local server running on port 8000
config = FlareConfig(port=8080)
with FlareTunnel(config) as tunnel:
    print(f"Your service is available at: {tunnel.tunnel_url}")
    # Your application code here
    input("Press Enter to stop the tunnel...")

Basic Usage with Serveo

from flaredantic import ServeoTunnel, ServeoConfig

# Create a tunnel using Serveo
config = ServeoConfig(port=8080)
with ServeoTunnel(config) as tunnel:
    print(f"Your service is available at: {tunnel.tunnel_url}")
    # Your application code here
    input("Press Enter to stop the tunnel...")

Basic Usage with Microsoft Dev Tunnels

from flaredantic import MicrosoftTunnel, MicrosoftConfig

# Create a tunnel using Microsoft Dev Tunnels
config = MicrosoftConfig(port=8080)
with MicrosoftTunnel(config) as tunnel:
    print(f"Your service is available at: {tunnel.tunnel_url}")
    # Your application code here
    input("Press Enter to stop the tunnel...")

TCP Forwarding with Serveo

from flaredantic import ServeoTunnel, ServeoConfig

# Create a TCP tunnel using Serveo
config = ServeoConfig(port=5432, tcp=True)
with ServeoTunnel(config) as tunnel:
    print(f"TCP tunnel available at: {tunnel.tunnel_url}")
    # Your application code here
    input("Press Enter to stop the tunnel...")

Custom Configuration

from flaredantic import FlareTunnel, FlareConfig
from flaredantic import ServeoTunnel, ServeoConfig
from flaredantic import MicrosoftTunnel, MicrosoftConfig
from pathlib import Path

# Configure Cloudflare tunnel with custom settings
cloudflare_config = FlareConfig(
    port=8080,
    bin_dir=Path.home() / ".my-tunnels",
    timeout=60,
    verbose=True  # Enable detailed logging
)

# Configure Serveo tunnel with custom settings
serveo_config = ServeoConfig(
    port=8080,
    ssh_dir=Path.home() / ".my-tunnels/ssh",  # Custom SSH directory
    timeout=60,
    verbose=True  # Enable detailed logging
)

# Configure Microsoft Dev Tunnels with custom settings
microsoft_config = MicrosoftConfig(
    port=8080,
    bin_dir=Path.home() / ".my-tunnels",
    timeout=60,
    verbose=True,  # Enable detailed logging
    tunnel_id="flaredantic",  # Custom tunnel ID
    device_login=True  # Use device login flow
)

# Create and start tunnel (choose one)
with MicrosoftTunnel(microsoft_config) as tunnel:
    print(f"Access your service at: {tunnel.tunnel_url}")
    input("Press Enter to stop the tunnel...")

Flask Application

from flask import Flask
from flaredantic import FlareTunnel, FlareConfig
import threading

app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello, World!'

def run_tunnel():
    config = FlareConfig(
        port=5000,
        verbose=True  # Enable logging for debugging
    )
    with FlareTunnel(config) as tunnel:
        print(f"Flask app available at: {tunnel.tunnel_url}")
        app.run(port=5000)

if __name__ == '__main__':
    threading.Thread(target=run_tunnel).start()

⚙️ Configuration Options

Cloudflare Tunnel Options

Option	Type	Default	Description
port	int	Required	Local port to expose
bin_dir	Path	~/.flaredantic	Directory for cloudflared binary
timeout	int	30	Tunnel start timeout in seconds
verbose	bool	False	Show detailed progress and debug output

Serveo Tunnel Options

Option	Type	Default	Description
port	int	Required	Local port to expose
ssh_dir	Path	~/.flaredantic/ssh	Directory for SSH configuration
timeout	int	30	Tunnel start timeout in seconds
verbose	bool	False	Show detailed progress and debug output
tcp	bool	False	Enable TCP forwarding instead of HTTP

Microsoft Dev Tunnels Options

Option	Type	Default	Description
port	int	Required	Local port to expose
bin_dir	Path	~/.flaredantic	Directory for devtunnel binary
timeout	int	30	Tunnel start timeout in seconds
verbose	bool	False	Show detailed progress and debug output
tunnel_id	str	"flaredantic"	Custom tunnel ID
device_login	bool	True	Use device login flow

📦 Requirements

• Cloudflare tunnel: No additional requirements (binary auto-downloaded)
• Serveo tunnel: Requires SSH client to be installed
• Microsoft Dev Tunnels: No additional requirements (binary auto-downloaded)
  • Note: Currently only supports Linux and macOS.

❗️Note: Serveo servers might occasionally be unavailable as they are a free service. Flaredantic automatically detects when Serveo is down and provides a clear error message. Consider using Cloudflare tunnels if you need guaranteed availability.

📚 More Examples

For more detailed examples and use cases, check out our examples:

• Cloudflare Examples - HTTP Server, Django, FastAPI, Flask
• Serveo Examples - HTTP, TCP, SSH forwarding, database access
• Microsoft Examples - HTTP Server, Custom Tunnel ID, Device Login

---