Hey VPN

June 23, 2026 · View on GitHub

Hey VPN

Hey VPN

A HarmonyOS VPN client powered by a native Xray core.

platform ArkTS API 24 Xray core version 1.3.0 license GPL-3.0

English · 简体中文

Hey VPN is a HarmonyOS VPN client built with ArkTS, Stage model abilities, and a native proxy core (Xray, with sing-box as a selectable second core). It imports proxy nodes and subscriptions, generates a runtime config, starts a HarmonyOS VPN Extension, and routes the device TUN flow into the core through a bundled tun2socks adapter that feeds a local SOCKS inbound.

The current native data path (same for both cores) is:

User connects
  -> vpnExtension.startVpnExtensionAbility(...)
  -> HeyVpnAbility.onCreate(want)
  -> vpnExtension.createVpnConnection(context)
  -> vpnConnection.create(vpnConfig)
  -> TUN fd
  -> libheyvpn.so dlopen(libxray.so / libsingbox.so)
  -> CGoRunXrayFromJSON(config) / CGoStartSingBox(config)
       (core opens a local SOCKS inbound on 127.0.0.1:10810)
  -> libheyvpn.so dlopen(libheytun2socks.so)
  -> HeyTun2SocksStart(tunFd, 127.0.0.1, 10810, mtu)
       (forwards Harmony TUN fd traffic into the SOCKS inbound)
  -> core SOCKS inbound -> core outbound (proxy node)

Why tun2socks instead of the core's native TUN inbound: the Go-on-HarmonyOS (musl) TLS wall and the toolchain gap for the native-TUN entry points pushed the data path back to TUN fd -> tun2socks -> SOCKS inbound, which works with the OHOS Go fork build. See docs/harmonyos-go-tls-wall.md.

Status

The client is feature-complete across the UI and config layers: node and subscription management, share-link and JSON import, Xray config generation, native delay testing, routing, geo-asset management, per-app proxy, and the full VPN extension startup path are all implemented and wired to the native bridge. The remaining gap is end-to-end traffic validation, which should be done on a real HarmonyOS device because some emulator/system images do not include the VPN authorization component.

Download

Signed HAP packages are published on the Releases page. Grab the latest entry-default-signed.hap and install it with DevEco Studio or hdc (see Install And Test). Building from source is covered below.

Note: the UI and config layers are feature-complete; end-to-end VPN traffic should be validated on a real HarmonyOS device (see Status).

Features

  • HarmonyOS Stage app with EntryAbility and HeyVpnAbility, plus core VPN routing, config, and sharing flows.
  • Node list, search, selection, start/stop/restart controls, and runtime status.
  • Import of subscription URLs, Xray outbound JSON, and share links, with multi-subscription groups and per-node detail/edit pages.
  • Share-link parsing for vless://, vmess://, trojan://, ss://, socks://, http(s)://, wireguard://, anytls://, and hysteria2:// / hy2://.
  • Runtime config generation with a local SOCKS inbound (fed by the tun2socks data path) plus proxy/direct/block outbounds, and routing rules (bypass LAN/CN).
  • Native N-API bridge for packaged libxray.so / libsingbox.so / libheytun2socks.so, including core lifecycle entry points, the tun2socks adapter, and real per-node delay testing (CGoPing).
  • Geo-asset management (geoip/geosite download, custom URLs, and status/count feedback).
  • Per-app proxy with allow/deny modes, a preset app list, and manual package entry (HarmonyOS NEXT restricts global app enumeration).
  • QR support via ScanKit: camera and from-image scanning to import share links, plus QR code generation on the node detail and export pages for sharing.
  • Import and export pages, diagnostic log panel, native runtime stat and traffic-total display, settings, and an about page — with full English/Chinese i18n.

Project Layout

AppScope/                         App-level HarmonyOS metadata and resources
entry/src/main/ets/               ArkTS UI, services, storage, VPN ability
entry/src/main/cpp/               Native N-API bridge and prebuilt core notes
entry/src/main/cpp/prebuilt/      Packaged arm64-v8a native libraries
scripts/                          Native build and device smoke-test scripts
docs/                             Real-device test documentation

Requirements

  • DevEco Studio / HarmonyOS SDK 6.1.1, API 24.
  • A HarmonyOS phone or tablet for end-to-end VPN testing.
  • Go and DevEco native toolchains when rebuilding the Xray shared library.

Build

Build the app with the project smoke-test script:

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk ./scripts/device_vpn_smoke_test.sh build

The output HAP is expected at:

entry/build/default/outputs/default/entry-default-signed.hap

Rebuild the Xray native core when needed:

./scripts/build_libxray_ohos.sh

The script places libxray.so and libxray.h under entry/src/main/cpp/prebuilt/arm64-v8a/.

Install And Test

List connected targets:

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk ./scripts/device_vpn_smoke_test.sh targets

Install the HAP:

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk ./scripts/device_vpn_smoke_test.sh install

Watch VPN and native bridge logs:

DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk ./scripts/device_vpn_smoke_test.sh logs

Native Core

The native bridge builds libheyvpn.so and loads packaged Go shared libraries: the proxy core (libxray.so, plus libsingbox.so for the optional second core) and the tun2socks adapter (libheytun2socks.so). These are documented in entry/src/main/cpp/README.md.

Hey VPN forwards the VPN data path through tun2socks. HarmonyOS creates the VPN TUN fd; the selected core starts with a local SOCKS inbound on 127.0.0.1:10810; libheyvpn.so then loads libheytun2socks.so and calls HeyTun2SocksStart(tunFd, 127.0.0.1, 10810, mtu) to relay the TUN fd's traffic into that SOCKS inbound. The core's native TUN inbound (CGoSetTunFd / protocol: "tun") is no longer used on the VPN data path — see docs/harmonyos-go-tls-wall.md for why.

Roadmap

  • Real-device VPN traffic validation across more HarmonyOS versions.
  • Node sorting, duplicate cleanup, and automatic subscription refresh.
  • Protocol editors for advanced VLESS/VMess/Trojan/Shadowsocks/WireGuard/ Hysteria2/AnyTLS fields, plus TUIC support.
  • Expanded routing rulesets, including ad-blocking and custom rule editing.
  • HarmonyOS deep-link import, shortcuts, and platform-specific automation.

License

Copyright (C) 2026 popsiclelmlm

Hey VPN is licensed under the GNU General Public License v3.0. You may use, modify, and redistribute it — including commercially — provided derivative works remain under GPL-3.0 and you make the corresponding source available.

It bundles the Xray native core (Xray-core, MPL-2.0) and builds on libXray (MIT). Those components keep their own licenses; see THIRD-PARTY-NOTICES.md for details.