Reticulum TCP Bridge

A vibe coded (by Gemini 3 Pro), protocol-agnostic TCP tunnel that runs over the Reticulum Network Stack.

This tool allows you to bridge any TCP connection (SSH, VNC, HTTP, etc.) over a Reticulum mesh network. It supports persistent identities, access control (whitelisting), and efficient binary stream buffering.

It is designed to be lightweight and uses the shared Reticulum instance (rnsd) by default, making it ideal for running on established nodes without conflict.

Features

• Protocol Agnostic: Tunnel SSH, Web, or any raw TCP traffic.
• Shared Instance: Connects to your running rnsd (doesn't hog interfaces).
• Access Control: Server-side whitelisting to restrict access to specific client identities.
• Persistent Identities: Save/Load identities so your Destination Hash doesn't change.
• Custom Bindings: Configurable listen IPs (localhost or 0.0.0.0).
• Zero Config Transport: Uses Reticulum's automatic pathfinding and announcements.

Prerequisites

You must have a working installation of Reticulum. Note: This script requires a running Reticulum daemon (rnsd) on the system.

Usage

1. Setup Identities (First Run)

To ensure your Server and Client have permanent addresses (Destination Hashes) that don't change when you restart the script, you should generate Identity files first.

On the Client Machine: Run the script once to generate an identity file.

python3 rns_tcp_bridge.py -c --dest <ANY_DUMMY_HASH> --id ./client_identity

Take note of the "Loaded Identity" hash printed in the logs. You will need this to whitelist yourself on the server.

On the Server Machine: Run the script once to generate the server identity.

python3 rns_tcp_bridge.py -s --id ./server_identity

Take note of the "Destination Hash" printed in the logs. You will need this to tell the client where to connect.

---

2. Running the Server (Exit Node)

The server sits on the machine that can reach the target service (e.g., your router or a web server).

Example: Forwarding SSH (Port 22) This command listens on the Mesh and forwards traffic to 127.0.0.1:22. It also restricts access so only your specific client can connect.

python3 rns_tcp_bridge.py -s \
    --target 127.0.0.1 \
    --target-port 22 \
    --id ./server_identity \
    --allowed <YOUR_CLIENT_IDENTITY_HASH>

3. Running the Client (Entry Node)

The client runs on your local machine (e.g., your laptop). It listens on a local port and forwards traffic into the mesh.

Example: Exposing the remote SSH on local port 2222

python3 rns_tcp_bridge.py -c \
    --dest <SERVER_DESTINATION_HASH> \
    --bind-port 2222 \
    --id ./client_identity

4. Connect!

Once the bridge is established, you can connect to your local port as if it were the remote machine:

ssh -p 2222 user@localhost

---

Command Line Arguments

Argument	Description	Mode
-s, --server	Run in Server Mode (Exit Node).	Server
-c, --client	Run in Client Mode (Entry Node).	Client
--id <path>	Path to identity file. Creates one if it doesn't exist.	Both
--target <ip>	IP address to forward traffic to (Default: 127.0.0.1).	Server
--target-port <port>	Port to forward traffic to (Default: 22).	Server
--allowed <hash>	Space separated list of allowed Client Identity Hashes.	Server
--dest <hash>	The Destination Hash of the Server.	Client
--bind-port <port>	Local port to listen on (Default: 2222).	Client
--listen-ip <ip>	Local interface to bind to (Default: 127.0.0.1).	Client

Advanced: Exposing to LAN

By default, the client binds to 127.0.0.1 for security. If you want other computers on your physical LAN to be able to use the bridge, you can bind to 0.0.0.0.

python3 rns_tcp_bridge.py -c --dest <HASH> --bind-port 2222 --listen-ip 0.0.0.0

Security Note

If you run the server without the --allowed flag, anyone on the Reticulum network can connect to your forwarded port. Always use an Identity file and whitelist your client's hash for private services.