IPv6 Subnet Proxy

English | 中文

SOCKS5 proxy that spreads outbound connections across IPv6 addresses from managed subnets. Built-in free IPv6 via Cloudflare WARP (no signup) or a 6in4 tunnel broker, plus a REST management API, SQLite persistence, per-user rate limits, traffic stats, and audit logs.

Full docs (EN / 中文): https://emptysuns.github.io/ipv6-subnet-proxy/

---

Quick start (Docker)

# On the HOST (required with network_mode: host — container cannot set this)
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

# Optional free IPv6 if the host has none:
#   sudo modprobe wireguard   # for WARP
#   sudo modprobe sit         # for a 6in4 tunnel broker

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

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

curl http://localhost:3000/health

curl -X POST http://localhost:3000/api/v1/users \
  -H "X-API-Key: changeme" \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'

SOCKS5: localhost:1080, user alice / secret123.

Host networking is required. Compose sysctls: do nothing under network_mode: host — set ip_nonlocal_bind on the host as above.

No IPv6 on the host?

	Cloudflare WARP	Tunnel broker (6in4)
Signup	None	Free account at tunnelbroker.net
What you get	One address per device	Routed /48
Kernel	modprobe wireguard	modprobe sit
Env	WARP_ENABLED=true	HE_TUNNEL_ID + credentials

Details: docs → No IPv6

Manual install

npm install && npm run build
export API_KEY=your-secret-api-key
# export DEFAULT_SUBNET=2001:db8:1::/64   # optional; auto-detects interfaces
npm start

Node 20+, Linux, iproute2, net.ipv6.ip_nonlocal_bind=1.

Configuration

All config is environment variables. Common ones:

Variable	Default	Description
API_KEY	(required)	REST API key (X-API-Key)
SOCKS5_PORT	1080	Proxy listen port
API_PORT	3000	REST API port
DEFAULT_SUBNET	—	Register a CIDR on startup
WARP_ENABLED	false	Free IPv6 via Cloudflare WARP
WARP_ACCOUNTS	1	WARP devices (= egress addresses)
HE_TUNNEL_ID	—	tunnelbroker.net tunnel id
HE_TUNNEL_USERNAME	—	HE account
HE_TUNNEL_UPDATE_KEY	—	Per-tunnel update key (preferred over password)
LOG_LEVEL	info	trace…fatal

Full list: docs → Configuration

Docs & development

npm run docs:dev      # local VitePress
npm run docs:build
npm test
npm run build

Image: ghcr.io/emptysuns/ipv6-subnet-proxy (tag v*).

License

MIT