Neon Pup
A menu bar app for Macs in China. It sends all of your Mac's internet through your own servers outside China, so Google, Instagram, WhatsApp and Claude work, and it keeps Claude on the same server every time so your account doesn't see a China connection.
Download the signed and notarized app at https://neonpup.bysa.app.
What you need
- A Mac with macOS 13 or newer (Apple silicon or Intel).
- SFM, the free macOS app of sing-box. Neon Pup's setup wizard
downloads and installs the tested version for you.
- Your own servers. Neon Pup comes without any. You add them as share links that start with
vless:// (VLESS Reality or VLESS over WebSocket) or hy2:// / hysteria2:// (Hysteria2). Whoever runs your servers gives you these links, and apps like Shadowrocket and Clash Verge can export them.
The full user guide is in docs/GUIDE.md. The app shows the same guide under Help.
Developers: docs/ARCHITECTURE.md explains the design and its decisions,
docs/DEVELOPING.md covers building, testing and releasing.
How it works
- The tunnel runs in SFM, sing-box's own NetworkExtension app. macOS then sends every app and every DNS lookup
through it. Neon Pup builds the sing-box config, hands it to SFM over a local address, starts and stops SFM's
tunnel, and steers the engine (servers, modes, health checks) through its local control API. Users only see
Neon Pup; a first-run wizard walks them through installing and approving SFM.
- Claude's domains (claude.ai, claude.com, anthropic.com, claudeusercontent.com, clau.de) stay on the server Claude
is using while it works, and otherwise take the first working server in your list. Their DNS goes the same way.
- China mode reconnects by itself when the tunnel drops, and "Go offline" turns Wi-Fi off.
- A small helper runs as root to install the tested SFM version (checked by hash, signature and notarization),
to end the hotel login window even if the app crashes, and to swap a China, Hong Kong or Macau time zone to
Singapore while connected. It only accepts requests from Neon Pup signed by the same Apple team.
- Server links are stored in the macOS Keychain, and SFM keeps its own copy to run them. Nothing about your servers
is bundled with the app.
See docs/ARCHITECTURE.md for the details and the open questions.
Known issues: when your real IP can show
We know about these and have not fixed them yet. In each case traffic leaves the Mac directly, from your real IP
address, for a short time. Measured on a MacBook Air with macOS 26.2 and SFM 1.14.3 in October 2026.
| When | What happens | How long |
|---|
| The Mac restarts | Wi-Fi joins about 10 seconds after boot, before anyone logs in, and the tunnel is not running yet. macOS's own services (iCloud, updates, the clock) go online directly until Neon Pup starts at login and, in China mode, turns Wi-Fi off. | About 90 seconds before login, then 2 to 3 seconds after |
| First Wake me up after a restart | The tunnel can't start until Wi-Fi has joined a network, so Wi-Fi has to come on first. | 2 to 5 seconds |
| The tunnel crashes | macOS keeps traffic blocked for about 6 seconds (SFM's "include all networks"), then drops the dead tunnel and lifts the block before Neon Pup can restart it. | 1 to 2 seconds |
Turning Wi-Fi off at shutdown did not help: macOS announces the restart, but Wi-Fi is back on at the next boot.
A fix most likely needs a rule that only lets traffic out toward your servers while the tunnel is down, without
ever locking a Mac out of the internet.
If you can close any of these, please open a pull request. The measurements and how we took them are in
docs/ARCHITECTURE.md ("Measured limits"), and tools/sfm-test.sh runs the live checks.
Build it yourself
You need Xcode's command line tools (Swift 5.9 or newer) and, to run the helper, an Apple Developer ID.
swift test # unit tests
tools/build.sh # builds and signs build/Neon Pup.app
The helper only talks to an app signed by the team in HelperConstants.teamID (Sources/NeonPupCore/HelperProtocol.swift). To run your own build:
- Change
teamID to your Apple team id.
- Run
IDENTITY="Developer ID Application: Your Name (TEAMID)" tools/build.sh.
tools/release.sh notarizes and zips the app; edit its IDENTITY and notary profile first.
Licence
Neon Pup is MIT licensed (see LICENSE). The released app bundles sing-box (GPL-3.0) for its legacy engine; its source code is at https://github.com/SagerNet/sing-box (version 1.13.7). SFM is a separate app by the sing-box developers, licensed GPL-3.0, downloaded from their official release page during setup. The China rule sets come from SagerNet/sing-geoip and SagerNet/sing-geosite.
Check the rules where you use it. Neon Pup comes with no warranty.
