https://github.com/nymtech/nym-bridges
https://github.com/nymtech/nym-bridges
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/nymtech/nym-bridges
- Owner: nymtech
- License: agpl-3.0
- Created: 2025-10-02T17:07:05.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-02-03T00:53:35.000Z (5 months ago)
- Last Synced: 2026-02-03T05:41:27.524Z (5 months ago)
- Language: Rust
- Size: 902 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Nym Transport Bridges
This repository implements and provides tooling for a pluggable transport system used to secure and
obfuscate [Nym VPN](https://github.com/nymtech/nym-vpn-client/) traffic. The
[nym-bridge](./nym-bridge/) is a server-side transparent forwarder accepting and unwrapping
obfuscated traffic to be passed on to a colocated [nym-node](https://github.com/nymtech/nym) entry
gateway.
The larger Nym system provides a secure distributed multi-hop VPN and mixnet.
⚠️⚠️ This repository is under active development and encodings, serialization formats, interfaces,
etc. are subject to change ⚠️⚠️
## Usage
#### Build
The nym-bridge binary runs the server side listener for the transports defined by the bridge
configuration. The binary can be built using:
```sh
cargo build --release -p nym-bridge -p bridge-cfg
# sudo cp target/release/nym-bridge /usr/local/bin/
```
#### Automatic Configuration
The [`bridge-cfg`](../bridge-cfg/) tool is provided to assist with key generation and configuration
management -- for more details on automatic configuration see
[`bridge-cfg/README.md`](../bridge-cfg/README.md).
This tool assumes that the `nym-bridge` is going to be run alongside a `nym-node`, but attempts to configure expected defaults if a nym-node config is not present.
```sh
# Try a dry run to preview the configuration changes / file locations
bridge-cfg --gen --dry-run
# Allow configuration changes to be persisted
bridge-cfg --gen
```
**Security Note:** After generating your bridge configuration, ensure proper file permissions to protect sensitive key material:
```sh
# Restrict config file to owner only (recommended for production)
sudo chmod 600 /etc/nym/bridges.toml
# Protect keys directory
sudo chmod 700 /etc/nym/keys
sudo chmod 600 /etc/nym/keys/*
```
**Refreshing Configuration:** If your server's public IPs change after initial setup, you can refresh the configuration:
```sh
# Re-detect public IPs while preserving existing keys
bridge-cfg --gen -i /etc/nym/bridges.toml -o /etc/nym/bridges.toml
```
Manual configuration instructions can be found in [`nym-bridge/README.md`](./nym-bridge/README.md)
#### Usage
```sh
$ nym-bridge -h
Usage: nym-bridge [OPTIONS]
Options:
-c, --config Provide a path to the configuration for launching server listeners [default: /etc/nym/default-nym-node/bridges.toml]
-h, --help Print help
$ nym-bridge -c ""
```
## Protocols
#### Quic
QUIC is a UDP-based, stream-multiplexing, connection-oriented, encrypted transport protocol that creates a stateful interaction between a client and server. The protocol published as [RFC 9000](https://www.rfc-editor.org/rfc/rfc9000.html).
This tool uses ed25519 keys to sign certificates for the TLS handshake used by Quic. The public (verifying) key is shared to clients as part of the node description and can be used to verify the server identity and secure a Quic TLS connection.
**TLS over TCP**
TLS over TCP is the most common protocol used across the public internet. It provides a connection-oriented, encrypted transport protocol.
This tool uses ed25519 keys to sign certificates for the TLS handshake. The public (verifying) key is shared to clients as part of the node description and can be used to verify the server identity and secure a TLS connection.
**[Future]** Shadowsocks | ssh | obfs4 | vmess | webrtc | ...
## Testing
A minimal docker test environment is provided for testing the tunneling and connection handling of
the nym-bridge binaries. The [`bridge-tools`](./bridge-tools/) are intended for use in this
environment.
See [`./test-env/`](./test-env/) for more details.