gitwtfhub

wtf is opensurge-for-mac?

ytwsy/opensurge-for-mac — explained in plain English

Analysis updated 2026-08-13

2,027GoAudience · ops devopsComplexity · 4/5LicenseSetup · hard

TL;DR

Turns a Mac into a home network gateway that gives each device on your network its own proxy and routing rules, similar in style to Surge.

Mindmap

mindmap
  root((OpenSurge for Mac))
    What it does
      Whole home gateway
      Per-device routing
      Menu bar plus web GUI
    Tech stack
      Go
      mihomo proxy engine
      dnsmasq DHCP DNS
      SwiftUI menu bar
    Use cases
      Bypass gateway for one device
      DHCP takeover for whole LAN
      Isolated downstream network
    Audience
      Home network tinkerers
      Ops and networking users

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Route a specific device like a phone or game console through a Mac based gateway.

REASON 2

Take over DHCP and DNS for a home network so every device auto-connects.

REASON 3

Set up an isolated downstream network with its own SSID or VLAN for testing.

REASON 4

Import an existing mihomo proxy configuration and manage it from a menu bar app.

What's in the stack?

GomihomodnsmasqSwiftUIReact

How it stacks up

ytwsy/opensurge-for-maccompozy/compozyboldsoftware/meat
Stars2,0272,0252,002
LanguageGoGoGo
Setup difficultyhardmoderateeasy
Complexity4/53/52/5
Audienceops devopsdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · hard Time to first run · 1h+

Requires macOS 13+ and comfort configuring DHCP/DNS or router settings, the installer is unsigned so Gatekeeper must be manually approved.

You can use and modify the code, but if you distribute it or a modified version, you must also share the source under the same license.

Wtf does this do

OpenSurge for Mac turns a Mac into a whole home network gateway, similar in style to the Surge proxy app, that can route traffic differently for each device on your home network. It is aimed at people who want more control than a typical router over how their devices reach the internet, letting some devices go through a proxy or filtering setup while everything else stays untouched. There are three ways to use it. In the simplest mode, your main router keeps handling DHCP as normal, and you manually point specific devices, like your phone or a game console, to the Mac by giving them a fixed address and setting the Mac as their gateway. A more advanced mode has the Mac take over DHCP and DNS duties for your whole local network, so any device that joins automatically gets configured to use it, no manual setup per device required. A third mode creates a separate downstream network, using its own access point, wireless network name, or VLAN, that runs entirely through the Mac without touching your existing network at all. Once a device is connected, you can set an individual outbound policy for it, such as routing a phone and a Mac through the same rules, sending a game console straight to its game servers, or letting a television or media player pass through with as little interference as possible. Under the hood, dnsmasq handles DHCP and DNS, mihomo acts as the proxy engine, and macOS built in packet filtering along with IPv4 forwarding provide the actual network path. The project ships with a menu bar app and a local web control panel that shows connection status, live upload and download speeds per device, and lets you check whether the network is healthy or needs attention. It supports importing an existing mihomo configuration or subscription, so you keep your current proxy nodes and rules rather than starting over. It is written mostly in Go, requires macOS 13 or newer, provides installers for both Apple Silicon and Intel Macs, and is released under the GPL 3.0 license. Because misconfigured network gateways can disrupt an entire home network, the project also includes an isolated virtual lab setup meant for testing risky network behavior safely before applying it to a real network.

Yoink these prompts

Prompt 1
Walk me through setting up OpenSurge for Mac in bypass gateway mode for a single device.
Prompt 2
Explain the difference between bypass routing, DHCP takeover, and independent downstream LAN modes.
Prompt 3
How do I import my existing mihomo subscription into OpenSurge for Mac?
Prompt 4
What do I need to check before installing the unsigned OpenSurge for Mac package?
Prompt 5
Show me how per-device outbound policies work in OpenSurge for Mac.

Frequently asked questions

wtf is opensurge-for-mac?

Turns a Mac into a home network gateway that gives each device on your network its own proxy and routing rules, similar in style to Surge.

What language is opensurge-for-mac written in?

Mainly Go. The stack also includes Go, mihomo, dnsmasq.

What license does opensurge-for-mac use?

You can use and modify the code, but if you distribute it or a modified version, you must also share the source under the same license.

How hard is opensurge-for-mac to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is opensurge-for-mac for?

Mainly ops devops.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.