Proxy Bridge

Proxy Bridge exposes multiple upstream SOCKS5 proxies through a single SOCKS5 endpoint. Applications select an upstream by proxy ID using the SOCKS username and authenticate with a shared application password.

Written in Go, it uses persistent yamux sessions over TCP to carry concurrent connections. The client connects to the server directly or through a TCP tunnel; both can also run on the same host.

How it works

flowchart LR
    app["Application"]

    subgraph bridge["Proxy Bridge"]
        client["Client<br/>SOCKS5 endpoint"]
        server["Server<br/>Routes by proxy ID"]
    end

    subgraph upstreams["Upstream SOCKS5 proxies"]
        proxy1["proxy-1"]
        proxy2["proxy-2"]
    end

    destination["Destinations"]

    app -->|SOCKS5| client
    client -->|Multiplexed TCP| server
    server --> proxy1
    server --> proxy2
    proxy1 --> destination
    proxy2 --> destination

• Gateway host: runs proxy-client and exposes the SOCKS5 endpoint to applications.
• Upstream host: runs proxy-server where the upstream SOCKS5 proxies are reachable.

Proxy Bridge connects to existing upstream proxies; it does not create them.

Features

• Select named upstream proxies through one application-facing port.
• Multiplex concurrent connections over a persistent session pool.
• Configure connection limits, timeouts, and automatic session reconnection.
• Record bandwidth totals by minute, hour, and day.
• Apply bandwidth limits globally, by connection leg, or per upstream proxy.

Supports SOCKS5 username/password authentication and TCP CONNECT. UDP ASSOCIATE and BIND are unsupported. Unknown proxy IDs fail without falling back to another upstream. The shared application password grants access to every configured ID.

Getting started

Requirements: Go 1.27.1 or later to build, existing SOCKS5 upstreams, and TCP connectivity from the client to the server. Compiled binaries do not require Go on the deployment hosts.

Build from the repository root and copy the example configurations:

mkdir -p bin
go build -trimpath -o bin/proxy-server ./server
go build -trimpath -o bin/proxy-client ./client
cp server/config.example.json server/config.json
cp client/config.example.json client/config.json

Before starting:

1. Set the upstream proxy addresses and credentials in server/config.json.
2. Set the same random bridge_token in both Go configs and a separate application password in the client config. Replace all example secrets.
3. Set the client's bridge_address to the server's reachable listen address or a tunnel endpoint. For a local setup, use 127.0.0.1:18081.

The bridge token authenticates sessions. Use an encrypted network or tunnel when carrying bridge traffic over untrusted networks; the bridge protocol uses plain TCP.

Follow the setup guide for local and remote connections, credentials, startup commands, and optional tunnel deployment.

Usage

From the gateway host, select a configured proxy ID as the SOCKS username and use the application password from client/config.json:

curl --noproxy '' --proxy 'socks5h://proxy-1:[email protected]:8080' https://example.com
curl --noproxy '' --proxy 'socks5h://proxy-2:[email protected]:8080' https://example.com

socks5h forwards destination hostnames to the upstream proxy for resolution. URL-encode credentials that contain URL-special characters.

Documentation

• Setup and deployment — build, configure, connect, and run the services.
• Configuration reference — settings, defaults, and validation rules.
• Bandwidth logging and limits — counters, log files, and rate controls.
• Architecture and runtime behavior — sessions, capacity, failure handling, and development checks.
• Troubleshooting — diagnose connection, authentication, and upstream failures.

Development

go test -race ./...
go vet ./...

Integration tests use local TCP connections and fake SOCKS5 upstreams. See the architecture guide for details.