NAT-Bridge

Network through P2P with no port fowarding
Latest Release »

Report Bug · Request Feature

Table of Contents

1. About
   • Built With
2. Getting Started
   • Prerequisites
   • Instructions to Run
   • Building to Executable
3. Usage
4. Roadmap
5. Contributing
6. License

About

A sweet and simple single command Node.js CLI tool for tunneling TCP and UDP traffic over a peer-to-peer (P2P) network using Hyperswarm. NAT-bridge allows you to expose local services to remote clients, bypassing NAT/firewall restrictions (no need for port fowarding).

Use Cases:

• You want to play minecraft with your friend but dont want to pay for a dedicated server or port foward.
• You Are working on a website and want testers to quickly be able to acsess it.
• You only want to expose a port to specific computers for networking.

NAT-bridge can be used for many things not descussed here.

(back to top)

Built With

• 
• 

(back to top)

Getting Started

Hyperswarm is made with node.js and can be run as such. However, if you prefer, It can also be downloaded as a windows executable here in which case it should just run out of the box.

Prerequisites

For this you will need the following:

• node

  winget install OpenJS.NodeJS

• npm

  npm install npm@latest -g

Instructions to Run

Follow these steps to run NAT-bridge

1. Clone the repo

   git clone https://github.com/Lawtro37/NAT-bridge.git

2. Install NPM packages

   npm install

3. Run this command

   node main.js

4. If you prefer you can run the launcher GUI via this command

   npm run launcher

(back to top)

Building to Executable

Follow these steps if you wish to build NAT-Bidge to an executable

Standalone EXE

npm run build

Launcher EXE

npm run build:launcher

Note that the launcher must be in the same or child directory as a nat-bridge.exe executable

There are currently no built in scripts for building to an executable for any operating system other than windows, though it can be done manualy through pkg.

Usage

To connect a device to another they must have the same bridge id. The "host" machine exposes a specified port with -e or --expose. Any "client" machines can connect to the host over peer to peer if they have the same bridge id. The "client can specify a port on their machine with -l or --listen that the tunnel will listen on.

Note that anyone with the same bridge id can connect to your device if you machine is operating as a "host", unless you specify a secret with --secret. Two hosts on the same bridge id can cause a variety of issues and may allow malicous hosts to trick "clients" inteded for your machine into to conneting to theirs.

No encryption is provided by NAT-bridge, that is the responsibility of the protocal running over the bridge.

node main.js <host|client> <bridge-id> [options]

or with a configuration

node main.js config <config-file>

Options

Option	Description	Default
-e, --expose <port>	Port to expose on host	8080
-l, --listen <port>	Port to listen on client	5000
-p, --protocol <type>	Protocol to tunnel: tcp, udp, both	tcp
-w, --warnings	Show common disconnect warnings
-v, --verbose	Enable verbose logging
-h, --help	Show help
--json	Structured JSON logs (disables spinner)
--secret <pass>	Enable mutual auth (HMAC challenge)
--status <port>	Start status server (JSON)
--max-streams <n>	Limit concurrent streams	256
--kbps <n>	Simple throttle per stream (0=unlimited)	unlimited
--tcp-retries <n>	TCP connect retry attempts	5
--tcp-retry-delay <ms>	Delay between retries (in miliseconds)	500ms
--no-tui	Disable the terminal UI
--no-fancy-logs	Disable colored and formatted logs
--skip-update-check	Don't check for updates on startup

Examples

Web Server Access

# Host: Share your local web server (localhost:3000) 
nat-bridge host webserver --expose 3000 --protocol tcp --verbose

# Client: Access the remote web server on your local port 8080
nat-bridge client webserver --listen 8080 --protocol tcp
# Now visit http://localhost:8080 to access the remote server

Game Server with Authentication

# Host: Expose Minecraft server with security
nat-bridge host minecraft --expose 25565 --protocol both --secret "gamenight2024"

# Client: Connect to the game server
nat-bridge client minecraft --listen 25565 --protocol tcp --secret "gamenight2024"
# Connect your Minecraft client to localhost:25565

Database Tunneling

# Host: Expose PostgreSQL database with monitoring
nat-bridge host database --expose 5432 --protocol tcp --status 9999 --max-streams 5

# Client: Connect to database through tunnel
nat-bridge client database --listen 5432 --protocol tcp
# Connect your database client to localhost:5432
# Check connection status at http://localhost:9999/status

Home Media Server

# Host: Share Plex/Jellyfin server with bandwidth limiting
nat-bridge host mediaserver --expose 32400 --protocol tcp --kbps 5000

# Client: Access media server remotely
nat-bridge client mediaserver --listen 32400 --protocol tcp

Configuration File Example

# Create config.json:
{
  "mode": "host",
  "bridgeId": "myservice",
  "exposedPort": 8080,
  "protocol": "tcp",
  "secret": "mysecret123",
  "verbose": true,
  "maxStreams": 10
}

# Use the config file:
nat-bridge config ./config.json

(back to top)

Roadmap

• Add a GUI Launcher
• Add a terminal UI
• Refactor so everything isnt in one file
• Add more visuals to the TUI
  • Upload and download visual graph
• Fix that bug where streams refuse to die when exiting for some reason
• Rework the handshake protocal
  • Rework the handshake protocal
  • Add Legacy Support
• Port to rust

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Feel free to fork, file issues, and submit pull requests! Any contributions that help make NAT-bridge more robust, secure, or user-friendly are welcome.

Top contributors:

(back to top)

License

Distributed under the GPL-3.0 License. See the LICENSE file for more information.

(back to top)

Made by Lawtro