Skip to main content

ReTunnel Client

PyPI Version Python Versions License

ReTunnel is a secure tunnel service that allows you to expose local servers to the internet. This is the official Python client library and CLI.

Features

  • 🚀 Easy to use - Single command to expose your local server
  • 🔒 Secure - All connections are encrypted
  • 🌐 HTTP/HTTPS and TCP - Support for web and TCP services
  • 🔑 Automatic registration - No sign-up required for basic usage
  • ⚡ High performance - Built with asyncio for efficiency
  • 🎛️ Professional CLI - Rich terminal interface with Typer

Installation

pip install retunnel

Requires Python 3.9 or higher.

Quick Start

HTTP Tunnel

Expose a local web server on port 8080:

retunnel http 8080

TCP Tunnel

Expose a local TCP service on port 22:

retunnel tcp 22

With Custom Subdomain

Request a specific subdomain (subject to availability):

retunnel http 8080 --subdomain myapp

With Authentication

Protect your tunnel with HTTP Basic Auth:

retunnel http 8080 --auth user:password

Configuration

Server Endpoint

By default, ReTunnel connects to localhost:6400. You can configure this using:

  • Environment variable: RETUNNEL_SERVER_ENDPOINT=your.server.com:port
  • Command-line option: --server your.server.com:port
  • Configuration file: server_addr: your.server.com:port

Save Authentication Token

Save your auth token for persistent access:

retunnel authtoken YOUR_AUTH_TOKEN

Configuration File

Create a retunnel.yml file to define multiple tunnels:

server_addr: ${RETUNNEL_SERVER_ENDPOINT:localhost:6400}
auth_token: ${RETUNNEL_AUTH_TOKEN}
log_level: INFO

tunnels:
  - name: web
    protocol: http
    local_port: 8080
    subdomain: myapp

  - name: api
    protocol: http
    local_port: 3000
    auth: user:pass

  - name: ssh
    protocol: tcp
    local_port: 22

Then start all tunnels:

retunnel start retunnel.yml

Environment Variables

  • RETUNNEL_SERVER_ENDPOINT - Server endpoint (default: localhost:6400)
  • RETUNNEL_AUTH_TOKEN - Authentication token
  • RETUNNEL_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)

Python API

import asyncio
from retunnel import ReTunnelClient, TunnelConfig

async def main():
    # Create client
    client = ReTunnelClient()

    # Connect to server
    await client.connect()

    # Create HTTP tunnel
    config = TunnelConfig(protocol="http", local_port=8080)
    tunnel = await client.request_tunnel(config)

    print(f"Tunnel URL: {tunnel.url}")

    # Keep running
    await asyncio.Event().wait()

asyncio.run(main())

Advanced Usage

Custom Server

Connect to a self-hosted ReTunnel server:

retunnel http 8080 --server your-server.com:8000

Multiple Tunnels

Use the configuration file to manage multiple tunnels simultaneously.

Logging

Set log level for debugging:

retunnel http 8080 --log-level DEBUG

CLI Commands

  • retunnel http PORT - Create HTTP tunnel
  • retunnel tcp PORT - Create TCP tunnel
  • retunnel start CONFIG - Start tunnels from config file
  • retunnel authtoken TOKEN - Save authentication token
  • retunnel config - Manage configuration
  • retunnel version - Show version
  • retunnel credits - Show open source credits

Development

Setup

# Clone repository
git clone https://github.com/retunnel/retunnel-client
cd retunnel-client

# Install with development dependencies
make install-dev

Testing

# Run tests
make test

# Run linting
make lint

# Run type checking
make typecheck

# Format code
make format

Building

make build

License

MIT License - see LICENSE file for details.

Credits

ReTunnel uses these excellent open source libraries:

  • aiohttp - Async HTTP client/server
  • websockets - WebSocket client/server
  • msgpack - Efficient serialization
  • typer - CLI framework
  • rich - Terminal formatting
  • pydantic - Data validation

Support

Metadata

Release files for retunnel 3.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for retunnel 3.3.3
File Size Uploaded Provenance Actions
retunnel-3.3.3.tar.gz 70.5 kB Without provenance Details for retunnel-3.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for retunnel 3.3.3
File Interpreter ABI Platform Actions
retunnel-3.3.3-py3-none-any.whl Python 3 none any Details for retunnel-3.3.3-py3-none-any.whl

Total release size: 128.5 kB

Release files / retunnel-3.3.3.tar.gz

Download URL retunnel-3.3.3.tar.gz
Size 70.5 kB
Tags Source
SHA-256 checksum
How to use checksums
4477da7a3df6fb5f2a478e7b32c9d9dd9c73dc81bd1219f872440ad5411d52f4
BLAKE2b-256 checksum
How to use checksums
e8ab5e6ecea22d22eb274002e43c4c13f8093b4c7280b5d45ee020a934b2cc46
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / retunnel-3.3.3-py3-none-any.whl

Download URL retunnel-3.3.3-py3-none-any.whl
Size 58.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4dd0170e5fecfb4a9a08c8437bb264749aaf270432196128969062f4883ce7e2
BLAKE2b-256 checksum
How to use checksums
27fea53fac171772c20cfa18616c8fca2623e4d5d09ea5f3df4d9ca7464b1812
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for retunnel 3.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page