GitHub - proxybasehq/socks5-bridge: A local HTTP-to-SOCKS5 proxy bridge for Chrome. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Uh oh!
There was an error while loading. Please reload this page.
proxybasehq
socks5-bridge
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>3 Commits<br>3 Commits
src
src
tests
tests
.gitignore
.gitignore
Cargo.lock
Cargo.lock
Cargo.toml
Cargo.toml
README.md
README.md
com.local.socks5-bridge.plist
com.local.socks5-bridge.plist
test_config.toml
test_config.toml
View all files
Repository files navigation
socks5-bridge
A local HTTP-to-SOCKS5 proxy bridge for Chrome.
Problem: Chrome doesn't support SOCKS5 username/password authentication, so you can't point it at socks5://user:pass@host:port and expect it to work.
Solution: socks5-bridge runs a local HTTP proxy on loopback. Chrome connects to it using HTTP proxy config it already understands, and the bridge handles the authenticated SOCKS5 upstream on Chrome's behalf.
Quick start
# Build<br>cargo build --release
# Create a config file (edit credentials + upstream host)<br>cp config.sample.toml config.toml
# Validate config<br>cargo run -- check --config config.toml
# Run in foreground<br>cargo run -- start --config config.toml --foreground
# Run as daemon (background)<br>cargo run -- start --config config.toml
CLI
Command<br>Description
start --config<br>Start the bridge (daemonizes by default; use --foreground to stay in terminal)
start --config --validate-only<br>Load and validate config, then exit
check --config<br>Validate config without opening any network listeners
test-upstream --config<br>Test the upstream SOCKS5 connection and auth path
status [--admin-port]<br>Query the admin API for runtime state
stop [--admin-port]<br>Gracefully shut down a running daemon via admin API
print-chrome-args --config<br>Print --proxy-server=... flags to pass to Chrome
Configuration
All options live in a single TOML file. Copy config.sample.toml and edit:
[listener]<br>host = "127.0.0.1"<br>port = 8899
[upstream]<br>type = "socks5"<br>host = "your-upstream.example.com"<br>port = 1080<br>username = "your-username"<br>password = "your-password"<br>connect_timeout_ms = 8000<br>auth_timeout_ms = 5000<br>command_timeout_ms = 8000<br>remote_dns = true
[policy]<br>allow_loopback_only = true<br>allow_private_destinations = false<br>allow_localhost_destinations = false<br>max_concurrent_connections = 256<br>idle_timeout_ms = 60000<br>graceful_shutdown_timeout_ms = 5000
[logging]<br>level = "info"<br>format = "json"<br># file = "/path/to/logfile.log"<br>redact_credentials = true
[health]<br>enable_admin_api = true<br>admin_host = "127.0.0.1"<br>admin_port = 8898<br>probe_host = "example.com"<br>probe_port = 443<br>probe_interval_ms = 30000
Key settings
remote_dns — when true (default), hostnames are sent to the upstream SOCKS5 server for resolution rather than resolved locally. This keeps DNS consistent with the upstream's view of the network.
allow_loopback_only — when true, the listener binds only to loopback. Set to false with extreme caution.
redact_credentials — strips username/password from log output.
Architecture
Chrome (HTTP proxy) → listener (loopback TCP) → HTTP proxy parser<br>→ policy check → SOCKS5 client (auth + connect) → upstream SOCKS5<br>→ relay (bidirectional copy)
Module<br>Role
listener<br>Binds TCP, accept loop, spawns per-connection handler
http_proxy<br>Parses HTTP proxy requests (GET + CONNECT), policy check, SOCKS5 connect, relay
socks5<br>SOCKS5 protocol types and handshake/connect client
relay<br>tokio::io::copy_bidirectional between client and upstream
policy<br>Destination allow/deny (loopback-only, private-range blocking)
session<br>Per-connection state machine and counters
admin_api<br>Axum HTTP server for health/metrics on admin port
config<br>TOML config loading and validation
logging<br>Tracing subscriber init (JSON or plain, optional file, credential redaction)
Chrome setup
Print the flags you need:
socks5-bridge print-chrome-args --config config.toml
Then launch Chrome with those flags, or...