A tiny local HTTP/HTTPS proxy that automatically decides — on every request — whether to route through your workplace proxy or connect directly.
If you are like me and your laptop roams between an office network that requires a corporate proxy and home / cafés / anywhere that needs no proxy, you normally have to keep flipping HTTP_PROXY and per-app proxy settings every time you move. This tool removes that chore: your system points at one fixed local address forever, and the proxy figures out the rest by itself.
Your system always talks to http://127.0.0.1:3128. For each request the proxy probes (a quick TCP connect, cached for a few seconds) whether the configured upstream work proxy is reachable:
| Work proxy reachable? | Routing of the request |
|---|---|
| yes | forwarded via the work proxy |
| no | direct connection to target |
system -> 127.0.0.1:3128 --+-- (at work) --> proxy.example.com:8080 --> Internet
|
+-- (elsewhere) --> target host directly --> Internet
Because the probe is re-evaluated every few seconds, a session started in one place keeps working after you move somewhere else — the proxy switches mode on its own, with nothing to reconfigure on the system side.
It handles both CONNECT requests (HTTPS / tunnels) and plain HTTP.
- Python 3.7+ (standard library only — no third-party dependencies)
- Linux with a user systemd instance (for the auto-start service). On other systems you can simply run
work-proxy.pydirectly or under your own supervisor.
git clone https://github.com/<your-user>/auto-routing-proxy.git
cd auto-routing-proxy
./install.shThe installer copies the script to ~/.local/bin/, installs the systemd user unit, creates ~/.config/work-proxy/config from the template, and enables the service. Edit the upstream line in ~/.config/work-proxy/config with your real work proxy, then:
systemctl --user restart work-proxy# 1. Script
install -Dm755 work-proxy.py ~/.local/bin/work-proxy.py
# 2. Config
mkdir -p ~/.config/work-proxy
cp config.example ~/.config/work-proxy/config
$EDITOR ~/.config/work-proxy/config # set your upstream proxy
# 3. systemd user service
install -Dm644 work-proxy.service ~/.config/systemd/user/work-proxy.service
systemctl --user daemon-reload
systemctl --user enable --now work-proxyAdd to your shell rc (~/.bashrc, ~/.zshrc, …):
export HTTP_PROXY=http://127.0.0.1:3128
export HTTPS_PROXY=http://127.0.0.1:3128
export NO_PROXY=localhost,127.0.0.1,::1(GUI apps usually pick up these variables too, or set the same proxy in their own settings — pointing at 127.0.0.1:3128 once and never touching it again.)
If you've never configured a service before, follow these steps in order. It is assumed that you already ran ./install.sh (the quick install above).
You need two things from your IT department (or your browser's existing proxy settings): the proxy's host and its port. It looks like one of these:
proxy.mycompany.com port 8080
10.20.30.40 port 3128
Open the config file in a text editor:
nano ~/.config/work-proxy/config # or: emacs, gedit...Find the line starting with upstream = and replace the example with your host and port, separated by a colon. For example, if your proxy is proxy.mycompany.com on port 8080:
upstream = proxy.mycompany.com:8080Leave everything else as-is (the other lines start with #, which means they're comments — you can ignore them). Save and close the file (in nano: Ctrl+O, Enter, then Ctrl+X).
Tell the service to reload the config you just edited:
systemctl --user restart work-proxysystemctl --user status work-proxyYou want to see active (running) in green. Press q to exit that screen. The last log line tells you the current mode:
routing mode -> via <your-proxy>→ you're on the work network, traffic goes through the proxy.routing mode -> direct→ you're off the work network, traffic goes straight out.
So that programs actually send their traffic to the proxy, add these three lines to the end of your shell config file (~/.bashrc if you use bash, ~/.zshrc if you use zsh):
export HTTP_PROXY=http://127.0.0.1:3128
export HTTPS_PROXY=http://127.0.0.1:3128
export NO_PROXY=localhost,127.0.0.1,::1Then either open a new terminal, or run source ~/.bashrc (or source ~/.zshrc) to apply them.
curl -I https://www.google.comIf you get a response (a bunch of HTTP/... 200 headers), it works — both at the office and at home, with nothing left to change. From now on the service starts automatically every time you log in.
Did it hang or fail? See Troubleshooting below.
Settings live in ~/.config/work-proxy/config:
upstream = proxy.example.com:8080 # required: your work proxy host:port
# optional (defaults shown):
# listen_host = 127.0.0.1
# listen_port = 3128
# probe_timeout = 1.0 # seconds to wait when testing the work proxy
# cache_ttl = 10.0 # seconds to cache the reachable/not-reachable resultAfter editing: systemctl --user restart work-proxy.
systemctl --user status work-proxy # current state + routing mode
journalctl --user -u work-proxy -f # watch direct/proxy switches live
systemctl --user restart work-proxy # after a config changeMode switches show up in the log as:
[work-proxy] routing mode -> via proxy.example.com:8080
[work-proxy] routing mode -> direct
To check the current mode without the logs:
timeout 1 bash -c 'echo > /dev/tcp/proxy.example.com/8080' \
&& echo "proxy reachable -> VIA PROXY" \
|| echo "proxy unreachable -> DIRECT"The service won't start / shows failed.
Check the logs for the reason: journalctl --user -u work-proxy -n 30. The most common cause is a typo in ~/.config/work-proxy/config (e.g. a missing port).
A program still can't reach the internet.
- Confirm the service is running:
systemctl --user status work-proxy. - Confirm your proxy variables are set in the current terminal:
echo $HTTP_PROXYshould printhttp://127.0.0.1:3128. If it's empty, you opened the terminal before adding them — open a new one (see step 5).
It says direct even though I'm at work.
The work proxy address is probably wrong or unreachable. Test it directly (replace with your real host/port):
timeout 1 bash -c 'echo > /dev/tcp/proxy.mycompany.com/8080' && echo reachable || echo unreachableIf it says unreachable while you're on the office network, double-check the upstream line in your config.
systemctl --user says "Failed to connect to bus".
You're likely on a text-only/SSH session without a user systemd instance. Either log in through the desktop, or run the proxy by hand:
python3 ~/.local/bin/work-proxy.py.
- The reachability test is a plain TCP connect to the proxy, not a full HTTP exchange — fast, and cached so it doesn't probe on every request.
- Authenticated (e.g. NTLM/Kerberos) upstream proxies are not handled by this tool; it forwards your requests as-is. Pair it with a proxy authenticator if your workplace requires credentials.
- The listen address is fixed on purpose: that's what lets you stop touching application proxy settings.
NO_PROXYexcludes the loopback to avoid any routing loop.