supatunnel 0.1.0

Lightweight TCP tunnel over Supabase Broadcast

SupaTunnel

English · 中文指南

Lightweight TCP tunnel over Supabase broadcast channels with AES-GCM encryption, ACK-based retransmit, and rate control.

⚙️ Features

• tunnel_uuid + sid isolation keeps concurrent local connections from interfering.
• AES-GCM protects payload confidentiality and integrity (secret is derived from your password).
• ACK + timeout retransmit makes the broadcast layer behave more like a reliable stream.
• Per-session token-bucket rate limiter (--rate-kbps).
• Installable CLI (supatunnel) via pip install -e . or registry publish.

🧱 Installation

git clone https://github.com/your-org/marx_supabase_tunnel.git
cd marx_supabase_tunnel
pip install -e .

🧩 Configuration

Export the following environment variables (see .env.example for templates) before running the CLI.

export SUPATUNNEL_URL="https://your-project.supabase.co"
export SUPATUNNEL_KEY="your-anon-key"
export SUPATUNNEL_ROOM="supa_tunnel_default"
export SUPATUNNEL_TUNNEL_UUID="7f3e9f5c-1a4d-4b2a-b3d5-2c4f9a8e1f6e"
export SUPATUNNEL_SECRET="a-strong-secret"

Optional tuning:

• SUPATUNNEL_RATE_KBPS: kilobytes per second limit (default 0 = unlimited)
• SUPATUNNEL_CHUNK_BYTES: chunk size per send (default 16384)
• SUPATUNNEL_RTO_MS: retransmit timeout (default 800)
• SUPATUNNEL_MAX_RETRIES: retransmit attempts (default 5)
• SUPATUNNEL_TARGET_HOST/PORT: server forwarding target
• SUPATUNNEL_LISTEN_HOST/PORT: client local listen endpoint

🚀 Usage

1. Server machine (where the target service runs):

   supatunnel server --target-host 127.0.0.1 --target-port 80
   

   • Starts a Supabase broadcast listener, opens the local target, and waits for client tunnels.

2. Client machine (your access point):

   supatunnel client --listen-host 127.0.0.1 --listen-port 8080
   

   • Listens locally and forwards the traffic over Supabase using the configured tunnel ID.
   • Access http://127.0.0.1:8080 to reach the remote service.

🧪 Health & debugging

• supatunnel --help shows all flags.
• Run supatunnel client server --rate-kbps 50 to exercise rate limiting.
• Secrets must match on both ends; mismatched secrets fail with decrypt errors.
• The tool prints session lifecycle logs (OPEN, DATA, ACK, CLOSE).

🏗️ Advanced topics

• Use distinct SUPATUNNEL_TUNNEL_UUID values for multiple tunnels even within the same room.
• SUPATUNNEL_ROOM lets you isolate groups of tunnels inside Supabase if needed.
• Drop-in AES key rotation: change SUPATUNNEL_SECRET and coordinate reconnects.
• The code keeps unacknowledged packets in memory until they are ACKed; tune --max-retries to avoid stuck sessions.

⚠️ 当前不支持

• UDP 流量，目前仅转发 TCP。
• 不提供本地 NAT 穿透或端口映射逻辑；数据必须依赖 Supabase 广播通道完成转发。
• 没有图形化界面，所有操作通过命令行与日志完成。

🧭 Research history

Older prototypes live in the research/ directory (see research/README.md). Production entrypoint is supatunnel in supatunnel/cli.py.

---

Need more control? Add --rate-kbps per session, or drop into the source for custom broadcast hooks.