mp-tunnel 4.0.24

Tunnel System V4 - Cloudflare Workers based tunnel system

Tunnel V4

A modern tunnel system built on Cloudflare Workers and Durable Objects.

Features

• 🚀 Remote Terminal - SSH-like terminal access to your servers
• 📡 SOCKS5 Proxy - Secure proxy through your nodes
• ⚡ Command Execution - Run commands remotely
• 🔒 Secure - End-to-end encrypted connections
• 🌍 Global - Powered by Cloudflare's edge network

Installation

pip install mp-tunnel

Quick Start

Start Agent on Your Server

# Basic usage
tunnel agent --id my-server @all

# With custom tags
tunnel agent --id my-server --tags env=prod,region=us @all

# Specific services only
tunnel agent --id my-server @term @socks5

Use CLI to Connect

# List nodes
tunnel list

# Remote terminal
tunnel term --node my-server

# Execute command
tunnel exec --node my-server "uptime"

# SOCKS5 proxy
tunnel socks5 --node my-server --port 1080

Configuration

Environment Variables

• TUNNEL_WORKER_URL - Override default Worker URL
• TUNNEL_ENV - Environment (dev/prod)
• TUNNEL_DEBUG - Enable debug logging

Custom Worker URL

export TUNNEL_WORKER_URL="wss://your-worker.workers.dev"
tunnel agent --id my-server @all

Services

Built-in Services

• @all - All services (exec, term, socks5)
• @exec - Remote command execution
• @term - Remote terminal
• @socks5 - SOCKS5 proxy

Port Forwarding

# Forward local HTTP service
tunnel agent --id my-server myapi:8080:http

# Forward local TCP service  
tunnel agent --id my-server mysql:3306:tcp

HTTP Forward (支持 HTTP 和 WebSocket)

HTTP forward 类型统一支持 HTTP 请求和 WebSocket 升级：

# 启动 Agent，转发本地 HTTP/WebSocket 服务
tunnel agent --id my-server myservice:8080:http

访问方式：

• 子域名模式: https://myservice-tun.your-domain.com/path
• 路径模式: https://your-domain.com/http/myservice/path

本地地址自动替换：

对于返回本地地址的服务（如 Chrome DevTools Protocol），Agent 会自动将 JSON 响应中的 127.0.0.1:port 替换为占位符，Worker 再替换为公网域名。

示例 - 连接远程 CDP 浏览器：

from playwright.sync_api import sync_playwright

# 启动 Agent: tunnel agent --id browser orbita:9222:http

with sync_playwright() as p:
    # 使用 https:// (Playwright 会自动获取 /json/version)
    browser = p.chromium.connect_over_cdp("https://orbita-tun.your-domain.com")
    page = browser.new_page()
    page.goto("https://example.com")
    browser.close()

Development

# Clone repository
git clone https://github.com/yourusername/tunnel-v4.git
cd tunnel-v4

# Install in development mode
export TUNNEL_DEV=1
pip install -e .

# Run agent (development uses tunnel4 command)
tunnel4 agent --id test @all

License

MIT License

Links

• Documentation: https://github.com/yourusername/tunnel-v4/docs
• Issues: https://github.com/yourusername/tunnel-v4/issues