Tunly

Quick SSH tunnels, tidy tray.

GNOME tray applet to manage multiple named SSH dynamic (SOCKS5) tunnels and toggle the system proxy in one click. Exclusive model: at most one tunnel active at a time — it drives the system proxy and is reverted on stop, drop, or quit.

• One click — pick a tunnel in the tray, ssh comes up, system proxy follows.
• Always reverted — stop, crash, drop, or quit: your proxy never stays pointed at a dead port.
• Multiple tunnels — named profiles, each with its own host, port, and auth.
• Any auth — ssh-agent, a specific key file, or password (GNOME keyring / prompt; never written to disk).
• Self-healing — health-checks the tunnel and cleans up if ssh dies underneath.
• Transparent mode (optional) — route everything through the tunnel with iptables, not just apps that read the proxy setting. See below.
• No daemons, no root — a single Python/GTK process running as you. (Transparent mode is the one exception: it needs root for the firewall rules.)

Proxy mode vs transparent mode

By default Tunly sets the GNOME system proxy. That only covers apps that bother to read it — Firefox, Chrome, GTK apps. curl, yt-dlp, git, apt and most CLI tools ignore it and leave over your real IP.

Tick Transparent (whole system) in the tray to force all outbound TCP through the tunnel with iptables. No per-app configuration, nothing to opt in.

ping will not work while transparent mode is on — that is the kill switch, not a broken network. ICMP cannot ride a SOCKS5 TCP tunnel, so it is rejected rather than allowed out over your real IP. Use curl to test connectivity.

Transparent mode is fail-closed: while it is on, traffic that cannot go through the tunnel is rejected rather than leaked. If Tunly dies — even by SIGKILL — the privileged helper notices its pipe close and removes every rule on its own. Rules are never persisted, so a reboot also clears them. To clean up by hand:

tunly --repair

It also needs a DNS server (set it in Manage tunnels…, default 1.1.1.1), because your local resolver's upstream is usually a private router address that is unreachable from the exit node. One consequence worth knowing: split-horizon DNS from a corporate resolver stops resolving while transparent mode is on.

📖 Full user guide — first run, auth setup, troubleshooting.

📱 On Android? See Tunly Mobile — the same named SSH tunnels, routing your whole device through a VpnService.

You need an SSH server

Tunly is a client. It doesn't provide servers — it tunnels your traffic through an SSH server you control and then out to the internet, so your exit IP becomes that server's IP. You need a Linux box you can SSH into with outbound internet; almost any small VPS works (the tunnel only needs sshd + bandwidth — no special software on the server).

Create a small Linux VM, note its public IP, and you're the root/sudo user. Popular options (prices/tiers change — verify before signing up):

Then: add your key with ssh-copy-id user@SERVER_IP, open Manage tunnels…, add a tunnel with that host/user/auth, and pick it from the tray. Harden the box with key-only auth (PasswordAuthentication no) and a firewall on port 22.

Quick install (Debian/Ubuntu)

wget https://github.com/thelinuxer/tunly/releases/latest/download/tunly_0.1.4_all.deb
sudo apt install ./tunly_0.1.4_all.deb

Requirements

System packages (all preinstalled on a standard GNOME desktop; no pip):

• python3 + python3-gi (GTK 3 introspection)
• gir1.2-appindicator3-0.1 or gir1.2-ayatanaappindicator3-0.1
• gir1.2-notify-0.7 (optional — desktop notifications)
• ssh, curl

Optional, per auth method:

• Password auth works out of the box via an SSH_ASKPASS helper (no extra deps). If sshpass is installed it is used instead.
• Remember password in keyring needs secret-tool (libsecret-tools). Without it, password-auth tunnels prompt on each connect.

Install

The GTK/AppIndicator bindings are system packages (GObject-Introspection typelibs), not PyPI wheels — so sandboxed formats (Flatpak/Snap) can't drive the host proxy and are not used. Pick one:

A. Debian / Ubuntu (.deb) — recommended for clean system integration

make deb                 # produces tunly_<ver>_all.deb (needs dpkg-deb)
sudo apt install ./tunly_*.deb   # pulls gir1.2-* deps automatically

B. pipx (any distro)

Because AppIndicator has no PyPI package, the venv must see the system bindings:

sudo apt install python3-gi gir1.2-gtk-3.0 \
     gir1.2-ayatanaappindicator3-0.1 openssh-client
pipx install --system-site-packages tunly   # from PyPI (or "." from a checkout)
# then, for the app menu + icon:
tunly --install-desktop --autostart

C. Arch Linux

A PKGBUILD ships in packaging/aur/:

cd packaging/aur && makepkg -si

D. From source (make install)

sudo make install PREFIX=/usr/local          # installs launcher + .desktop + icon

Run

After install, launch tunly (from the app menu or the shell). An icon appears in the top-bar tray (green = a tunnel is active, grey = none). Click it → per-tunnel start/stop, Manage tunnels…, Quit.

Run in place without installing:

PYTHONPATH=src python3 -m tunly &

Menu/autostart integration for a pipx or in-place run:

tunly --install-desktop            # add --autostart to launch on login
tunly --uninstall-desktop          # remove it

Managing tunnels

Manage tunnels… opens a window listing every tunnel with a status dot and Start/Stop, Edit, Delete buttons, plus + Add tunnel. Each tunnel has a unique name and its own SOCKS port.

SSH auth methods (per tunnel)

Config

~/.config/tunly/tunnels.json — created on first run. A legacy config.ini (single-tunnel format) is auto-migrated to tunnel default. Passwords are never written here (keyring or prompt-only).

Self-test

Real end-to-end check (spawns ssh, sets + reverts proxy, prints exit IP). Point it at your own reachable SSH server via env vars — nothing is hardcoded:

SSTRAY_TEST_HOST=vps.example.com SSTRAY_TEST_USER=alice \
  PYTHONPATH=src python3 -m tunly --selftest   # or: tunly --selftest

Security notes

• Passwords are never written to tunnels.json. They come from the GNOME keyring (secret-tool) or a prompt, and reach ssh via sshpass -e or an SSH_ASKPASS helper — no plaintext on disk. The password does transit the ssh child's environment (as with sshpass), readable only by the same user via /proc/<pid>/environ.
• Host-key policy is StrictHostKeyChecking=accept-new: unknown host keys are trusted on first connect (TOFU) so the non-interactive tunnel can come up; a changed key is still refused. If you need strict first-connect verification, pre-populate ~/.ssh/known_hosts.
• Runs entirely as your user; it changes only your GNOME proxy settings and spawns ssh. No privileged operations, no shell interpolation of user input.

Releasing

Versions are tag-driven; pyproject.toml is the single source of truth (the .deb version derives from it at build time). To cut a release:

# 1. bump `version` in pyproject.toml (and the Quick install URL above), commit
# 2. tag and push — CI builds wheel/sdist + .deb and attaches them to a GitHub Release
git tag v0.2.0 && git push origin v0.2.0

CI fails the release if the tag and pyproject.toml version disagree. Unit tests run on every push (.github/workflows/ci.yml); live SSH integration tests run locally with SSTRAY_TEST_HOST=<server> pytest tests/.

Enabling PyPI publishing (one-time): on pypi.org → Publishing → add a trusted publisher with repository thelinuxer/tunly, workflow release.yml, environment pypi; create a matching pypi environment in the GitHub repo settings; then uncomment the pypi job in .github/workflows/release.yml. After that every tagged release also lands on PyPI (pipx install tunly).

Design

See docs/2026-07-05-tunly-design.md.