Moondrop

by rayyan

A small, independent Java desktop client for protected Shadowsocks, VLESS, Trojan, Hysteria2, and TUIC connections from Shadowmere, GFP, V2rayCollector, Morpheus, V2RayAggregator, and Epodonios. Dark navy, warm text, mint accents, country flags, one list, one connection. Not an official Shadowmere release.

Interface preview with example servers and measurements.

Android

Download Moondrop for Android (Android 8.0+). Native Java interface, encrypted VPN, cached servers, Quick Connect, country flags, protocol settings, and signed-update checks. No Java installation is needed on your phone. See Android installation and build instructions.

Install

Download from the Moondrop v0.7.3 release, currently a prerelease. The Windows and macOS installers include a Temurin OpenJDK 21 runtime. You do not need to install Java separately for these installers.

Windows installer

1. Under Assets, download Moondrop-0.7.3-Windows-x64.exe for a Windows x64 PC.
2. Run the installer. It installs for your user account and creates Start menu and desktop shortcuts.
3. Open Moondrop from either shortcut.

This release is unsigned. Windows SmartScreen or Microsoft Defender may warn about an unfamiliar publisher. Proceed only if you trust the download and obtained it from the official release linked above.

macOS installer

1. Open Apple menu → About This Mac to check your chip.
2. Download Moondrop-0.7.3-macOS-arm64.dmg for Apple Silicon (M1 and newer), or Moondrop-0.7.3-macOS-x64.dmg for Intel.
3. Open the DMG and drag Moondrop.app into Applications. If that folder is not writable by your account, use ~/Applications instead.
4. Open Moondrop from Applications, then eject the installer disk.

This release is unsigned and is not notarized. If macOS blocks it, open System Settings → Privacy & Security → Open Anyway after attempting to launch, and proceed only if you trust the official download. Keep Gatekeeper enabled.

Portable ZIP or JAR

The portable download runs on Windows (x64/ARM64), macOS (Intel/Apple Silicon), and Linux x64 with Java 17 or newer. Java 21 LTS is recommended. The portable ZIP and standalone JAR do not bundle Java. A desktop Java runtime (JRE) is enough; a JDK works too. You do not need Maven or development tools to run them. The following Java setup and launcher steps apply to these portable downloads.

1. Install Java

If java -version already reports version 17 or newer, skip to downloading Moondrop.

Windows

Open PowerShell or Windows Terminal and run:

winget install --exact --id EclipseAdoptium.Temurin.21.JRE

Close and reopen the terminal, then run:

java -version

Prefer an installer? Download Eclipse Temurin 21, choose Windows, package type JRE, your CPU architecture (usually x64), and the MSI installer. Run it and keep Add to PATH enabled. Reopen the terminal to check the version. The JRE package is listed in Microsoft's WinGet catalog. See Microsoft's Java setup instructions.

macOS

Automatic setup: download and extract Moondrop below, then double-click installmacos.command. It checks for Java 17+ with desktop support. If missing, it downloads the correct Temurin 21 installer for Intel or Apple Silicon, verifies its SHA-256 checksum and macOS package signature, and asks for administrator authorization to install Java separately. It then opens Moondrop. No Homebrew is needed.

For manual installation instead:

Download Eclipse Temurin 21, choose macOS, and install the PKG:

• Apple Silicon (M1, M2, M3, and newer): choose aarch64.
• Intel Mac: choose x64.

Apple menu → About This Mac identifies your chip. If you already use Homebrew, you can instead install Temurin 21:

brew install --cask temurin@21

Open a new Terminal window and check:

java -version

Linux

Install the desktop runtime for your distribution. Do not choose a package with only headless in its name: Moondrop needs a graphical desktop.

Ubuntu 24.04 or newer (package):

sudo apt update
sudo apt install openjdk-21-jre

Debian 12 or newer (default runtime, Java 17 on Debian 12):

sudo apt update
sudo apt install default-jre

Fedora (Java 21 package):

sudo dnf install java-21-openjdk

If your Fedora release no longer provides Java 21, install its current desktop OpenJDK runtime (Java 17 or newer) or use the Temurin installer instructions.

Arch Linux (Java 21 package):

sudo pacman -Syu jre21-openjdk

Check the installed version:

java -version

2. Download the portable archive

1. Open the Moondrop v0.7.3 release. This is a prerelease.
2. Under Assets, download Moondrop.zip. The same archive works on all supported operating systems; it contains Moondrop and launchers, without Java.
3. Extract the entire ZIP. On Windows and macOS, keep that folder for running Moondrop. On Linux, the installer below copies the app to a stable location in your user account. Do not run from inside the ZIP.

You can also download moondrop.jar alone and run it with java -jar moondrop.jar.

3. Open the portable app

Windows: double-click launch-windows.bat in the extracted folder. Alternatively, open a terminal in that folder (right-click the folder background → Open in Terminal) and run:

java -jar .\moondrop.jar

macOS: first double-click installmacos.command to check/install Java and open Moondrop. For later launches, use launch-macos.command. If the setup needs executable permission, open Terminal, change into the extracted folder, and run:

cd "$HOME/Downloads/Moondrop"
chmod +x installmacos.command
./installmacos.command

Replace the example folder path with wherever you extracted Moondrop. You can also run java -jar moondrop.jar from that folder.

Linux: open a terminal in the extracted folder and install the app-menu shortcut:

chmod +x install-linux.sh
./install-linux.sh

Then open Moondrop from your application menu. No sudo is needed, and Java stays a separate installation. The installer copies the app to ${XDG_DATA_HOME:-$HOME/.local/share}/moondrop, creates ~/.local/bin/moondrop, and installs moondrop.desktop and the SVG icon under your user data directory. The stable app folder is writable by your account so automatic updates can replace the JAR.

The repository and ZIP also include moondrop.desktop and moondrop.svg. The desktop file is a template using Exec=moondrop and Icon=moondrop; the installer writes a ready-to-use desktop entry with absolute paths.

For a portable launch without installing a shortcut, run chmod +x launch-linux.sh followed by ./launch-linux.sh, or use java -jar moondrop.jar from the extracted folder.

Connect

Nearby-first ordering uses a manual country preference, or an optional approximate-country lookup. No IP geolocation request is made unless you enable Settings → Privacy & routing → Detect my approximate country. That option sends a direct HTTPS request to IPWHOIS at ipwho.is, which receives your public IP; only country and lookup time are cached for 24 hours. Manual country selection and -Dmoondrop.country=CA require no lookup and override detection. Disabling detection does not break Connect. Country-center distances affect test order; measured connection quality determines ranking.

Moondrop imports protected proxy connections from Shadowmere, GFP, V2rayCollector, Morpheus, V2RayAggregator, and Epodonios. Supported profiles are encrypted Shadowsocks, VLESS with verified TLS or REALITY, Trojan with TLS, Hysteria2 with TLS, and TUIC with TLS. Plain HTTP/SOCKS proxies, plaintext VLESS, profiles disabling TLS verification, VMess, and unsupported plugins, transports, or ciphers are excluded.

The app automatically loads Shadowmere's Shadowsocks feed; GFP's Shadowsocks, Hysteria2, and TUIC feeds; V2rayCollector's Shadowsocks and mixed feeds filtered to supported protected profiles; and Morpheus's Shadowsocks, VLESS, Trojan, Hysteria2, and TUIC bundles. Identical connections are deduplicated across sources. Rows show the source; search for GFP, V2rayCollector, Morpheus, or Shadowmere to narrow the list. If one source fails, the others still load. Country flags reflect source labels when provided; unknown locations remain unknown.

For each reachable candidate, Moondrop makes three HTTPS requests, shows the median successful latency in milliseconds and the percentage that succeeded. Lower latency and higher reliability are better. Servers that fail the initial TCP check do not receive HTTPS samples. To estimate download speed, it downloads at most 1 MiB through each of the best five servers, chosen by reliability then median latency: at most 5 MiB per testing pass, rather than a download through every server. Fresh cached download measurements are skipped. The rate is an end-to-end estimate including TLS setup, not a sustained bandwidth guarantee.

Completed checks, including failures and download estimates, are cached locally for 7 days. Results are saved as testing progresses, so closing and reopening Moondrop resumes missing checks instead of starting the full scan again. Automatic testing checks only new, changed, or expired servers. Existing working entries with one old HTTPS sample receive a three-request upgrade; the old failure cache stays intact. Older measurements remain visible until replaced. Hover a result to see when it was measured. Use Stop testing to pause; completed checks stay saved.

Click Connect. Moondrop reuses the cached quality ranking and verifies the selected server again before connecting. Ranking puts complete three-request results first, then reliability, then a score combining median latency with the estimated time to transfer 256 KiB. When download speed is unknown, the score adds one second; a failed download ranks behind other results with the same quality and reliability. Without a usable cached result, Quick Connect samples up to 256 candidates across sources and countries, limits initial address checks to eight seconds, and compares HTTPS results through up to 20 responsive candidates. This is the best connection tested, not a promise about every server or download speed. Failed checks are normally excluded until they expire or you retest. If every enabled candidate has a cached failure, Connect rechecks a sample rather than refusing immediately.

The cache reflects your machine and network; it is not a shared global ranking. After changing networks or routes, use Retest speeds to force a fresh check of every server, including cached successes and failures. A successful HTTPS check confirms that a server works from your current network. Actual censorship bypass depends on the network, server, and protocol configuration; TLS alone does not guarantee it everywhere.

On the first connection, Moondrop downloads its separate sing-box networking engine from the official upstream release and verifies its checksum. This is not a Java installation. The first launch and engine download need working internet access.

On Windows and macOS, enable Use as system proxy to route compatible applications through Moondrop. macOS may ask for permission to change network settings.

On Linux, configure your browser or application's proxy manually: choose HTTP or SOCKS5, host 127.0.0.1, port 17890. You can also use these settings in applications on Windows or macOS when system proxy mode is disabled. Moondrop is an application proxy; applications that ignore proxy settings will use their own connection.

Click Disconnect when finished. Close Moondrop normally so it can restore any system proxy settings it changed.

Optional privacy and routing

Settings → Privacy & routing keeps these controls separate from the default simple connection workflow:

The desktop panel includes Simple connection preset and One-server privacy preset, plus individual switches. Presets apply only after Save options and preserve your saved-credential protection choice. The simple preset enables automatic tests and single-hop Application Proxy Mode, and disables country detection and contact prompts. The privacy preset disables automatic testing and country detection, and enables one-server attempts with contact prompts; it preserves your chosen route. Strict blocking already active still requires Restore direct internet to release it.

Control	Desktop	Android
Automatic server testing	Optional	Optional
One-server privacy mode	Optional	Optional
Ask before contacting a proxy	Optional	Optional
Approximate country detection	Opt-in IPWHOIS lookup	No IP lookup; manual/device region only
Manual preferred country	Optional	Optional
Protect saved credentials	Optional OS-backed encryption	Always encrypted with Android Keystore
Full-device routing	Optional Linux tunnel; experimental Windows/macOS backends	Device VPN
Strict disconnect blocking	Optional nftables / WFP / PF control, depending on OS	Optional Android Always-on/Block without VPN setting
Two-hop routing	Optional	Optional, supported TCP exits
Automatic update checks	Optional	Optional; manual checks remain available

Untrusted-feed address checks, supported encryption, TLS certificate verification and update authentication are enforced independently of privacy options. CI dependency checks, SBOM generation and publisher release signing are build/release processes rather than user toggles. Windows installer signing and macOS notarization still require publisher identities.

• Privacy mode reuses cached ranking and attempts one server per explicit Connect action. It pauses background scans and does not silently try other operators after failure. A disclosure explains the selected operator's visibility before connecting. Ask before contacting a proxy enables the same single-attempt consent boundary without requiring the main Privacy-mode toggle. Ordinary automatic testing remains available when these options are off; contacted operators can see your connecting IP.
• Test selected server only makes an intentional HTTPS check. When a connection is already active, desktop tests use its local SOCKS endpoint as the detour to the new candidate. Route-specific measurements are not saved as direct-server rankings.
• Manual country and optional IPWHOIS detection control proximity; no detection occurs by default.
• Protect saved credentials encrypts desktop reusable profiles with AES-256-GCM and stores its key with Linux Secret Service (secret-tool), macOS Keychain, or Windows CurrentUser DPAPI. Non-secret endpoint metadata stays separate. This optional setting needs a working, unlocked OS store and fails clearly rather than falling back to plaintext. A locked/damaged catalog is preserved while fresh feeds remain usable in memory. Without this option, private profile files still contain reconnect credentials. Android uses Android Keystore encryption automatically.
• Two-hop routing implements an actual sing-box exit detour through the selected entry, with no direct fallback. Choose an entry from the main server list in Privacy & routing, then Connect chooses a different exit. Bulk testing is paused while two-hop mode is enabled. Entry sees your connecting IP; exit receives traffic from the entry. Independent operators are not verified, collusion/correlation remains possible, and HTTPS is still needed. Android currently supports a Shadowsocks entry with Shadowsocks, VLESS or Trojan exits.
• Erase saved profiles and test history removes the stored catalog, reusable key where available, measurements, country cache, and Linux endpoint pins. It leaves an active connection running. A failed OS-key deletion is reported separately while other history is still cleared.

Public feeds are untrusted. Remote profiles cannot nominate loopback, private/LAN, link-local, multicast, unspecified or other non-public addresses. DNS answers are validated again before connecting, and the core receives a pinned validated address while retaining its TLS server name. Only explicit manual profiles, added with a warning, can use private endpoints. Modern authenticated Shadowsocks ciphers and certificate verification remain mandatory; these are not switches for allowing unsafe feeds or disabling TLS.

Privacy mode reduces unnecessary proxy contacts; it does not stop ordinary subscription and update requests to their providers. These options do not make a public proxy operator trustworthy or guarantee censorship bypass.

Traffic coverage

The default desktop mode is Application Proxy Mode. System proxy settings on Windows/macOS cover compatible applications; applications that ignore them can connect directly. A loopback SOCKS listener is not a full-device VPN.

Windows and macOS full-device modes are selectable in Settings → Privacy & routing → Full-device tunnel, with a separate Keep internet blocked when the tunnel disconnects switch. They are experimental: the implementations, offline validation and native CI jobs are present, but real traffic/leak/crash testing on these operating systems has not yet been completed on this Linux development host. Application Proxy Mode remains the default. Windows uses an elevated, pinned engine and persistent WFP rules; macOS uses a root-owned Python broker, utun, encrypted DNS, and a dedicated PF anchor. Administrator approval is required. macOS also requires a trusted root-owned Python 3 installation and refuses incompatible PF layouts. See Windows tunnel setup and recovery and macOS tunnel setup and recovery. Disconnect retains strict blocking; Restore direct internet explicitly releases it. Windows persistent blocks can survive reboot; macOS PF blocks are cleared by reboot.

Linux x64 full-device mode is optional and requires nftables, iproute2, PolicyKit and /dev/net/tun. It installs an administrator-owned broker and a checksum-pinned networking engine, then manages TUN routing and encrypted DNS. Keep internet blocked when the tunnel disconnects adds a separate persistent-in-session firewall. A stopped engine, app crash, or removed TUN leaves ordinary direct traffic blocked. Use Restore direct internet explicitly to release it. Enabling it can prompt for administrator authorization; no host firewall changes are performed by ordinary startup or the tests. See Linux tunnel setup, limits, and recovery.

Windows/macOS desktop full-device routing is not implemented in this first Linux-focused version. Android uses its VPN service; after connecting once, its Device VPN & strict blocking setting opens Android's VPN settings for Always-on VPN and Block connections without VPN. Android enforces this blocking, and Moondrop restores only its exact approved pinned route. Moondrop itself is excluded for transport/feed access. Device-specific lockdown and handover behavior still needs physical-device coverage.

Automatic updates

Moondrop checks this project's GitHub releases in the background at launch and every six hours. Check for updates retries manually. An unavailable update service does not block browsing or connections. Updates follow published preview releases as well as regular releases.

Windows and macOS installer editions: when Download update appears, click it to open the official release page. Download the installer for your platform and chip, disconnect and close Moondrop, then install the new version. On macOS, replace the existing app in the folder where you installed it. The full installer updates the app and its bundled Java together. Saved settings and connection results remain in the data folder below.

Portable ZIP/JAR edition: a newer JAR downloads automatically and is authenticated against an Ed25519-signed release manifest, its SHA-256 digest, and application version. The trusted publisher key is embedded in the app; a replacement JAR and checksum alone are rejected. A verified staged download is reused across launches. When Restart to update appears, click it when convenient. Moondrop restores proxy settings, closes its engines, waits for the app to exit, replaces the JAR, and restarts using your separately installed Java. It keeps moondrop.jar.previous beside the JAR as a backup. This updater does not update your separate Java installation.

Portable updates require a writable app folder; move the extracted folder somewhere you own if needed. If an update cannot install or launch, the helper keeps/restores the previous app. Logs are in the updates subfolder of the data folder below. You can also close Moondrop and rename moondrop.jar.previous back to moondrop.jar for manual rollback. Older portable releases without the updater need one manual upgrade.

If it will not open

• Portable edition: “Java not found” / “java is not recognized”: install Java above, close and reopen your terminal, then check java -version. On Windows, make sure the installer added Java to PATH.
• Portable edition: Java 8 or UnsupportedClassVersionError: the launcher is finding an older Java installation. Install Java 17+ and make sure java -version reports the newer version before trying again.
• Double-clicking the JAR does nothing: use the platform launcher or java -jar moondrop.jar in a terminal. A JAR file association is not required.
• Cannot find moondrop.jar: extract the whole ZIP and keep the launcher beside the JAR. Run the command from that folder.
• No display / HeadlessException on Linux: use a graphical desktop session and install the desktop JRE listed above.
• Connecting from a censored network: saved servers appear before feed downloads finish. Quick Connect first tries a small history of servers that actually established an entry connection on this device; benchmark results alone never enter that history. Proven entries remain saved even if a feed temporarily omits them. After connecting, feed refreshes travel through the active proxy without falling back to direct downloads. Background direct speed scans pause while connected; use Test selected server for a check through your current connection. Past success is a preference, not a reachability guarantee, especially after changing networks. At least one entry must still be reachable directly. You can import a server link offline in Settings → Privacy & routing.
• First connection fails: check that your internet connection can reach GitHub for the engine download, then retry. Public servers can also go offline; refresh the list and try Quick Connect again.
• Connection was interrupted and the system proxy is stuck: reopen Moondrop and use Disconnect so it can recover the saved settings.

Remove Moondrop

Disconnect and close the app. On Windows, uninstall the installer edition through Settings → Apps → Installed apps. On macOS, move Moondrop.app from Applications to the Trash. These editions remove their private bundled runtime with the app. For portable downloads, delete the extracted Moondrop folder. For a Linux app-menu installation, also remove these files and folders (replace the data directory if you set XDG_DATA_HOME):

• ~/.local/share/moondrop
• ~/.local/share/applications/moondrop.desktop
• ~/.local/share/icons/hicolor/scalable/apps/moondrop.svg
• ~/.local/bin/moondrop

Any separately installed Java used by the portable edition stays installed for other applications.

If you also want to remove Moondrop's downloaded engine and saved state, delete its data folder only after disconnecting successfully:

• Windows: %LOCALAPPDATA%\Shadowmere
• macOS: ~/Library/Application Support/Shadowmere
• Linux: ~/.local/share/shadowmere-desktop

These older Shadowmere folder names are retained for compatibility and proxy recovery.

Use

1. Open Moondrop. Saved servers and their measured speeds appear immediately. The list refreshes in the background while Connect stays available. On the first launch, a download populates the local server-list cache. Background testing reuses fresh results and resumes missing or expired checks.
2. Click the large Connect button to choose the best tested server, or select a location and click Connect selected server. You can connect while background testing continues. Sort: recommended only changes list order.
3. On first connection, the app automatically downloads sing-box 1.14.3 for your OS and CPU from SagerNet's official GitHub release and checks its pinned SHA-256 checksum. Install engine in Advanced mode also lets you prepare it ahead of time.
4. System proxy is enabled by default on macOS and Windows for compatible apps. Change the default in Settings. Linux uses the local proxy: configure apps to use HTTP or SOCKS5 at 127.0.0.1:17890. Advanced mode reveals the per-connection proxy control.
5. Disconnect restores the previous system proxy settings and stops this app's engine.

The default Application Proxy Mode covers compatible apps; optional full-device modes and their platform validation limits are described above. Apps ignoring application proxy settings are not covered in Application Proxy Mode. macOS may require network-settings permission. On Windows this configures the current user's Internet Settings, not WinHTTP. Corporate policy, automatic discovery, and applications with their own proxy settings can override it. Local mode never modifies OS proxy settings. Public proxy operators control their servers; availability and trust vary. HTTPS certificate validation stays enabled.

Quick Connect

Reachable candidates receive three HTTPS requests using Google's connectivity endpoint. Simple mode shows latency and how recently the server was tested. Advanced mode adds reliability (successful requests out of three) and download estimates; servers failing the initial TCP check have no HTTPS samples. A bounded Cloudflare HTTPS download estimates end-to-end speed, including TLS setup. Only the best five servers by reliability then median latency enter this stable download shortlist, with at most 1 MiB each / 5 MiB per pass. Cached download results are reused for seven days, so restarting does not rotate downloads through the entire feed.

The connection ranking puts full three-request results first, reliability second, then median latency plus the estimated time to transfer 256 KiB. Unknown download speed adds one second to that score; failed downloads rank last within the same quality/reliability tier. This balances response time, repeated success, and a measured transfer estimate. It selects the best tested connection, not a globally fastest server or a sustained bandwidth guarantee.

Completed results, including failures, are saved progressively in a local 7-day cache. Reopening resumes missing checks; automatic testing checks only new, changed, or expired profiles. Legacy cache files upgrade automatically: working one-probe entries receive three-request checks, while saved failures remain cached. Older measurements remain visible until replaced. The large Connect button reuses the cached ranking and verifies the chosen connection again. A working result is usable before download testing finishes. Failed verification automatically tries other tested alternatives before reporting an error. Retest speeds forces a fresh scan; use it after changing networks or routes because results reflect your machine and network.

When no cached server succeeds, Quick Connect samples up to 256 candidates across sources and countries, spends up to eight seconds checking TCP responsiveness, then compares HTTPS results through up to 20 responsive endpoints. Both stages keep sources represented so a large feed cannot crowd out smaller ones. Cancel stops the search and closes its temporary engine. A refresh discovers new profiles; there is no background subscription polling or silent server switching. Test endpoint availability can affect results. Supported protected protocols and successful tests do not guarantee censorship bypass on every network.

Run from source

Requires JDK 17+ and Maven 3.9+:

mvn package
java -jar target/moondrop.jar

The runnable JAR works on macOS (Apple Silicon and Intel), Windows (x64 and ARM64), and Linux x64. OS proxy automation is macOS/Windows only. The first engine download requires internet access. No accounts or credentials to type.

Downloads / packaging

The release provides Windows x64 .exe and macOS Apple Silicon/Intel .dmg installers with a bundled Temurin OpenJDK 21 runtime. It also provides the portable Moondrop.zip and standalone moondrop.jar, which require separately installed desktop Java 17+. The ZIP works on macOS (Apple Silicon and Intel), Windows (x64 and ARM64), and Linux x64; it includes launchers, the Linux user installer, desktop entry, icon, instructions, and licenses.

Build the portable ZIP with JDK 17+ and Maven 3.9+:

bash scripts/package.sh      # macOS / Linux

./scripts/package.ps1        # Windows

Output: dist/Moondrop.zip. Packaging uses an explicit file list to exclude local state, downloaded engines, and runtimes from the portable archive.

Build native installers on their target operating system with Temurin JDK 21 (including jpackage) and Maven 3.9+. Windows also requires WiX 3 on PATH. Build the application first:

mvn package
bash scripts/package-macos.sh

mvn package
./scripts/package-windows.ps1

The native scripts bundle the runtime and set moondrop.distribution=native, so update checks offer the full installer instead of replacing the installed app's JAR. macOS builds use the build machine's architecture; build once on Apple Silicon and once on Intel. Release asset names are Moondrop-0.7.3-Windows-x64.exe, Moondrop-0.7.3-macOS-arm64.dmg, and Moondrop-0.7.3-macOS-x64.dmg. These installers are unsigned; macOS packages are not notarized.

GitHub Actions builds the three native installers and portable downloads, and tests the native networking engine on Linux, macOS Apple Silicon, macOS Intel, and Windows. The sing-box engine downloads separately on first connection.

Verification

mvn test
mvn -Dengine.test.path=/absolute/path/to/sing-box test
java -jar target/moondrop.jar --install-engine
java -jar target/moondrop.jar --smoke-test

The integration test runs a real local Shadowsocks server and client, verifies an encrypted HTTP round trip, and checks child-process/config cleanup. The smoke test fetches live servers, runs Quick Connect, verifies HTTPS through the winning server, then disconnects. Neither changes system proxy settings. Isolate data with -Dshadowmere.dataDir=/temporary/folder before -jar.

Native macOS/Windows system-proxy behavior must be acceptance-tested on those platforms, including an existing manual proxy, PAC configuration, disconnect, engine failure, forced quit, and recovery at next launch. Linux validation does not substitute for those checks.

State and recovery

• macOS: ~/Library/Application Support/Shadowmere
• Windows: %LOCALAPPDATA%/Shadowmere
• Linux: ~/.local/share/shadowmere-desktop

Moondrop keeps the original Shadowmere-named data folders for compatibility and recovery across the rename. Only one app instance can own the proxy settings. A durable snapshot is written before system settings change and removed after restoration. An interrupted session is recovered on next launch. A force-killed app can leave system proxy settings enabled until then; reopen Moondrop to restore them. Startup terminates leftover cores only when a private ownership record matches their PID, start time, and executable; session files must belong to this app's data directory. If settings recovery fails, the snapshot is retained and a live listener is kept available while you retry Disconnect. Server profiles, including the credentials needed to reconnect, are saved locally in server-catalog.json. On macOS and Linux this file is restricted to its owner; Windows uses the user profile’s permissions. The list appears before network refresh finishes and remains usable if refresh fails. Temporary engine configurations are removed on disconnect and after startup recovery. Median latency, reliability, download estimates, their timestamps, and hashed connection identifiers are persisted in server-performance.json; passwords are not stored in that cache. No browsing history is persisted. The profile cache is local and is never included in releases or copied diagnostics.

Architecture and credits

Bundled SVG flags render consistently without requiring emoji fonts. Java 17 + Swing/FlatLaf, Gson, Apache Commons Compress. The UI stays on the event thread; feed requests, engine installation, and connection work run off-thread. A single sing-box process provides the loopback HTTP/SOCKS endpoint and the selected protected proxy protocol. The benchmark uses one separate temporary core with isolated routing per candidate.

Shadowmere's API implementation supplies active server records; SagerNet sing-box supplies the networking core. This project's code is GPL-3.0-or-later; dependencies retain their own licenses. See THIRD_PARTY.md.

Settings

Open Settings in the top right to choose automatic update checks, background server tests, and the default system proxy preference. Advanced mode is off by default and saved between launches. Enable it to reveal protocol switches and nearby-first testing in Settings, plus local proxy controls, detailed measurements, and engine activity in the main window. Turning it off preserves your protocol choices and active connection. Nearby ordering changes apply when refreshing servers.

Select Show server details for the selected server’s protection explanation and measurements without enabling Advanced mode. The main button changes from Connect to Cancel during an attempt and Disconnect once connected. Status text explains saved-server checks, verification, fallback, and applying system proxy settings.

Connection errors offer Try another server, Retest servers, and Copy diagnostics. Diagnostics are also available in Settings and include app/Java/OS versions, settings, server counts, and a broad error category. They exclude server addresses, credentials, paths, and raw logs.

Protocol badges and preferences

Every server row shows its protocol badge. Select a server to see its short strength label, and expand Show server details for an explanation: Shadowsocks Encrypted proxy, VLESS TLS encryption or REALITY camouflage, Trojan TLS camouflage, Hysteria 2 HTTP/3 camouflage (or Obfuscated QUIC when configured), and TUIC TLS over QUIC. These describe the configured transport, rather than ranking encryption strength or claiming post-quantum protection.

In Settings → Advanced mode → Protocols, toggle Shadowsocks, VLESS (including REALITY), Trojan, Hysteria 2, and TUIC. Disabled protocols disappear from the browser and are excluded from Quick Connect and background tests. An existing connection remains active until you disconnect. Re-enabling a protocol restores its servers and saved test results without a feed refresh. All protocols start enabled; disabling all of them shows a prompt to enable a protocol.

Protocol descriptions follow the Shadowsocks documentation, sing-box VLESS settings, REALITY documentation, Trojan overview, Hysteria 2 documentation, and sing-box TUIC settings.

The release workflow also runs the updater integrity, replacement, restart and rollback tests with the Java runtime inside each Windows and macOS package. It checks that native launchers select full-installer updates. Portable update fixtures use paths containing spaces and Unicode characters.

Publisher signature format, key handling, build inventories/provenance and reproducibility limitations: Release security. Windows Authenticode and macOS notarization require publisher identities and are not yet available.