TinyPaws

Current device release: 1.2.7-tiny (versionCode 1002007). See the changelog for release notes and the delivery record for physical-device evidence.

TinyPaws is a Clash/mihomo HarmonyOS client with a native ArkUI interface, powered by meow-rs 0.22.0, a Rust userspace TUN stack, and optional mihomo and sing-box compatibility engines. Profiles that use plugin transports are resolved through the route-validated mihomo engine even when a candidate engine is selected, so a compatibility preference cannot produce a false Connected state. Its product flow follows Meow for Android, while the HarmonyOS UI, VPN lifecycle, native bridge, packaging, and device validation are implemented in this repository.

Architecture

Native ArkUI (Rust: arkit + Dioxus)
    |  N-API
    v
HarmonyOS abilities (ArkTS)
    |  EntryAbility + VpnExtensionAbility
    |  VpnConnection TUN + protectProcessNet()
    v
TinyPaws Rust runtime
    |  paws_core + paws_profile
    |  paws_vpn + netstack-smoltcp/lwIP
    v
engine adapter
    |  meow-rs (native Rust), mihomo, or sing-box
    |  Config, rule engine, proxy, DNS, external controller
    v
Network

Features

• Routing modes
  • Rule: follow the active profile's ordered rules and rule providers.
  • Global: send all eligible traffic through the selected proxy.
  • Direct: bypass proxies.
• Proxy protocols: Direct, Shadowsocks, Trojan, VLESS, VMess, Snell, Hysteria2, AnyTLS, HTTP, and SOCKS5 through the enabled meow-rs feature set.
• Profiles and subscriptions
  • Import Clash YAML, base64 subscriptions, local files, remote URLs, and common share links.
  • Refresh, activate, edit, export, restore, and delete profiles.
  • Preserve subscription usage, expiry, update interval, home, and support metadata when provided.
• Rules and resources: ordered rules, rule providers, proxy providers, provider refresh, GEOIP, GEOSITE, and ASN data.
• VPN and DNS: HarmonyOS VpnExtensionAbility, userspace TCP/UDP forwarding, in-TUN DNS handling, cache diagnostics, and process-network protection.
• HarmonyOS integration: one system continuous-task notification, service card, Live View, per-application VPN allow/bypass lists, lifecycle journal, and bounded process/exit evidence.
• Configuration safety: subscription source, persistent user overrides and Harmony runtime adaptation remain separate; preflight reports changed paths without exporting credentials.
• Operations: target-service health checks, cooled-down automatic failover, portable/WebDAV backup, public-exit health, and a redacted diagnostic export.
• Runtime views: proxy selection and delay test, live traffic, connections, requests, logs, resources, and VPN lifecycle diagnostics.
• Native UI: phone, tablet, and 2-in-1 device targets built with arkit. Live window widths below 840vp use bottom navigation; wider tablet and desktop windows use a sidebar and bounded page content. Keyboard and pointer input remain available in split or narrow windows. Text fields focus on click so scrolling does not open the keyboard accidentally.
• Localization: English and Simplified Chinese.
• Automation: workspace tests, local protocol mocks, HAP export checks, device/QEMU smoke tests, and a 14-mode positive/negative protocol matrix.

Building

Prerequisites

• macOS with DevEco Studio and the HarmonyOS SDK installed.
• Rust 1.90 or a compatible newer toolchain.
• ohrs available in PATH.
• hvigorw and hdc; the packaging scripts can use the copies bundled with DevEco Studio.
• Signing material configured locally when producing a physical-device HAP.

If DevEco Studio is installed outside /Applications/DevEco-Studio.app, set DEVECO_STUDIO_HOME to its Contents directory before running these scripts.

Run ohpm install --all after changing dependencies. Paws uses the published Arkit 0.0.1-beta.0 Rust crates and Ability 1.0.0-beta.3 Rust / OHPM packages, including the matching files and URL plugins. Third-party dependencies resolve from crates.io and the OHPM registry; no local host snapshot or sibling checkout is required.

The project targets HarmonyOS 6.1 and is compatible with HarmonyOS 6.0.2. The default release package contains arm64-v8a native libraries.

Verify the source tree

scripts/verify.sh

This runs Rust formatting checks, workspace tests, ArkTS platform tests, local protocol profile generation, and an OpenHarmony aarch build.

Build an unsigned release HAP

Prepare the Go engines from the vendored bridges and pinned upstream sources; see Native engine builds for the OHOS Go toolchain and patch setup. A separate FlClash checkout is no longer required.

Provision the GeoData files required by GEOIP, GEOSITE, and ASN rules, then package the app:

scripts/fetch-geodata.sh
scripts/package-hap.sh

Output:

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

Build a signed release HAP

After configuring a valid HarmonyOS signing profile for the target device:

scripts/fetch-geodata.sh
scripts/package-hap.sh --signed

Output:

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

Do not unpack and rebuild a signed HAP with a generic ZIP utility. Doing so can change the aligned resource layout and cause application icon or launcher problems on physical devices.

See GeoData provisioning for rawfile sources and packaging requirements.

Install and launch

List connected targets:

hdc list targets

Install a signed release on a physical device:

hdc install -r \
  entry/build/default/outputs/default/entry-default-release-signed.hap
hdc shell aa start -b com.richerfu.paws -a EntryAbility

For a target selected by key, add -t <target-key> immediately after hdc.

The smoke script builds a fresh debug HAP, validates its native exports, installs the app, launches EntryAbility, and captures hilog. Pass --hap to reuse an already packaged HAP, such as the signed release:

scripts/harmony-smoke.sh \
  --hap entry/build/default/outputs/default/entry-default-release-signed.hap \
  --require-protect-success

For a route-proven performance sample on a connected phone, use:

python3 scripts/benchmark-harmony-vpn.py \
  --target <device-ip:hdc-port> \
  --engine mihomo \
  --force-global \
  --requests 1000 \
  --minimum-success-rate 99.5

The benchmark fails if it cannot observe the selected proxy in the controller chain (or independently prove a changed public exit), if the VPN process restarts, or if the declared success-rate threshold is missed. Public IP values are stored only as hashes, and the request URL is recorded for reproducibility. See the 2026-10-14 engine evaluation.

OpenHarmony QEMU

Use a standard-system image with the VPN manager, VpnExtension, /dev/tun, policy routing, SettingsData, and the system VPN authorization dialog enabled. The ohos-qemu project provides prebuilt images with that capability.

After starting QEMU, connect its forwarded HDC port:

hdc tconn 127.0.0.1:5555
hdc list targets

Then build a debug HAP and run an automated direct-mode VPN smoke:

scripts/harmony-smoke.sh \
  --target 127.0.0.1:5555 \
  --protocol-mode direct \
  --mock-bind 0.0.0.0 \
  --mock-advertise-host 10.0.2.2 \
  --auto-start-vpn \
  --require-protect-success

On first use, approve the system VPN authorization dialog. This is QEMU validation, not the DevEco simulator fallback controlled by --allow-vpn-unsupported.

Tests

Run all host-side tests:

cargo test --workspace

Generate and validate every local protocol profile:

scripts/verify-local-protocols.sh

Run the complete device/QEMU protocol matrix. Replace the address with one that the target can use to reach the development host:

scripts/harmony-protocol-matrix.sh \
  --mock-bind 0.0.0.0 \
  --mock-advertise-host <host-address> \
  --require-protect-success

The matrix covers Direct, HTTP, SOCKS5, Shadowsocks, Trojan, and VLESS, including authentication, unavailable-server, bad-password, and bad-UUID failure paths. It builds and packages one debug HAP before running all modes. Set HAP_PATH to reuse an existing debug HAP, or pass --no-build to reuse the default output. Debug Want automation requires app.debug=true in the HAP; for a signed debug package, use NATIVE_PROFILE=debug HAP_BUILD_MODE=debug scripts/package-hap.sh --signed.

Project structure

entry/                         HarmonyOS application module
  src/main/ets/                Entry, backup, and VPN extension abilities
  src/main/cpp/types/          Generated N-API declarations
  src/main/resources/          UI resources and packaged GeoData
crates/
  paws_ui/                    Native ArkUI interface and N-API exports
  paws_core/                  Runtime lifecycle and meow-rs integration
  paws_profile/               Profiles, subscriptions, rules, and persistence
  paws_vpn/                   TUN TCP/UDP and DNS forwarding
  paws_model/                 Shared data model
local-protocol-tests/          Echo servers, mock proxies, and generated profiles
scripts/                       Build, package, smoke, and regression automation
docs/                          GeoData provisioning notes

License

MIT.