Quick Start

Prerequisites

• Linux with net.ipv6.ip_nonlocal_bind=1 and iproute2 installed
• IPv6 connectivity — either native, or free from Cloudflare WARP or a tunnel broker, both of which need only IPv4 on the host
• Node.js 20+ (for manual deployment)
• Docker (for container deployment)

Docker (recommended)

# On the HOST first (network_mode: host cannot set this from the container)
sudo sysctl -w net.ipv6.ip_nonlocal_bind=1
echo net.ipv6.ip_nonlocal_bind=1 | sudo tee /etc/sysctl.d/99-ipv6-proxy.conf

git clone https://github.com/emptysuns/ipv6-subnet-proxy.git
cd ipv6-subnet-proxy

# Edit docker/docker-compose.yml → API_KEY (and WARP_ENABLED / HE_* if needed)
docker compose -f docker/docker-compose.yml up -d --build

Manual

# Clone and install
git clone https://github.com/emptysuns/ipv6-subnet-proxy.git
cd ipv6-subnet-proxy
npm install
npm run build

# Set required API key (subnets are auto-detected from host interfaces)
export API_KEY=your-secret-api-key

# Optional: manually specify a subnet if auto-detection fails
export DEFAULT_SUBNET=2001:db8:1::/64

# Start
npm start

On startup, the program auto-detects IPv6 subnets from the host's network interfaces. You'll see log lines like:

info: Auto-registered detected IPv6 subnet { cidr: "2001:db8:1::/64" }

Verify

# Health check
curl http://localhost:3000/health

# Create a user — all active subnets are automatically bound
curl -X POST http://localhost:3000/api/v1/users \
  -H "X-API-Key: your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secret123"}'

Users are automatically bound to all registered subnets on creation — no manual binding needed. You can still manage subnets and bindings via the API for advanced use cases.

Add a subnet

curl -X POST http://localhost:3000/api/v1/subnets
-H "X-API-Key: your-secret-api-key"
-H "Content-Type: application/json"
-d '{"cidr": "2001:db8:1::/64"}'

Bind user to subnet

curl -X POST http://localhost:3000/api/v1/users/<USER_ID>/bindings
-H "X-API-Key: your-secret-api-key"
-H "Content-Type: application/json"
-d '{"subnet_id": "<SUBNET_ID>"}'

Now use SOCKS5 proxy at `localhost:1080` with username `alice` and password `secret123`.

---