Happ VPN
Pricing

Setting Up Happ on macOS

Author
Dmitry Sokolov, Lead technical writer
Reviewed by:
Artem Volkov
Fact-checked:
Published:
Guide version:
1.0

In short

To set up Happ on macOS, copy a key or subscription link, click “+” and import it from the clipboard, pick a server and connect. On the first connection macOS asks for a permission, and you need to confirm it.

The setup order is the same for both builds: import with “+”, pick a server, connect, check the ping. What differs is how macOS lets the app onto the network. For the App Store version the system allows creating a VPN configuration, while the Qt 6 DMG build works in TUN mode or as a system proxy. On macOS 15 and newer, sharing over the local network additionally needs the permission for local network access.

Before You Start

Setting up Happ on macOS depends on the build. The App Store version works through a macOS VPN configuration, while the Qt 6 DMG build offers TUN mode and the system proxy.

The import itself is the same: the “+” button at the top right, then the clipboard, a deep link or manual entry. The servers appear in the server list.

Before you begin, get a key or subscription from a provider, or prepare the configuration of your own server. Happ itself does not provide servers.

Step-by-Step Setup

  1. Open Happ and grant system permissions

    Launch Happ from the Applications folder or Launchpad. If macOS asks for permission for notifications or network access, answer as you see fit: for connecting, the permissions related to VPN and the network matter.

    Result: The main window opens with no servers.

  2. Copy a key or subscription

    Copy the string with Cmd+C: a key such as vless://, vmess://, trojan://, ss://, socks://, hysteria2:// or hy2://, a regular subscription address, or an encrypted happ://crypt link.

    Result: The whole string is in the clipboard.

  3. Import with “+”

    Click “+” at the top right and choose paste from clipboard. A deep link from your provider opens Happ by itself. For your own server, use manual entry: choose a protocol, fill in the fields and click Done.

    Result: The servers appear in the server list, and a subscription shows its name.

  4. Pick a server and connect

    Select a server and click the connect button. In the App Store version, confirm adding the VPN configuration with your password or Touch ID. In the DMG, choose TUN mode or the system proxy and confirm the permission request if macOS shows one.

    Result: The status in the Happ window changes to connected, and websites open through the chosen server.

  5. Check the delay

    Click the speedometer icon in the subscription header to measure all servers. To test through the proxy itself, use the Via Proxy HEAD method; ICMP requires you to disconnect the tunnel temporarily. Then run the current connection check.

    Result: A delay in ms or a green status icon is visible, depending on the ping setting in Settings.

  6. Configure routing and the LAN if needed

    For split tunneling, import a profile with a happ://routing/onadd/ link or build one at routing.happ.su. To share with other devices, turn on Allow LAN connections in Advanced settings.

    Result: A profile is active, and with LAN enabled the Mac's IP and the SOCKS5 and HTTP ports are visible.

Connection Modes

  • macOS VPN configuration (App Store version) — The App Store app creates a tunnel through the macOS system VPN mechanism. The connection is visible in the VPN section of System Settings, and app traffic goes through the tunnel according to the subscription's routing rules.
  • TUN (DMG) — The desktop build creates a virtual network interface and sends the traffic of all programs into it, including Terminal. In pre-release 4.4.6, Xray TUN became the default TUN mode.
  • System proxy (DMG) — Happ writes a local proxy into the macOS network settings. Browsers and apps that use the system networking stack respect it. Pre-release 4.4.6 added a setting for system proxy exclusions.

What Happ Supports on macOS

FeatureSupport
TUN mode (all device traffic)Yes
System proxyYes
Proxy for individual appsNo data
Sharing the connection over the local networkYes
RoutingRouting profiles

Tips

If websites stop opening in the browser after you disconnect Happ, check System Settings → Network → Wi-Fi → Details → Proxies. No proxies from a finished session should remain switched on there.

Do not run the App Store version and the DMG at the same time. Two tunnels on one Mac fight over routes and DNS.

The built-in macOS firewall may ask whether to let Happ accept incoming connections. For LAN sharing, answer Allow, or other devices will not connect.

For corporate resources, keep their domains in DirectSites or ProxySites, depending on where they are reachable. That way work systems do not depend on the server you have chosen.

Related Guides

Key takeaways

  • Keys and subscriptions are imported into Happ on a Mac with the “+” button, from the clipboard or through a deep link.
  • On the first connection macOS asks for a permission, and without it the tunnel will not come up.
  • The DMG build supports TUN mode and the system proxy, like the Windows and Linux versions.
  • Release 4.3.0 fixed the tunnel being lost after a Mac wakes from sleep.
  • For LAN sharing on macOS 15 and newer, check Happ's permission for local network access.

Frequently asked questions

macOS asks me to allow adding a VPN configuration. Is that normal?

Yes. Mac apps that create a tunnel through Apple's system mechanism ask, on the first connection, for permission to add a VPN configuration and for confirmation with a password or Touch ID. The configuration is stored in the VPN section of System Settings. If you click Don't Allow, you cannot connect until you try again and agree.

Why does Happ not restore the connection after my Mac sleeps?

In the desktop build this problem was fixed in release 4.3.0: the tunnel is no longer lost after sleep on macOS and Linux. Check your version and update the DMG if needed. If the connection is lost anyway, disconnect and connect again: after a network change or sleep, Xray-core re-establishes the connection to the server.

How do I exclude a site from the proxy in Happ on a Mac?

Add the domain to DirectSites, or the address to DirectIp, in the active routing profile. You can import a profile with a happ://routing/add/ link or build one in the routing.happ.su generator. The DMG build of pre-release 4.4.6 also has a setting for system proxy exclusions. Routing changes apply on the next connection to a server.

How do I share a connection from a Mac with other devices?

Open Settings, then Advanced settings, and turn on Allow LAN connections, then connect to a server. Happ shows the Mac's IP and the SOCKS5 and HTTP ports. On macOS 15 and newer the system may ask for permission to access the local network: you can see its status under Privacy & Security, then Local Network.

Why does the browser work while Terminal goes around the proxy?

The macOS system proxy is respected by Safari, Chrome and most apps that use the system networking stack, but not by console tools such as curl and git. They need the http_proxy and https_proxy environment variables, or TUN mode. Switch the DMG build to TUN, and Terminal traffic will go through the tunnel along with everything else.

Can I move subscriptions from Happ on iPhone to Happ on a Mac?

If the subscription is neither encrypted nor hidden, open its server in Happ on iPhone, swipe right and tap the arrow icon: Copy to clipboard, QR code and JSON are available. Send the copied link to the Mac, for example through Universal Clipboard, and import it with “+”. An encrypted subscription is easier to add again from the original link.

Topics mentioned

Related articles

Related sections

Sources

  1. Happ system requirements — accessed September 27, 2026
  2. Happ documentation: downloads table — accessed September 27, 2026
  3. Happ - Proxy Utility on the App Store — accessed September 27, 2026
  4. happ-desktop releases on GitHub — accessed September 27, 2026
  5. Adding a configuration and subscription — accessed September 27, 2026
  6. Ping in Happ — accessed September 27, 2026
  7. Local network connections — accessed September 27, 2026
  8. Routing in Happ — accessed September 27, 2026