Swihomo

A native SwiftUI mihomo client for iOS and macOS

Swihomo is a universal SwiftUI app that runs the mihomo core directly inside a Packet Tunnel Network Extension — no separate CLI process, no system TUN interface, and no local SOCKS bridge.

Usage

Download from App Store (coming soon at $2.99) or TestFlight (limited). You can also build from source and sign by yourself.

Import a local YAML file or add a remote HTTP(S) subscription to start. Mobile devices can also import remote profile by scanning a QR code. Subscriptions support a custom User-Agent; leave it empty to use the default ClashMeta/<mihomo-version>.

Overrides

You can write custom YAML that is deep-merged into the active profile with Mihomo Party syntax:

• key! replaces an entire object
• +key prepends array items
• key+ appends array items
• <key> escapes a literal key that starts or ends with +

Basic override settings (routing mode, log level, ports, etc.) are applied after custom YAML, so they always have final priority. Save your changes and reconnect the tunnel to apply them.

Hint for Geo Databases

Apple imposes strict memory limits (approximately 50–70 MB) on Network Extension on mobile devices; exceeding this limit results in the process being forcibly terminated.

Geo databases require significant memory to operate; the database itself often consumes 30 MB or more upon startup, and this figure can increase depending on some configuration.

Therefore, if your VPN frequently disconnects unexpectedly or fails to start altogether, please check whether your configuration includes Geo databases; if possible, replace them with rulesets.

Build

Prerequisites:

• Xcode 26 or newer
• Go toolchain
• An Apple Developer team authorized for the Packet Tunnel entitlement

git clone --recurse-submodules https://github.com/ruattd/swihomo.git
cd swihomo
bash scripts/build-mihomo.sh
open Swihomo.xcodeproj

In Xcode, select your development team and update the bundle identifiers for both Swihomo and PacketTunnel. Test on a signed macOS host or a physical iOS device — the simulator cannot run a Packet Tunnel.

Development

Repository layout

Swihomo/              SwiftUI app, shared models, and services
PacketTunnel/         Packet Tunnel extension and Swift-to-C bridge calls
Vendor/mihomo/        mihomo fork submodule, tracking ruattd/swihomo-core Alpha
scripts/              Core build and version-sync scripts
docs/                 Documentation site files

Vendor/MihomoCore.xcframework is generated by the build script and intentionally ignored by Git.

Architecture

SwiftUI app
    |
    | NETunnelProviderSession provider messages
    v
Packet Tunnel extension
    |
    | NEPacketTunnelFlow <-> C bridge <-> mihomo sing-tun gVisor stack
    v
Embedded mihomo core

The app stores profiles in its private Application Support container and passes the active YAML plus runtime overrides to the extension via NETunnelProviderProtocol.providerConfiguration. The extension owns the core and the controller secret; the app talks to it only through provider messages. More details are in the Mihomo bridge documentation.

Updating the core

The mihomo fork is a submodule pinned to the swihomo branch of ruattd/swihomo-core. Rebuild the XCFramework after updating it:

git submodule update --remote --merge Vendor/mihomo
bash scripts/build-mihomo.sh

The build also generates Swihomo/Shared/MihomoCoreVersion.swift from mihomo's constant.Version, keeping the default subscription User-Agent in sync with the core.

Screenshot demo data

Add --screenshot-demo to the app scheme's launch arguments for deterministic screenshots. The app then uses bounded in-memory fixtures without starting the tunnel or making network requests.

License

Swihomo itself is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). The embedded mihomo core is licensed under GPL-3.0 — any distributed build that includes it must meet the corresponding GPL source-distribution obligations.