Hey VPN

A HarmonyOS VPN client powered by a native Xray core.

English · 简体中文

---

Hey VPN is a HarmonyOS VPN client built with ArkTS, Stage model abilities, and a native Xray core. It imports proxy nodes and subscriptions, generates an Xray runtime config, starts a HarmonyOS VPN Extension, and routes the device TUN flow through Xray's native TUN inbound.

The current native path is:

User connects
  -> vpnExtension.startVpnExtensionAbility(...)
  -> HeyVpnAbility.onCreate(want)
  -> vpnExtension.createVpnConnection(context)
  -> vpnConnection.create(vpnConfig)
  -> TUN fd
  -> libheyvpn.so dlopen(libxray.so)
  -> CGoSetTunFd(tunFd)
  -> CGoRunXrayFromJSON(config)
  -> Xray native TUN inbound reads the Harmony VPN fd
  -> Xray outbound

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.

Features

• HarmonyOS Stage app with EntryAbility, HeyVpnAbility, and backup ability.
• 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://, and hysteria2:// / hy2://.
• Xray config generation with native TUN inbound plus proxy/direct/block outbounds, and routing rules (bypass LAN/CN).
• Native N-API bridge for packaged libxray.so, including TUN fd setup, Xray lifecycle entry points, and real per-node delay testing (CGoPing).
• Geo-asset management (geoip/geosite download, custom URLs, backup/restore).
• Per-app proxy with allow/deny modes, a preset app list, and manual package entry (HarmonyOS NEXT restricts global app enumeration).
• Scan/import and export pages, diagnostic log panel, native runtime stat 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

For the manual closed-loop checklist, see docs/real-device-vpn-test.md.

Native Core

The native bridge builds libheyvpn.so and loads one packaged Go shared library, libxray.so. That library exports Xray control symbols plus CGoSetTunFd, documented in entry/src/main/cpp/README.md.

Hey VPN does not bundle or invoke tun2socks for the VPN data path. HarmonyOS creates the VPN TUN fd, libheyvpn.so passes that fd into Xray with CGoSetTunFd, and the generated runtime config uses Xray's native protocol: "tun" inbound. A local SOCKS inbound may still be generated for per-node delay tests, but it is separate from VPN traffic forwarding.

Roadmap

• Real-device VPN traffic validation across more HarmonyOS versions.
• Node sorting, duplicate cleanup, and automatic subscription refresh.
• Camera-based QR scanning and QR code generation for share/export.
• Protocol editors for advanced VLESS/VMess/Trojan/Shadowsocks/WireGuard/ Hysteria2 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.