High-performance HTTP / SOCKS5 proxy gateway for Linux and Windows. Five startup modes, optional external auth and traffic APIs.
Download prebuilt Linux and Windows binaries from GitHub. No compilation required.
joyproxy-gui.exe includes a desktop UI; joyproxy.exe is the command-line gateway.
joyproxy-gui.exe offers a visual interface for listen port, auth modes, start/stop controls, and live logs โ no command line required.
Configure listen port, local IP, proxy type, and open / whitelist / password modes in one place.
Start, stop, and save config with clear running status feedback.
Watch proxy activity in real time without opening a separate terminal.
Run ./joyproxy sps -h to show all flags. Common options:
| Flag | Required | Description |
|---|---|---|
-S | No | Upstream relay type: http or socks5 (default http) |
-p | Yes | Listen port(s), e.g. :8080 or :5001-5999 |
-g | Recommended | Public IP of this server; used as local_addr when calling auth API |
-parent | No | Default upstream URL if auth API does not return upstream |
--auth-url | No | External auth API URL (optional) |
--auth-nouser | No | Clients do not send username/password; API decides per connection |
--auth-cache | No | Auth success cache TTL in seconds |
--auth-fail-cache | No | Auth failure cache TTL in seconds |
--traffic-url | No | External traffic reporting API URL (optional) |
--daemon | No | Run in background (shell returns immediately) |
--forever | No | With --daemon: auto-restart worker on crash |
--no-detach | No | With --daemon: stay attached (use with systemd) |
--verbose | No | Full logs |
--quiet | No | Errors only |
--max-conns-rate | No | Global max new connections per second (0 = unlimited) |
--sniff-domain | No | Sniff TLS SNI on HTTP CONNECT |
./joyproxy sps -h
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP"Production-ready proxy gateway for your infrastructure
HTTP and SOCKS5 on configurable single port or port range.
Open proxy, whitelist API, username/password, or full external auth API.
Optional async traffic reporting when connections end.
Per-user connection limits, bandwidth caps, and global connection rate limit.
Background mode with auto-restart for production deployments.
Optional domain sniffing on HTTP CONNECT.
Choose the mode that fits your deployment
No --auth-url. Anyone who can reach the port may use the proxy without credentials.
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP"Use --auth-nouser + --auth-url. Clients send no password; your API decides allow/deny per connection (IP whitelist, target whitelist, etc.).
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP" \
--auth-nouser --auth-url "https://your-api.example.com/auth"Do not use --auth-nouser. Clients must send Proxy-Authorization (HTTP) or SOCKS5 credentials. Returns 407 if missing. Without --auth-url, credentials are only checked locally (non-empty).
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP"Optional --auth-url sends an HTTP GET to your endpoint for each connection. Combine with or without --auth-nouser.
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP" \
--auth-url "https://your-api.example.com/auth"Optional --traffic-url sends an async HTTP GET when each connection ends. Your API should return 204 No Content. Can be combined with auth API.
./joyproxy sps -S http -p ":8080" -g "YOUR_PUBLIC_IP" \
--auth-nouser --traffic-url "https://your-api.example.com/traffic"When --auth-url is set, joyproxy sends an HTTP GET for each connection with these query parameters:
| Parameter | Description |
|---|---|
user | Client username (empty if --auth-nouser) |
pass | Client password |
client_addr | Client address IP:port |
local_addr | Proxy listen address IP:port (from -g + listen port) |
target | Destination: HTTP URL or host:port for SOCKS5 |
service | http or socks |
sps | Always 1 |
Your API should respond with 200 or 204 and header upstream: http://... or socks5://... to allow. Return upstream: ERR or non-200/204 to deny (client gets 503, or 407/429 via X-Joyproxy-Reject-Status / X-Joyproxy-Deny).
| Response Header | Description |
|---|---|
upstream | Upstream proxy URL for this connection |
outgoing | Bind source IP hint |
userconns / ipconns | Max concurrent connections (per user) |
userrate / iprate | Per-connection bandwidth bytes/s (per user) |
userqps / ipqps | Max new connections per second (per user) |
When --traffic-url is set, joyproxy sends an async HTTP GET when each connection ends. Your API should return 204 No Content.
| Parameter | Description |
|---|---|
act | traffic |
bytes | Total bytes transferred (up + down) |
client_addr | Client IP:port |
server_addr | Proxy service IP:port |
target_addr | Target host or IP:port |
username | Proxy auth username (if any) |
upstream | Upstream URL used (if any) |
out_local_addr | Outbound TCP local address |
out_remote_addr | Outbound TCP remote address |
id | http or socks |
sniff_domain | TLS SNI (only when --sniff-domain enabled) |
Use --daemon --forever for production. With systemd, add --no-detach so the main process does not exit immediately.
./joyproxy sps -S http -p ":5001-5999" -g "YOUR_PUBLIC_IP" \
--auth-nouser --daemon --forever
# systemd unit: add --no-detachClient connects to joyproxy-server; server optionally calls your auth API before relaying traffic.
Recent releases. Full list on GitHub.
Auth API must return socks5:// (not http://) for service=socks / SOCKS5 UDP sessions.
Download the binary, configure your startup mode, and start accepting connections.
Download Binary