Setting Up Happ on Linux
- Author
- Dmitry Sokolov, Lead technical writer
- Reviewed by:
- Artem Volkov
- Fact-checked:
- Published:
- Guide version:
- 1.0
In short
To set up Happ on Linux, import a key or subscription with the “+” button from the clipboard, pick a server and connect in TUN mode if you need all system traffic. The system proxy is respected only by programs that read desktop settings.
On Linux, Happ works as on other desktops: import with “+”, pick a server, connect, check the ping. The difference is in how the system distributes traffic. TUN mode creates a network interface and covers all programs, including the terminal and containers on the host. The system proxy is written into the GNOME or KDE settings, so not every app sees it, and console tools look at environment variables instead.
Before You Start
Setting up Happ on Linux begins the same way as on Windows and macOS: import a key or subscription, pick a server and connect. What differs is how the distribution hands traffic to programs.
For workstations where you need all traffic, choose TUN. For a single browser, the system proxy is enough if your desktop supports it.
The guide targets the Qt 6 build for Ubuntu 22.04+, Debian 11.6+ and Red Hat 8.10+. The names of system menus depend on the desktop environment.
Step-by-Step Setup
Launch Happ from the applications menu
Find Happ in the applications menu or start it from a terminal. On the first launch the app opens with an empty server list.
Result: The main Happ window with no configurations.
Copy a key or subscription
Copy the key string vless://, vmess://, trojan://, ss://, socks:// or hysteria2://, a subscription address or an encrypted happ://crypt link into the desktop clipboard.
Result: The whole string is in the clipboard.
Import with the “+” button
Click “+” at the top right and choose paste from clipboard. If a deep link from the browser does not open Happ, copy the link and paste it the same way. For your own server, use manual entry.
Result: The servers appear in the server list.
Choose a mode and connect
Select a server, choose TUN mode or the system proxy, and click the connect button. TUN needs elevated privileges: if a prompt for the administrator password appears, enter it.
Result: The status is connected, and in TUN mode a new interface appears in the ip link output.
Check the ping
Click the speedometer icon in the subscription header. If the TCP ping looks too low, it may be the delay to the nearest CDN point; the Via Proxy HEAD method shows the delay through the proxy more accurately.
Result: Delays in ms next to the servers, and the current connection check shows no timeout.
Configure routing
Import a profile with a happ://routing/add/ link or build one at routing.happ.su. The local networks 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16 already go direct by default.
Result: A profile appears for the subscription and applies on the next connection.
Share access over the LAN if needed
Turn on Allow LAN connections in Advanced settings, connect to a server and open the SOCKS5 and HTTP ports in the distribution's firewall.
Result: Happ shows the current IP and ports, and other devices on the network connect to them.
Connection Modes
- TUN — Happ creates a virtual network interface and sends system traffic into it. Good for the terminal, package managers and programs with no proxy settings. In pre-release 4.4.6, Xray TUN became the default TUN mode.
- System proxy — Happ writes a local proxy into the desktop network settings. Browsers and GNOME and KDE apps read it, but not all console tools do. Pre-release 4.4.6 has a setting for system proxy exclusions.
- Local SOCKS5 and HTTP for the LAN — With Allow LAN connections turned on, the Linux machine accepts connections from other devices on the network on the SOCKS5 and HTTP ports that Happ shows.
What Happ Supports on Linux
| Feature | Support |
|---|---|
| TUN mode (all device traffic) | Yes |
| System proxy | Yes |
| Proxy for individual apps | No data |
| Sharing the connection over the local network | Yes |
| Routing | Routing profiles |
Tips
If a Linux laptop loses the tunnel after sleep, check your version: the fix arrived in release 4.3.0. On older versions, reconnecting helps.
Do not keep another client with TUN mode on at the same time. Two interfaces and their default routes interfere with each other and with DNS.
If a red exclamation mark appears next to the routing profile after the geo files download, check your access to GitHub. The download stops if it does not finish within 3 minutes.
For Docker containers on the same machine, TUN mode covers the host's traffic, but the containers' own network settings may need a separate check.
Related Guides
Key takeaways
- On Linux, TUN mode covers the traffic of all programs, including console tools.
- The desktop system proxy is respected by browsers and GTK or Qt apps, but not by curl, git and apt.
- For console programs you can set Happ's local port in the http_proxy and https_proxy variables.
- For LAN sharing on Linux you need to open the SOCKS5 and HTTP ports in the distribution's built-in firewall.
- Xray JSON configurations are passed to the core unchanged, and Happ routing is not applied to them.
Frequently asked questions
On Linux, why does the browser go through Happ but apt and curl do not?
System proxy mode changes the desktop settings that Firefox, Chromium and GNOME or KDE apps read. Command-line tools look at the http_proxy and https_proxy environment variables. Either set them with Happ's local HTTP port, or switch to TUN mode, and then all system traffic goes through the tunnel.
Does Happ's system proxy work on Wayland and other desktop environments?
On Linux the system proxy is not a kernel feature but a setting of a specific desktop. In GNOME and KDE you can see it in the network settings under Proxy, and it does not depend on X11 or Wayland. Minimal window managers often have no such shared setting, and TUN mode is more reliable there.
How do I open ports for LAN connections on Linux?
Turn on Allow LAN connections in Advanced settings and note the SOCKS5 and HTTP ports, for example 10808 and 10809. On Ubuntu with ufw, run sudo ufw allow 10808/tcp and the same for 10809. On Fedora and Red Hat with firewalld, add the ports with the firewall-cmd --add-port command. After that, devices on the same subnet can connect.
Can I use my own Xray JSON config in Happ on Linux?
Yes, Happ accepts JSON configurations and passes them to Xray-core unchanged. Happ routing is not applied to them, and the rules are set inside the JSON itself. Only the choice of geo files and the remote DNS are taken from the active profile. JSON subscriptions allow zero or one routing profile, and you cannot change it.
What if domains stop working after connecting but IP addresses still open?
The problem is DNS. The default routing profile uses the remote DNS-over-HTTPS server cloudflare-dns.com, and dns.google for direct requests. Check that systemd-resolved or NetworkManager are not sending queries around the TUN interface, then reconnect. To diagnose, compare the output of resolvectl status before and after connecting.
How do I start Happ with the system on Linux?
If the app settings have no autostart option, use your desktop's tools: in KDE it is System Settings → Autostart, and in GNOME the list of startup applications. A universal way is to copy the Happ shortcut, usually a .desktop file in /usr/share/applications, into the ~/.config/autostart folder. In pre-release 4.4.6 each subscription got its own connect-on-launch setting.
Topics mentioned
Related articles
Related sections
Sources
- Happ system requirements — accessed September 27, 2026
- Happ documentation: downloads table — accessed September 27, 2026
- happ-desktop releases on GitHub — accessed September 27, 2026
- Happ Legacy 1.0.2 on GitHub — accessed September 27, 2026
- Adding a configuration and subscription — accessed September 27, 2026
- Local network connections — accessed September 27, 2026
- Routing in Happ — accessed September 27, 2026
- Ping in Happ — accessed September 27, 2026