Skip to content
leaperonePublic

About

GPUI macOS controller for a bundled mihomo core

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

myproxy

macOS menu-bar controller (GPUI) for a bundled mihomo core.

Strategy JSON under ~/Library/Application Support/myproxy/ is the source of truth: subscriptions, node groups, rules, and Mixed port (HTTP + SOCKS5, loopback unless 设置 opens it to the LAN). The UI is Chinese: 总览, 连接, 订阅, 节点组, 规则, 设置.

总览 → 入门指南 expands on the first visit and starts collapsed in later windows. Reopen it at any time; 功能说明 on the other pages reveals optional explanations. Runtime status, permission prompts, and safety warnings remain visible with the controls they describe.

Install

Download myproxy-*.sparkle.zip from Releases, unzip, and move myproxy.app into Applications.

If the build is not Developer ID–notarized, macOS Gatekeeper may require a right-click → Open the first time.

Updates

Choose 正式版(Prod) or Nightly under 设置 → 高级设置 → 更新 → 更新通道, then use 检查更新 or the menu-bar extra. The choice is saved in strategy.json; older configurations default to the installed build's channel. Switching back to Prod receives the next newer Prod build and does not downgrade the installed app.

Channel Sparkle feed CI/CD
Prod https://github.com/leaperone/myproxy/releases/latest/download/appcast.xml Push a vMAJOR.MINOR.PATCH tag, or run Release with channel prod and that existing tag.
Nightly https://github.com/leaperone/myproxy/releases/download/nightly/appcast.xml Builds main daily at 18:00 UTC, or run Release with channel nightly.

Nightly builds are GitHub prereleases with immutable build tags. The nightly prerelease points to the latest Nightly feed. Both channels generate Sparkle deltas from recent same-channel archives; Nightly never replaces GitHub's latest stable release. Existing published Prod tags cannot be overwritten by the workflow. While the core is connected, Check for Updates and archive/delta downloads use Mixed as an HTTP proxy.

Cargo.toml holds the next target release version. Prod uses v<version>. Nightly uses v<version>-nightly.<YYYYMMDD>.<run_number>.<attempt>, with the UTC date and Release workflow run number and attempt. The app displays the same version without the v prefix. Release notes record the source commit. When a Prod release is ready, tag its matching commit, then advance main to the next target version. Nightly tags do not trigger the Prod workflow.

Both channels use the Release workflow's run number and attempt as CFBundleVersion, so Sparkle can compare builds across channels. The display version, build number, feed, and channel are validated against the packaged app before publication. A manually dispatched Prod release checks out the requested tag; its version must match Cargo.toml at that commit.

The title shows Dev for development builds and Nightly for Nightly builds; Prod has no badge. This identifies the installed build, independently of the selected update channel or developer logging. Local debug builds default to Dev and release builds to Prod; MYPROXY_BUILD_CHANNEL=dev|prod|nightly overrides this at build time.

The repository's release skill handles /release patch, /release minor, /release major, and /release nightly ($release in Codex). Stable increments start from the latest published Prod version, so an already-advanced development version is not incremented twice. Creating or reviewing the skill does not publish a release.

Develop

scripts/fetch-mihomo.sh
scripts/fetch-sparkle.sh          # Sparkle.framework + generate_appcast
cargo run --bin myproxy           # debug UI, no Sparkle
MYPROXY_PAGE=connections cargo run --bin myproxy
scripts/package-macos-app.sh      # release .app with Sparkle
scripts/release-macos.sh          # zip + appcast into dist/
cargo run --bin myproxyctl -- capabilities

Browser extension

The browser extension lives under browser-extension/. It keeps only browser-scoped website rules and sends matching requests to the existing Mixed listener; nodes, subscriptions, DNS, and routing remain owned by myproxy.

scripts/package-browser-extension.sh chromium
scripts/package-browser-extension.sh firefox
scripts/package-browser-extension.sh safari

Chrome/Edge use a PAC script and Firefox uses the WebExtension proxy listener. Safari has no WebExtension proxy API, so its packaged resources use the native messaging protocol documented in browser-extension/safari/native-bridge.md.

Rust 1.98+ (rust-toolchain.toml). Info / Warning / Error always go to myproxy.log; 设置 → 高级设置 → 日志 shows the tail. Subscription URLs are never written.

CLI

myproxyctl is included in myproxy.app/Contents/MacOS/ and updated with the app. Open 设置 → 高级设置 → 命令行工具 to create or update the ~/.cargo/bin/myproxyctl PATH link. 复制 Agent skill copies the official instructions from .agents/skills/agent/SKILL.md. 安装说明 opens the optional installation dialog. The MacBook Air install script creates the same PATH link automatically.

The in-app installer refuses to replace an existing regular file. If a terminal cannot find myproxyctl, add ~/.cargo/bin to PATH. You can still invoke /Applications/myproxy.app/Contents/MacOS/myproxyctl directly.

All commands accept --json for one machine-readable success result on stdout. Runtime errors return a JSON error on stderr and a non-zero exit. The official Agent CLI skill explains how to inspect and configure myproxy.

On macOS, the bundled CLI sends apply, subscription refresh, connect, disconnect, and runtime status queries to the signed application. Commands that change runtime state open that same app in the background if needed, without triggering its launch-time connection setting. status does not launch the app; if the Host is unavailable, System Extension and DNS are reported as unobserved. Pending authorization stays with the application after the CLI exits. If a command loses its reply, check status before retrying.

myproxyctl --json capabilities
myproxyctl --json status
myproxyctl --json group list
myproxyctl --json export
myproxyctl --json import ~/Downloads/myproxy-strategy-2026-09-10.json

export writes the current strategy.json (default ~/Downloads/myproxy-strategy-YYYY-MM-DD.json). import replaces the live file after writing strategy.json.bak-import-* and does not apply; run apply if the core should pick it up. The 设置 → 高级设置 → 配置 panel uses file dialogs and also creates a backup. In the app, importing while a connection is requested applies the configuration immediately; otherwise it takes effect on the next connection or apply.

cargo run --bin myproxyctl -- subscription add 'https://…' --name Example
cargo run --bin myproxyctl -- subscription set Example --name HK
cargo run --bin myproxyctl -- filter --set '(?i)(流量|剩余|到期|官网)'
cargo run --bin myproxyctl -- group add PROXY --all
cargo run --bin myproxyctl -- rule add --name GitHub --keyword github --via PROXY
cargo run --bin myproxyctl -- apply
cargo run --bin myproxyctl -- connect

Default Mixed port is 7890.

To let devices on the same LAN use this Mac as a proxy, enable 设置 → 手动代理 → 允许局域网设备使用 or run myproxyctl mixed-lan on. Configure the other device with this Mac's LAN IP and the manual proxy port.

Mixed has no inbound password and listens on all network interfaces when enabled. Leave the switch off on untrusted networks. VPN, hotspot, and firewall rules can make the port reachable from other networks. The controller, DNS, and System Extension listeners stay on loopback. Run myproxyctl mixed-lan off to close the LAN listener. Apply or reconnect after changing the setting.

Routing and runtime state

strategy.json stores the saved configuration. Saving, applying, Mihomo readiness, System Extension activation, and DNS readiness are separate states. Apply validates the candidate before replacing a running configuration. Synchronous activation failures are reported and trigger an attempt to restore the previous configuration. Once the Host accepts an asynchronous System Extension request, later capture or DNS failures are reported separately and do not trigger that rollback. A working Mixed listener does not prove automatic capture is active. Explicit proxy clients can keep working while System Extension capture or DNS interception is down.

The Supervisor monitors the applied configuration, including capture and DNS when System Extension is required. An accepted enable request stays pending until the Host confirms capture, DNS, and the matching request revision. Startup or unknown status has a 120-second grace period; waiting for approval or a system reboot stays pending without automatic resubmission. Confirmed failures and startup timeouts use the existing bounded recovery loop with the same applied request and credentials. Attempts are cleared only after all required components are ready. After five failed recoveries, myproxy releases capture, DNS, and the system proxy as on disconnect. If release cannot be confirmed, it keeps the core and retries cleanup.

The protected runtime-state.json keeps the applied YAML and matching System Extension request together. An older running core without this snapshot requires one disconnect and reconnect before applying changes. MYPROXY_DATA_DIR overrides the data directory for isolated command checks; normal launches keep the standard application support directory.

  • Groups resolve pins in order, then automatic matches. Exact exclusions apply to both; name exclusions apply only to automatic matches. Empty groups reject traffic and show as unavailable instead of silently routing it directly.
  • Matchers inside one rule are OR conditions. Rules are evaluated in their displayed order, after built-in local-network bypasses, and only after traffic enters Mixed, System Extension, or TUN. Mixed and System Extension each have their own mode; TUN follows the profile rules and is mutually exclusive with System Extension.
  • Each DIRECT domain or suffix rule can enable 网站解析仅用 IPv4. The strategy stores this as dns_ipv4_only; proxy and reject rules keep fake-IP hostname matching. Process, keyword, and CIDR matchers do not provide DNS policies.
  • gfw:<group> is evaluated by mihomo (RULE-SET,gfw then DIRECT on a miss). System Extension still captures the user's own process and domain/suffix/keyword/cidr matchers, including pins whose via is gfw:<group>. It does not embed the GFW domain list.
  • The connections page shows connections recorded by Mihomo. System Extension traffic passed directly to macOS or rejected before Mihomo is outside that list; 显示直连 reveals only DIRECT connections recorded by the core.
  • System Extension DNS interception stays coupled to the core: disconnect waits until capture and DNS are down before stopping Mihomo. If NEDNSProxy cannot be disabled, the core is kept so system resolution is not blackholed.
  • With System Extension on, public lookups (including public names asked of the router) are answered by Mihomo's fake-ip DNS, so apps see 198.18.x addresses and Mihomo applies domain rules when they connect. Apps that an app rule sends DIRECT get real addresses. If Mihomo's DNS stops answering, lookups fall back to a real resolver within about ten seconds and return to fake-ip when it recovers. LAN names such as .lan, .local, and single-label hosts still go to the LAN resolver. When a lookup goes direct and macOS reports the queried name instead of a resolver address, the provider uses the strategy's dns.nameserver list. DNS readiness reported in the app proves the private SOCKS listener is reachable, not that every lookup resolves.

Source checks and builds do not verify macOS approval, DNS forwarding, or actual traffic. Those require acceptance on the signed installed application.

Signing

Local packaging uses a Developer ID identity from the login keychain when one exists; otherwise it ad-hoc signs. Both CI release channels require Developer ID signing, notarization, and Sparkle signatures:

Secret Purpose
SPARKLE_ED_PRIVATE_KEY EdDSA seed for generate_appcast / sign_update (required for in-app updates)
APPLE_ID / APPLE_TEAM_ID / APPLE_APP_SPECIFIC_PASSWORD Required notarization
CSC_LINK / CSC_KEY_PASSWORD Base64 Developer ID certificate and its password
MYPROXY_HOST_DEVID_PROFILE / MYPROXY_NETWORK_EXTENSION_DEVID_PROFILE Provisioning profiles needed for System Extension activation

Do not commit .env, .p12, or the Sparkle private key.

About

GPUI macOS controller for a bundled mihomo core

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages