Most of the tools I actually finish start the same way: something small annoys me for the tenth time in a month, and at some point the annoyance costs more than the fix would. Socksy is exactly that. It is not a clever idea. It is a chore I refused to keep doing by hand.
The thing that kept happening
A client project needed traffic to leave from a specific country. Nothing exotic, just geo-dependent behaviour I had to see with my own eyes rather than guess at. So I bought access to a residential proxy, got the usual string back,
user:pass@eu.example.net:1080
and went to open Settings, Network, Proxy, the way you would on any desktop.
There is no password field.
That is the whole problem, and it is worth sitting with for a second, because I did not believe it at first. The GNOME proxy panel gives you a SOCKS host and a port. That is it. Same on KDE. The desktop can point every app at a SOCKS5 proxy, but it has nowhere to put the credentials that proxy demands. So your apps connect, the proxy rejects them, and everything quietly breaks in a way that looks like a network outage rather than a config problem.
Almost every residential and mobile proxy out there is authenticated. Which means the system proxy settings are useless for the exact case where you most want them.
What I did before Socksy existed
The workaround is not a secret. You run a local relay that holds the credentials and speaks to the upstream proxy for you, then you point your desktop at the relay:
your apps -> 127.0.0.1:1081 -> local relay -> your.proxy:1080
(no auth) (local, no auth) (adds creds) (authenticated)
Clean idea. Miserable to do repeatedly. Every single time it meant fetching a relay binary, writing the config with the credentials in it, keeping the process alive somehow, then going into the desktop settings and flipping proxy mode, typing in localhost and the port, and finally curling an IP echo service to check whether any of it worked. Then reversing all of it when I was done, and remembering which of those steps I had forgotten when the internet stopped working an hour later.
Ten minutes, maybe. But ten minutes with six chances to make a typo, and I was doing it several times a week across two machines. The realisation that pushed me over was noticing I had started avoiding the proxy entirely. I would guess at geo behaviour instead of checking it, because checking was a hassle. That is the real cost of friction: not the lost minutes, but the work you quietly stop doing.
What it looks like now
socksy set 'user:pass@host:port'> upstream : user:***@eu.example.net:1080
> relay : 127.0.0.1:1081
+ proxy applied.
+ exit IP: 41.45.55.53
One command. It downloads the relay if you do not have it, verifies the download against a SHA-256 checksum, starts it as a systemd user service so it survives a logout and restarts itself if it dies, detects whether you are on GNOME or KDE and writes the right desktop setting, and then tells you your new exit IP so you know it actually worked before you go and waste twenty minutes debugging.
socksy off puts everything back.
That last part matters more than it sounds. A tool that changes system-wide network settings has to be trivially reversible, or people will not run it. I wanted the off switch to be as boring and reliable as the on switch.
The design decisions I care about
No root, no system packages. Everything lives under ~/.local and
~/.config. I did not want to write something that asks for sudo to fiddle with
a user-level convenience. If a tool cannot be uninstalled by deleting a couple
of directories, it is asking for too much trust for what it does.
It tells you the truth immediately. Every apply ends with a real HTTP request that prints your exit IP. Not “configuration written.” Not “service started.” The actual, observable outcome. This one behaviour has saved me more time than every other feature combined, because proxy failures are silent by nature and the feedback loop is otherwise horrible.
It handles the annoying details I kept hitting myself. Firefox resolves DNS
locally even when proxied, which leaks your real location and quietly defeats
the whole point, so socksy dns on fixes that across your profiles. Rotating
proxies hand you a fresh IP on every connection, so --sticky pins one. They
also occasionally hand you a dead exit node, so there is an opt-in watchdog that
probes the exit and restarts the relay when it goes bad. Saved profiles exist
because I have a work proxy and a testing proxy and I refuse to keep either
password in my shell history.
None of those were in the first version. Each one is a bug report I filed against myself after getting burned.
Who it is actually for
If you have never needed an authenticated SOCKS5 proxy, this solves a problem you do not have, and that is fine. But if you are testing geo-dependent behaviour, scraping something that needs a residential exit, working against an API that whitelists by region, or just want your whole desktop behind a proxy your provider gave you credentials for, then you have hit this wall too and probably built the same relay by hand.
You should not have to. That is the entire pitch.
What I took from building it
I write mostly TypeScript. Socksy is Bash, and writing a few thousand lines of it with ShellCheck and a real test suite in CI made me a noticeably better shell programmer than years of writing throwaway one-liners did. Turns out the discipline transfers: naming, error paths, keeping state in one place, failing loudly instead of half-succeeding.
The other lesson is older and I keep relearning it. The tools worth building are rarely the impressive ones. They are the ones that turn a ten-minute ritual you dread into one line you do not think about. Nobody is going to be amazed by Socksy. But I use it almost every day, and I no longer avoid the work it used to gate.
It is open source and MIT licensed. If it saves you an afternoon, the source is on GitHub.