OpenSurge for Mac is a Surge-style macOS gateway and control plane. It uses dnsmasq for DHCP/DNS, mihomo as the proxy engine, and supports per-device routing, TUN-based transparent proxy, a web GUI, and a menu-bar app. It provides CLI tools for status, policies, rendering, and start/stop operations.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (2 so far).
What it is
OpenSurge for Mac is an open-source Surge-style gateway and control plane for macOS. It renders the Mac as a full-network proxy gateway with DHCP/DNS takeover, per-device routing, and a UI workflow for subscription import, network settings, device policies, and health checks. It can import mihomo configurations or profiles and exposes a Web GUI plus a menu-bar app for status and alerts. The underlying components include dnsmasq for DHCP/DNS, mihomo as the proxy engine, and pf with IPv4 forwarding for gateway paths.
How it works
The gateway relies on dnsmasq to provide DHCP/DNS, mihomo as the proxy engine, and macOS pf plus IPv4 forwarding to create the gateway path. It can render or import mihomo configurations, render final Mihomo config, and validate Mihomo with its own tooling. It exposes a local Control API, a React Web GUI, and a read-only SwiftUI menu-bar launcher. It supports explicit per-device policy via a mihomo selector group and can generate fixed IPv4 leases per device under DHCP takeover. Transparent proxy paths on macOS use TUN (with redir/disallowed in the Darwin build set to 0). It provides status and diagnostic outputs in text or JSON formats.
Getting started
Installation and usage walkthroughs are available via the README links and App Guide. The repository provides commands for building the Web GUI and control components:
make web-install
make control-build
./bin/opensurge-control --config examples/config.example.yaml
make menubar-build
For rendering Mihomo configurations and validating profiles:
go run ./cmd/omg doctor --config examples/config.example.yaml
go run ./cmd/omg render-mihomo --config examples/config.example.yaml
go run ./cmd/omg validate-mihomo --config examples/config.imported-profile.example.yaml
And to start, reload, restart Mihomo, or stop the gateway:
sudo go run ./cmd/omg start --config examples/config.example.yaml --format json
sudo go run ./cmd/omg reload --config examples/config.example.yaml --format json
sudo go run ./cmd/omg restart-mihomo --config examples/config.example.yaml --format json
sudo go run ./cmd/omg stop --config examples/config.example.yaml --format json
The README contains additional steps for installing unsigned Release packages and verifying with SHA sums and GitHub attestations.
Recent releases
Latest release: v0.1.23 OpenSurge for Mac v0.1.23 (2026-07-28). Prior entries include v0.1.22 (2026-07-27), v0.1.21 (2026-07-26), v0.1.20 (2026-07-24), v0.1.18 (2026-07-21).
Traction
GitHub stars: 1511; stars_1d: 232; forks: 94; open_issues: 7.
Behind the repo
Not provided in the README excerpt.
Caveats
- License: GPL-3.0-only. OpenSurge for Mac uses GPL-3.0-only licensing for the main code.
- Security and system permissions: start/stop require sudo as the gateway manages DHCP, pf, and IPv4 forwarding.
- macOS TUN-based transparent proxy is the supported path; other proxy redirection is disabled in Darwin builds (redir-port and pf redirect_tcp_to should be 0).
- The GUI components include a Web GUI, a control service, and a menu-bar launcher; installation notes mention signed/notarized packaging workflows and unsigned release packages with architecture-specific installers.