Alpha software: ProxyTuner is under active development. Do not use it for production traffic, sensitive workspaces, or security-critical workloads. Review the configuration and test every proxy before relying on it.
ProxyTuner is a Python CLI that routes network connections through multiple SOCKS5, HTTP CONNECT, or direct outbounds using flexible rules. Run one local proxy, then send different destinations through different upstream proxies for practical split tunneling and proxy chaining workflows.
Use it as a multi-proxy router, rule-based proxy manager, local SOCKS5 proxy, or HTTP CONNECT proxy. Rules can match domains, IP addresses and CIDR ranges, ports, process names, process paths, and regular expressions.
Most proxy clients apply one proxy to an entire application or system. ProxyTuner lets you define routing policies such as:
- Send browser traffic or selected domains through a SOCKS5 VPN.
- Keep private and local network ranges on a direct connection.
- Route corporate, regional, or development traffic through a dedicated HTTP proxy.
- Combine domain, IP, port, and process conditions with first-match-wins priority.
- Inspect configuration, test upstream connectivity, monitor statistics, and diagnose prerequisites from the terminal.
Example routing policy:
Firefox ──► *.example.com ──► VPN Proxy (SOCKS5)
Chrome ──► *.video.example ──► Streaming Proxy (HTTP)
curl ──► 10.0.0.0/8 ──► Direct connection
Other ──► * ──► Work Proxy (SOCKS5)
- Multiple upstream outbounds: SOCKS5, HTTP CONNECT, and direct connections.
- Rule-based routing: Priority-ordered rules with AND logic between match fields and OR logic within list fields.
- Domain routing: Wildcard patterns such as
*.example.comand domain regular expressions. - IP routing: Exact IPs, IPv4/IPv6 CIDR ranges, and IP regular expressions.
- Port routing: Exact ports and port ranges.
- Process-aware rules: Process names and executable paths are modeled for platform interception support.
- Local proxy server: Accepts both SOCKS5 and HTTP CONNECT clients on the same listener, with protocol auto-detection.
- Authenticated proxies: Optional username/password authentication for SOCKS5 and HTTP outbounds.
- Async forwarding:
asyncio-based connections, bidirectional relay, retries, pooling, DNS caching, and per-outbound statistics. - Operations CLI: Setup wizard, config validation, hot reload on Unix, shell completions, logs, live monitoring, benchmarking, and
doctordiagnostics. - Cross-platform codebase: Local proxy mode is Python-based; Linux and Windows transparent interception backends are under active development.
Requires Python 3.10 or newer.
python -m pip install proxy-tunerFor development from source:
git clone https://github.com/HoomanJ/ProxyTuner.git
cd ProxyTuner
python -m pip install -e ".[dev]"proxy-tuner outbound add vpn \
--type socks5 \
--host 127.0.0.1 \
--port 1080
proxy-tuner outbound add work \
--type http \
--host proxy.example.net \
--port 8080 \
--username my-user \
--password my-passwordTest an outbound before using it:
proxy-tuner outbound test vpn
proxy-tuner outbound listProxy credentials are stored in the local JSON configuration file. Avoid placing real credentials in shell history when possible; use
proxy-tuner config editor another secure workflow.
Rules with lower priority numbers are evaluated first. The built-in direct outbound is always available and does not need to be added.
# Keep private networks direct.
proxy-tuner rule add private-network \
--ip-cidr "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.0/8" \
--outbound direct \
--priority 5
# Route browser destinations through the SOCKS5 VPN.
proxy-tuner rule add browser-sites \
--domain "*.example.com,*.example.org" \
--outbound vpn \
--priority 10
# Route HTTPS traffic not caught by earlier rules through the work proxy.
proxy-tuner rule add work-https \
--port 443 \
--outbound work \
--priority 20
# Optional catch-all rule.
proxy-tuner rule add default \
--outbound direct \
--priority 100proxy-tuner start --foregroundThe default listener is 127.0.0.1:10808. Configure an application or command to use it as a SOCKS5 or HTTP proxy:
# SOCKS5 with hostname resolution through the proxy.
curl --proxy socks5h://127.0.0.1:10808 https://example.com
# HTTP CONNECT proxy.
curl --proxy http://127.0.0.1:10808 https://example.comIn another terminal, inspect the service:
proxy-tuner status
proxy-tuner stats
proxy-tuner monitorFor daemon-style operation on supported Unix environments:
proxy-tuner start
proxy-tuner status
proxy-tuner reload
proxy-tuner stopEvery non-empty field in a rule must match. Values inside one field are alternatives.
| CLI option | Example | Matches |
|---|---|---|
--process |
firefox,chrome |
Process name |
--process-path |
/opt/apps/* |
Executable path glob |
--domain |
*.example.com |
Domain wildcard |
--domain-regex |
.*\\.cdn\\..* |
Domain regular expression |
--ip |
8.8.8.8 |
Exact IP address |
--ip-cidr |
10.0.0.0/8 |
IPv4 or IPv6 network range |
--ip-regex |
^10\\. |
IP regular expression |
--port |
80,443 |
Exact destination port |
--port-range |
8000-9000 |
Destination port range |
--url-regex |
https?://.* |
URL regular expression |
Combine matchers for precise policies:
# All conditions are AND-combined.
proxy-tuner rule add firefox-google \
--process firefox \
--domain "*.google.com" \
--port 443 \
--outbound vpn \
--priority 10Review and test the rule order:
proxy-tuner rule list
proxy-tuner rule test firefox-google --process firefox --domain google.com --port 443
proxy-tuner rule move firefox-google --priority 5
proxy-tuner rule disable firefox-google
proxy-tuner rule enable firefox-googleThe local SOCKS5/HTTP forwarder receives the destination requested by the client, so domain, IP, and port rules are the most useful in the current local-proxy workflow. Process and process-path matching depend on platform-level interception, which is still being implemented. URL-regex matching is available in the rule engine but is not populated by every proxy protocol path yet.
| Type | CLI configuration | Typical use |
|---|---|---|
| SOCKS5 | --type socks5 --host HOST --port PORT |
VPN tunnels, SSH dynamic forwarding, privacy proxies |
| HTTP CONNECT | --type http --host HOST --port PORT |
Corporate, caching, or regional HTTP proxies |
| Direct | Use the special outbound name direct |
Bypass an upstream proxy |
Application
│ SOCKS5 or HTTP CONNECT
▼
127.0.0.1:10808
│
▼
ProxyTuner rule engine
│ first matching rule
├──► Direct connection
├──► SOCKS5 upstream
└──► HTTP CONNECT upstream
ProxyTuner loads a JSON configuration, compiles routing rules, evaluates each incoming connection, connects through the selected outbound, and relays bytes in both directions. The local forwarder supports concurrent connections with asynchronous I/O and connection statistics.
| Platform | Local SOCKS5/HTTP proxy | Transparent interception | Notes |
|---|---|---|---|
| Linux | Supported | Experimental / in progress | TUN and iptables components require root and system networking tools |
| Windows | Supported | Experimental / in progress | WinDivert and Administrator privileges are required for interception |
| macOS | Supported | Not complete | Use the local proxy and configure applications manually |
The reliable cross-platform workflow today is to run the local forwarder and configure each application to use 127.0.0.1:10808. Transparent system-wide routing is not yet production-ready.
ProxyTuner creates a JSON config file on first use:
- Linux:
~/.config/proxy-tuner/config.json - macOS:
~/Library/Application Support/proxy-tuner/config.json - Windows:
%APPDATA%\\proxy-tuner\\config.json
Useful configuration commands:
proxy-tuner config path
proxy-tuner config show
proxy-tuner config validate
proxy-tuner config set settings.listen_port 10808
proxy-tuner config edit
proxy-tuner config initUse a custom config path for isolated profiles or testing:
proxy-tuner --config ./proxy-tuner.json config validate
proxy-tuner --config ./proxy-tuner.json statusProxyTuner writes restrictive 0600 permissions for config files on Unix systems because proxy credentials may be stored there.
# Global options
proxy-tuner --help
proxy-tuner --version
proxy-tuner --config PATH <command>
# Upstream proxies
proxy-tuner outbound add NAME --type socks5|http --host HOST --port PORT
proxy-tuner outbound list
proxy-tuner outbound test NAME
proxy-tuner outbound remove NAME
# Rule management
proxy-tuner rule add NAME --outbound OUTBOUND [MATCH_OPTIONS]
proxy-tuner rule list
proxy-tuner rule test NAME [OPTIONS]
proxy-tuner rule move NAME --priority NUMBER
proxy-tuner rule enable NAME
proxy-tuner rule disable NAME
proxy-tuner rule remove NAME
# Service and diagnostics
proxy-tuner start [--foreground] [--log-level LEVEL]
proxy-tuner stop
proxy-tuner status
proxy-tuner reload
proxy-tuner doctor
proxy-tuner stats [--reset]
proxy-tuner monitor
proxy-tuner bench
proxy-tuner logs [--lines NUMBER] [--follow]
proxy-tuner setup
# Shell completion
proxy-tuner completions bash
proxy-tuner completions zsh
proxy-tuner completions fishRun proxy-tuner COMMAND --help for the complete options for any command.
proxy-tuner doctorproxy-tuner outbound test vpn
proxy-tuner logs --lines 100
proxy-tuner start --foreground --log-level debugproxy-tuner rule list
proxy-tuner rule test RULE_NAME --domain example.com --port 443
proxy-tuner config validateConfirm that the rule has the intended priority, is enabled, and references an existing outbound. Remember that a local proxy cannot infer the originating application process from every client connection.
Use the local proxy mode first. Transparent interception requires elevated privileges and platform-specific dependencies:
- Linux:
iptables/iproute2, a usable TUN device, and root orsudo. - Windows: WinDivert and an Administrator shell.
git clone https://github.com/HoomanJ/ProxyTuner.git
cd ProxyTuner
python -m pip install -e ".[dev]"
# Run the test suite
pytest tests/ -v
# Lint and type-check
ruff check src/ tests/
mypy src/proxy_tuner/ --ignore-missing-importsSee the contribution guide, usage guide, configuration reference, and architecture notes for more detail.
ProxyTuner is relevant to developers searching for a Python proxy router, multi-proxy manager, SOCKS5 routing, HTTP CONNECT proxy, split tunneling, per-domain proxy, per-IP proxy, CIDR-based routing, per-port routing, proxy chaining, local proxy server, or rule-based network traffic routing.
MIT