The easy way to run an authenticated SOCKS5 proxy system-wide on Linux desktops.

Paste one proxy string. socksy stores the credentials, points your desktop at a local relay, and confirms the new exit IP, all from one command. Works on GNOME and KDE, with a CLI-only fallback for everything else.

Get StartedGitHubView on GitHub
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

Why this exists

Desktop proxy settings have no fields for a SOCKS5 username and password. If your provider hands you an authenticated SOCKS5 proxy, common for residential and mobile proxies, the system proxy dialog is a dead end: apps connect, then get rejected.

socksy fixes this with a tiny local relay. Your desktop points at the relay with no authentication; the relay holds your credentials and forwards traffic upstream, authenticated, to your actual proxy.

Read more in the docs.

  your apps  ──▶ 127.0.0.1:1081 ──▶ gost relay ──▶ your.proxy:1080
   (no auth)      (local, no auth)   (adds creds)   (authenticated)

What it does

One command on, one command off

socksy set applies a proxy system-wide; socksy off returns you to a direct connection. No config files to hand-edit.

Handles the authentication the GUI can't

The relay holds your SOCKS5 username and password; your desktop's proxy setting never sees them.

Autodetects your desktop

GNOME, KDE, or CLI-only: socksy picks the right backend on its own, or you can set it yourself with SOCKSY_BACKEND.

No root required

The default install lives entirely under ~/.local and ~/.config. A .deb and an .rpm are also available on every release.

A leak audit built in

socksy check verifies where your traffic actually exits: relay, bind address, DNS, IPv6, bypass list, and exit country, in one command.

Credentials stay out of ps

The relay reads credentials from a 600 config file, not its command line, so they never end up readable in /proc/<pid>/cmdline.

Get started

Install from source:

git clone https://github.com/Nrentzilas/socksy.git
cd socksy
./install.sh

Then apply your first proxy:

socksy set 'user:pass@host:port'

Prefer a .deb or .rpm, or need shell completions? See Installation.

Looking for a specific command or flag? See the command reference.