Installing and configuring Happ on Linux distributions

Installing Happ on Linux: AppImage and .deb

The Happ desktop build is distributed in the Releases section of the Happ-proxy repository on GitHub. For most distributions the universal AppImage format is more convenient — it requires no installation and runs from any folder. For the Debian and Ubuntu family there is a separate .deb package.

Download the latest file for your architecture (usually x86_64), make the AppImage executable, and then run it: `chmod +x Happ-x86_64.AppImage` and `./Happ-x86_64.AppImage`. For the .deb, use `sudo apt install ./happ_amd64.deb` — the package manager will pull in the dependencies itself.

If the AppImage does not start, the most common cause is a missing FUSE library. Install it with `sudo apt install libfuse2` (Debian/Ubuntu) or the equivalent for your distribution. As a workaround, the AppImage can be extracted and run directly: `./Happ-x86_64.AppImage --appimage-extract` and then `./squashfs-root/AppRun`.

Importing the subscription and configuration

Access to the servers is granted by the service's Telegram bot: there you activate a trial, paid, or official key and receive a subscription link in the form https://…/sub/…. This link contains an up-to-date list of servers and Xray parameters — there is no need to enter configs manually.

In the app, open the add-configuration screen, paste the subscription link, and save. Happ will load all available servers as a single list and will continue to update them via the same link. If the servers change or new locations are added, just tap the subscription refresh — no reinstallation is required.

If needed, you can also add a single configuration: copy the vless:// or ss:// string from the bot and paste it via import from the clipboard. The same key works on all devices, so the subscription for Linux, Windows, and mobile clients is identical.

Running proxy mode on the Xray core

After importing, select a server from the list and enable the connection. Happ brings up a local proxy (SOCKS and HTTP) on the Xray core and routes traffic through it. In system mode the client writes the proxy into the desktop environment settings, so browsers and most applications start working through the tunnel without additional configuration.

The local proxy port can be set manually in the app settings — this is handy when you need to route only a specific program into Happ. Enter the address 127.0.0.1 and the chosen port in your browser's proxy settings or in environment variables (for example, `export https_proxy=http://127.0.0.1:PORT`), and leave the rest of the traffic direct.

For fine-grained traffic separation, Happ has list-based routing and split tunneling — which domains and applications go through the proxy and which bypass it. A detailed breakdown of the rules and utility is covered in separate sections of the site, so as not to mix the basic installation with fine-tuning routes.

Autostarting Happ at system boot

To have the proxy come up automatically, add the client to your desktop environment's startup. Create the file `~/.config/autostart/happ.desktop` with the lines `[Desktop Entry]`, `Type=Application`, `Exec=/full/path/Happ-x86_64.AppImage`, and `X-GNOME-Autostart-enabled=true`. GNOME, KDE, and most environments will pick it up at the next login.

For a .deb installation, the autostart shortcut can be enabled directly in the app settings or through your environment's startup menu — the path to the executable is filled in automatically. After login, Happ minimizes to the system tray and is available from the icon next to the clock.

If you run Linux without a graphical shell, set up the launch as a systemd user service: place the unit in `~/.config/systemd/user/`, specify the path to the AppImage in `ExecStart`, and enable autostart with `systemctl --user enable --now happ.service`.

Checking the connection and troubleshooting

After connecting, verify that traffic goes through the server: open any IP-detection service — the address and country should match the selected location. If the IP stayed the same, make sure the system proxy is enabled and that the application is reading the correct local port.

In case of drops or slow speeds, switch the server in the subscription list — neighboring locations often provide a more stable route. Then refresh the subscription to get the current Xray parameters and restart the connection. Sometimes a local firewall gets in the way: allow Happ outbound connections in ufw or firewalld.

If the server list fails to load after updating the client, check the key's validity in the Telegram bot and that the subscription link is correct. Connection logs are available in the app itself and help distinguish a key problem from a network block.