Python port of the Localtunnel Client with enhancements

Expose your localhost to the 🌎 for easy testing and sharing:

• 👷🏻‍♂️ Actively maintained

A Python client for LocalTunnel, enabling developers to expose their local servers to the internet with minimal setup. Designed for ease of use, flexibility, and lightweight integration, this library supports both CLI and programmatic APIs.

LocalTunnel provides a simple way to make a local development server accessible to anyone on the internet. Unlike similar tools like Ngrok, this library is lightweight, open-source, and Python-native, making it perfect for developers who prefer seamless integration into their Python projects.

Install using a package manager 📦:

pip install localtunnel-py

uv add localtunnel-py

poetry add Localtunnel-py

For contributors or advanced users, clone the repository and install in editable mode:

git clone https://github.com/gweidart/localtunnel-py.git
cd localtunnel-py
pip install -e .

• Expose Local Servers Effortlessly:

  • Quickly share your local development server with a public URL.
  • Perfect for testing webhooks, sharing progress with team members, or debugging remotely.

• Custom Subdomains:

  • Use a custom subdomain to make your server URL more predictable and user-friendly.
  • Example: https://my-custom-subdomain.loca.lt

• Robust Retry Mechanisms:

  • Ensure tunnel connections are resilient with customizable retry strategies, including exponential backoff.

• Monitoring and Lifecycle Management:

  • Built-in support for monitoring tunnels to handle unexpected disruptions.
  • Automatically recover or notify when a tunnel goes offline.

• Flexible Header Transformations:

  • Modify request headers dynamically using HeaderTransformer.

• Lightweight CLI Tool:

  • A simple command-line interface for quick setup and deployment.

• Seamless Integration:

  • Import the library directly into your Python project and manage tunnels programmatically.

• Extensive Logging:

  • Pretty printed logging with rich tracebacks.

Here’s how to expose a local server programmatically:

import asyncio
from localtunnel.tunnel_manager import TunnelManager

async def main():
    manager = TunnelManager()
    manager.add_tunnel(port=8000, subdomain="my-subdomain")

    try:
        await manager.open_all()
        for tunnel in manager.tunnels:
            print(f"Tunnel open at URL: {tunnel.get_tunnel_url()}")

        # Keep running
        await asyncio.Event().wait()
    finally:
        await manager.close_all()

asyncio.run(main())

Expose a local server directly from the command line:

lt --port 3002 -s my-subdomain

Available arguments:

import asyncio
from localtunnel.tunnel_manager import TunnelManager

async def main():
    manager = TunnelManager()
    manager.add_tunnel(port=8000, subdomain="my-subdomain")

    try:
        await manager.open_all()
        for tunnel in manager.tunnels:
            print(f"Tunnel open at URL: {tunnel.get_tunnel_url()}")

        # Keep running
        await asyncio.Event().wait()
    finally:
        await manager.close_all()

asyncio.run(main())

Modify headers dynamically using HeaderTransformer:

from localtunnel.header_transformer import HeaderTransformerFactory

transformer = HeaderTransformerFactory.create_transformer(
    transformer_type="host", host="my-custom-host"
)
headers = {"Authorization": "Bearer token"}
transformed_headers = transformer.transform(headers)
print(transformed_headers)

Implement robust retry mechanisms for tunnel connections:

from localtunnel.utils import ExponentialBackoffRetryTemplate

retry_strategy = ExponentialBackoffRetryTemplate(base_delay=1.0, max_delay=10.0)
retry_strategy.retry(some_function, retries=5)

Use TunnelManager to handle multiple tunnels seamlessly:

from localtunnel.tunnel_manager import TunnelManager

manager = TunnelManager()
manager.add_tunnel(port=8000, subdomain="app1")
manager.add_tunnel(port=8001, subdomain="app2")
await manager.open_all()

• Issue: Tunnel connection drops frequently.

  • Solution: Enable monitoring with TunnelManager.

• Issue: Custom subdomain not working.

  • Solution: Ensure the subdomain is available and correctly passed to add_tunnel().

We welcome contributions! Here's how you can get involved:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request with a detailed description.

This project is licensed under the MIT License. See the LICENSE file for details.

• Source Code
• Issue Tracker
• Documentation