Bethrou

A simple peer-to-peer proxy network built on libp2p

---

📚 Documentation

Read the full documentation →

This README provides a quick overview. For comprehensive guides, tutorials, and API references, visit our documentation site.

What is Bethrou?

Bethrou is a peer-to-peer proxy network that allows you to route your internet traffic through trusted exit nodes using a private network built on libp2p. It's an MVP (Minimum Viable Product) designed to demonstrate decentralized VPN-like functionality.

Key Features

• Private Networks: Uses pre-shared keys (PSK) for network isolation
• P2P Architecture: Built on libp2p for robust peer-to-peer communication
• SOCKS5 Proxy: Local SOCKS5 server for easy browser/application integration
• NAT Traversal: Support for relay nodes to handle NAT and firewall issues
• Node Discovery: Redis-based pub/sub for dynamic node discovery
• Load Balancing: Multiple routing strategies (random, round-robin, fastest)

How It Works

flowchart LR
      App[Your Browser or App] -- SOCKS5 --> Client[Bethrou Client]
      Client -- libp2p --> Node[Bethrou Exit Node]
      Client -.->|Redis Pub/Sub| Discovery[Node Discovery]

Loading

1. Client starts and loads exit node addresses (static or via discovery)
2. Client creates a SOCKS5 proxy server on localhost:1080
3. Applications connect to the SOCKS5 proxy
4. Client establishes libp2p connections to exit nodes
5. Proxy requests are forwarded through libp2p streams to exit nodes
6. Exit nodes make actual TCP connections to destination addresses
7. Traffic flows: App → SOCKS5 → libp2p → Exit Node → Internet

Use Cases

• Privacy: Route traffic through trusted nodes you control
• Testing: Test applications from different network locations
• Development: Create isolated network environments for testing
• Learning: Understand P2P networking and libp2p architecture

Installation

Prerequisites

Before installing Bethrou, ensure you have the following:

• Go 1.24.7 or higher - Download Go
• Git - For cloning the repository
• Redis (optional) - For node discovery features
• Docker/Podman (optional) - For containerized deployments
• OpenSSL - For generating network keys

Build from Source

Clone the repository and build the binaries:

# Clone the repository
git clone https://github.com/henrybarreto/bethrou.git
cd bethrou

# Build the node
cd node
go build -o bethrou-node main.go

# Build the client
cd ../client
go build -o bethrou-client main.go

Using Docker

Pull the pre-built image from Docker Hub:

For the node:

docker pull henrybarreto/bethrou-node:latest

For the client:

docker pull henrybarreto/bethrou-client:latest

Or build the image locally:

For the node:

# Build from repository root
docker build -f ./node/Containerfile -t bethrou-node .

For the client:

# Build from repository root
docker build -f ./client/Containerfile -t bethrou-client .

Generate Network Key

All nodes in a Bethrou network must share the same pre-shared key (PSK). Generate one:

echo "/key/swarm/psk/1.0.0/" > network.key
echo "/base16/" >> network.key
openssl rand -hex 32 >> network.key

This creates a network.key file that looks like:

/key/swarm/psk/1.0.0/
/base16/
abc123def456...

Warning

Keep your network.key file secure! Anyone with this key can join your private network. Never commit it to version control.

Copy this file to:

• The directory where you run the node
• The directory where you run the client
• All machines that will participate in your network

Basic Example Usage

Here's a minimal example to get started in seconds (assumes you have Go installed and a network.key):

Run the Node

cd node
go run main.go start
# Output: Peer ID: 12D3KooW... (copy this)

Create Client Config

Create client/client.yaml:

key: "network.key"

server:
  listen: "127.0.0.1:1080"
  auth: false

routing:
  strategy: random
  health: 30s
  timeout: 10s

nodes:
  - id: 12D3KooWRmF8HJnQyW4pqV...  # Paste the Peer ID from Terminal 1
    addrs:
      - /ip4/127.0.0.1/tcp/4000/p2p/12D3KooWRmF8HJnQyW4pqV...

discovery:
  enabled: false

log:
  level: info
  format: text

Run the Client

cd client
go run main.go connect --config client.yaml
# Output: SOCKS5 server listening on 127.0.0.1:1080

Test It

# Test with curl through the SOCKS5 proxy
curl --socks5 127.0.0.1:1080 https://ifconfig.me

# Or configure your browser:
# Proxy: 127.0.0.1:1080 (SOCKS5)

That's it! Your traffic is now routing through the Bethrou node. 🚀

Contributing

This is an early-stage project. Contributions, ideas, and feedback are welcome!

License

MIT License - see LICENSE file for details