OpenSurge-for-Mac is a free, open source networking & connectivity project written in Go and released under GPL-3.0. It has 2,367 GitHub stars, 166 forks and 9 open issues, and was last pushed 37 hours ago. On this registry it ranks #13 of 14 tracked projects in Networking & Connectivity, with 5 head-to-head comparisons available.

What is OpenSurge-for-Mac?

OpenSurge for Mac is an open-source, GPL-3.0 macOS gateway and control plane that turns a Mac into a Surge-style whole-home transparent proxy gateway with IPv4 and IPv6 support, built for home-network operators and small labs that want per-device routing without swapping out their main router.

What it is

OpenSurge for Mac combines a macOS menu bar app, a local Web GUI and a set of system-level components into one control surface. Below the interface it drives mihomo as the proxy engine and dnsmasq for DHCP and DNS, while IPv4 traffic takes a native gateway path through macOS pf and forwarding. Experimental IPv6 takeover works differently: dnsmasq RA/SLAAC/RDNSS, a macOS BPF packet broker and a mihomo user-space data plane built from patched sources cover TCP, UDP and QUIC over UDP/443, preserving MAC identity for per-device policy. The project is written in Go, licensed under GPL-3.0, and documented at opensurge.pages.dev.

The concrete problem it solves is the friction of routing individual devices. Rather than editing gateway and DNS settings on every phone, television, console or headset, an operator registers devices once and lets OpenSurge hand out DHCP and DNS automatically in LAN DHCP takeover mode or from an independent downstream LAN, or keeps the main router in charge and points only chosen devices at the Mac in bypass-router mode. In DHCP takeover it takes over the DHCP/DNS role the main router would otherwise fill.

Key capabilities

• Three gateway modes — bypass router, LAN DHCP takeover and independent downstream LAN — each able to enable experimental IPv6 takeover.
• Transparent proxy through mihomo TUN, plus an explicit proxy on mihomo mixed-port.
• dnsmasq-powered DHCP and DNS, with fixed IPv4 leases generated for MAC-registered devices in DHCP takeover mode.
• Per-device policy from a single mihomo process: each device gets its own selector group and SRC-IP-CIDR rules, with device-specific REJECT actions and overrides by domain, IP, protocol, port or rule provider.
• Tailscale and Headscale as on-demand mihomo outbounds, scoped by MagicDNS suffix, tailnet peer or explicit subnet route, with a chosen Exit Node added as a policy group.
• Observability that attributes live sessions to devices and shows connection counts, real-time up/down rates, cumulative bytes and the dominant mihomo outbound chain, plus text or JSON status, doctor, logs and snapshot output.
• Config validation, rollback on start and stop, an explicit recovery contract, and an isolated virtual LAN lab for validating high-risk network behavior before it touches a real LAN.

Who uses it and how

• Households that want only some devices routed start in bypass-router mode: the main router keeps DHCP, and chosen devices get a stable IPv4 with gateway and DNS pointed at the Mac.
• Households that want the whole LAN to join automatically use LAN DHCP takeover, guided by a recovery state machine through start, client acceptance, stop and network restore; the main router DHCP must be disabled and then restored.
• Operators with a separate AP, SSID or VLAN use independent downstream LAN mode, where the Mac supplies DHCP, DNS and gateway for that network without disturbing the existing LAN.
• Mixed-device homes assign different exits per device: phones and Macs on rule-based routing, consoles to US servers, televisions to streaming nodes.
• People with remote network needs attach Tailscale or Headscale as a limited outbound so specific Macs or downstream devices reach a tailnet, without granting every device that path.

Getting started

The README points to the macOS app distributed from the project site at opensurge.pages.dev, where it installs as /Applications/OpenSurge.app and reopening it expands the same status panel as the menu bar icon. First-time setup and the three network modes are covered in the project guides, including docs/app-user-guide.zh-CN.md.

How it compares

No list of paid products is provided in the facts, so the honest framing is that OpenSurge sits on top of tools it does not replace: mihomo remains the proxy engine, dnsmasq provides DHCP and DNS, and Tailscale or Headscale supply remote outbound connectivity. Its role is the orchestration layer those tools lack on macOS — mode selection, per-device policy, rollback and observability around them.

When to use it — and when not to

A self-hoster must run a Mac as an always-on gateway and operate dnsmasq, mihomo, pf NAT and IPv4 forwarding together; in DHCP takeover mode, anything that stops serving DHCP and DNS can cut the LAN off from both. Anyone unwilling to accept that risk, or not running macOS, should look elsewhere, and the keep-awake toggle that prevents sleep is off by default and lasts only for the current run, so a laptop that closes its lid can drop the gateway. IPv6 takeover is explicitly experimental, and much of the documentation, including docs/device-policy.zh-CN.md and docs/faq.zh-CN.md, is written in Simplified Chinese first.

project readme (upstream, from github) — read inline

OpenSurge for Mac

把 Mac 变成可按设备分流的 Surge 风格全屋透明代理网关——既可让指定设备通过旁路由手动接入，也支持 DHCP/DNS 自动接管与实验性下游 IPv6 接管

简体中文 · English

官网 · 下载 · 使用文档 · App 指南 · 能力 · 每设备策略 · Web GUI · Agent 工作区

OpenSurge for Mac 是一个开源的 Surge 风格 macOS 网关与控制面。多数用户可以先从 旁路由模式开始：主路由 DHCP 保持开启，只让需要接入的设备使用稳定 IPv4，并把网关和 DNS 指向 Mac。需要让同一局域网的设备自动接入时，也可以选择局域网 DHCP 接管；有独立 AP、SSID 或 VLAN 时，则可以使用独立下游 LAN。三种模式均可按需启用实验性的 IPv6 接管。

无论采用哪种模式，你都可以为已登记设备配置不同的出口策略：手机和 Mac 一起走规则 分流、游戏机连美服、电视走流媒体节点。在局域网 DHCP 接管和独立下游 LAN 模式下， 接入相应网络的手机、电视、PS5 和 VR 设备，都可以自动从 Mac 获取 DHCP/DNS，无需逐台 修改网关和 DNS。

想了解 OpenSurge 的具体功能、安装配置和常见使用场景，请访问 OpenSurge 官网。

功能介绍 · 使用指南 · 用户文档

• 导入已有的 mihomo 配置或订阅是可选能力；默认折叠的全局附加配置可以单独添加节点、 Provider、策略组、DNS 与规则。即使网关停止、没有任何导入源，也能在策略页预览最终 合成结果、选择节点和检测延迟，或从 Web GUI 直接启动同一份配置；刷新订阅或保存草稿 不会自动改变运行中的网关
• Web GUI 实时展示每台设备的连接、上下行流量和实际出口链；菜单栏随时查看网关状态与恢复提醒。
• 菜单栏与 Web GUI 提供默认关闭、仅本次运行有效的合盖保持运行开关。

底层由 dnsmasq 提供 DHCP/DNS，mihomo 作为代理引擎。IPv4 使用 macOS pf 与 forwarding 提供原生网关路径；实验性的下游 IPv6 则由 dnsmasq RA/SLAAC/RDNSS、 macOS BPF packet broker 和本项目补丁构建的 mihomo 用户态数据面共同接管。

这个仓库也被有意设计成一个 AI Agent 友好工作区：项目知识与代码一起版本化，高风险 网络行为有可执行的证据门槛，Virtual Lab 与真实设备产生的证据会回流到下一轮工程 循环。

能力

友好的 App 体验

• 通过 macOS 菜单栏 App 随时查看状态、接收网络恢复提醒并打开本地 Web GUI；再次打开 /Applications/OpenSurge.app 会直接展开与菜单栏图标相同的状态面板；
• 按需临时阻止空闲与合盖睡眠；开关不依赖网关状态，不保存偏好，退出 OpenSurge 或重启 Mac 后恢复正常睡眠；
• 在一个控制面中完成订阅导入、网络设置、设备分流、节点健康、连通性检查与诊断；
• 使用恢复状态机引导局域网 DHCP 接管的启动、客户端验收、停止和网络恢复。

第一次使用请参阅 OpenSurge for Mac App 使用指南。遇到常见 网络、TUN 或设备配置问题时，请参阅 常见问题。

网关与代理

• 启停 DHCP/DNS、mihomo、pf NAT 与 IPv4 forwarding，并带 rollback；
• 通过 mihomo mixed-port 提供显式代理；
• 通过 mihomo TUN 提供 macOS 透明代理；
• 把 Tailscale / Headscale 作为 mihomo 的按需出站：可按 MagicDNS 后缀、Tailnet peer 或明确的 subnet route 限定 Mac/下游设备访问，也可把指定 Exit Node 作为独立策略组加入所有用户定义的手动 select 组，同时保留 Mac 全局出口和设备 出口候选；
• 在实验性的下游 IPv6 模式中，独立下游 LAN 与局域网 DHCP 接管通过 dnsmasq RA/SLAAC/RDNSS 自动接入，旁路由模式则使用手工 ULA；IPv6 流量不经过 macOS 系统 TUN，而由 BPF packet broker 送入本项目补丁构建的 mihomo gVisor 数据面，覆盖 TCP、 UDP 和以 UDP/443 承载的 QUIC，并保留 MAC 设备身份用于独立策略；
• 在不改变下游设备的前提下，为 Mac 本机经 TUN/显式代理的新连接切换 规则 / 全局 / 直连；默认不修改 macOS 系统代理，也可在 TUN 模式下显式启用 HTTP/HTTPS 系统代理协同，兼容 SafeDNS、DNS Proxy 等 Network Extension 干扰 TUN-only 本机 DNS 的场景；
• DHCP 接管模式为带 MAC 的登记设备生成固定 IPv4 租约；旁路由模式（手工网关） 允许只按主路由侧保持稳定的静态 IPv4 登记设备，MAC 是可选身份信息，两者都可使用 独立出口策略。

可观测性

• 把活跃会话流量归属到 DHCP 设备或同 LAN 的静态登记/当前观察设备，显示每设备 连接数、实时上下行速率、累计字节与占主要流量的 mihomo 出口链；
• 网关运行时或停止时都可集中检测代理节点可达性/延迟，并从最终合成的策略视图切换 Selector；
• 通过 applied mihomo mixed-port 和当前 Mac 本机模式探测固定真实服务目录，展示 三轮中位延迟、命中规则与实际出口链；
• 查看与切换策略组、查看 imported proxy/rule provider 状态、查看当前连接；
• 输出文本/JSON 形式的 status / doctor / logs / snapshot，并收集允许局部失败的 JSON snapshot 供诊断与 UI 使用。

安全与验证

• 配置校验、TUN-only 透明代理、rollback 与明确的恢复契约；
• 在接触普通 LAN 前，先用隔离的虚拟 LAN lab 验证高风险网络行为。

每设备策略

一个 mihomo 进程可以对已登记的 LAN 设备应用独立策略。DHCP 接管模式会为带 MAC 的设备 配置固定 IPv4 租约；旁路由模式只需主路由侧保持稳定的静态 IPv4，MAC 可留空，并可从 当前经过 Mac 的流量与 ARP 邻居观察辅助登记。切换到 DHCP 模式时，GUI 会要求确认当前 可观察到的 MAC；仍无 MAC 的登记会保留，但设备专属策略暂停，补全 MAC 后恢复。当前拓扑中 身份信息充分的设备会生成各自的 mihomo selector group 和 SRC-IP-CIDR 规则。安装版默认 启用每设备策略，Web GUI 始终保留该能力；JSON 策略文件让每台设备要么跟随网关规则，要么在 全局规则之前走设备专属 selector；它也支持 REJECT 这类设备专属动作，以及按 域名/IP/协议/端口/rule-provider 叠加的规则覆盖。dedicated 模式下，本地/私有目标 保持直连。Mac 本机的规则 / 全局 / 直连开关不改变这些下游规则；详见 Mac 本机流量模式。

Web GUI 的规则库把规则集、不带出口的分流模版和每台设备的命中出口分开管理。 其中提供一份可查看的 Claude Code 社区规则示例，但不会默认应用到任何设备；其他策略内容由操作者提供，空 starter 文件也是合法配置。JSON 模型、优先级、CLI 命令和验证边界见 每设备策略覆盖。

Tailscale 出站

Web GUI 的“代理与规则源”页面可以管理一个 OpenSurge 托管的 Tailscale outbound。Auth Key 只写入权限受限的独立文件，配置和 API 响应不会回显； 本地 state-dir 保留节点身份，所以停用后再启用不需创建新设备。“忘记本地 身份”是单独动作，只能在 Tailscale 已停用且网关已停止时执行；它不会从 Tailscale / Headscale 管理后台删除节点。

卡片内的折叠设置会只读检测本机 Tailscale App，把当前 Tailnet 的 MagicDNS 后缀、peer 精确地址、在线状态、已接受的私网路由和可用 Exit Node 显示为待确认建议；不会 自动保存或扩大访问范围。成功发现会保存不含密钥的受限缓存；本机 App 断开后仍可 继续配置，界面会标明信息来源和检测/缓存时间，不把快照描述成实时状态。若本机 Tailscale App 已通过自己的 utun 接管同一条 子网路由，界面会在运行中网关重载前指出具体路由和接口，并要求先关闭 App 的 “接受子网路由”或断开连接；OpenSurge 不会自动修改另一个 App。首次注册仍需要 单独的 Auth Key，界面可直接打开官方 Keys 页面，并提示使用一次性、非 Ephemeral 的 key。本机 App 与 OpenSurge 托管 节点不共享登录身份或 state；检测失败时仍可使用折叠的高级手动配置。

Tailnet 访问和 Exit Node 是两种不同角色：

• Tailnet-only 只在明确的 MagicDNS 后缀、peer IP/CIDR 或已接受的远端子网命中时 选择 Tailscale，目标不可达时不回退 DIRECT；
• 只有配置了明确 Exit Node 才会生成 open-surge/tailscale-exit 独立策略组； 它会成为 Mac 全局出口、每设备 Selector，以及所有用户定义手动 type: select 组的 可选成员，但不会加入自动测速/故障转移/负载均衡组；
• 远端 subnet route 必须逐条确认，与 OpenSurge LAN 重叠时会拒绝保存；
• mihomo 按 outbound 首次请求启动 Tailscale 节点；OpenSurge 会在网关启动、 重载和 mihomo 恢复后主动预热，但第一次业务访问仍可能需要重试。界面仍显示 “按需连接”，且不会用公网 generate_204 误判 Tailnet-only 节点。

当前边界是 outbound-only：OpenSurge 不向 Tailnet 发布本地 LAN，也不用这个节点 提供入站服务。

Web GUI 与菜单栏 App

通过安装包使用 OpenSurge 时，请从 OpenSurge for Mac App 使用指南开始。

本地 Control API、React Web GUI 和以状态展示为主的 SwiftUI 菜单栏 launcher 已进入仓库。开发构建：

make web-install
make control-build
./bin/opensurge-control --config examples/config.example.yaml
make menubar-build

控制服务只监听 127.0.0.1，启动时会输出一次性 Web GUI 链接。菜单栏 App 显示 状态、恢复警报并打开 Web GUI；除独立的临时合盖运行开关外，不提供网关 start/stop 或 策略切换。它区分“只退出菜单栏 App”和“退出 OpenSurge”：后者只在网关数据面已经停止时退出菜单栏 App 与用户级 Control Service；系统 launchd 托管的 root Helper 保持空闲加载，下次打开无需再次授权。 菜单栏还提供独立的“卸载 OpenSurge”入口：只要网关已经停止即可通过 macOS 管理员授权 移除 App、Control Service 与 root Helper，并可选择保留配置数据供以后重新安装或彻底删除。 架构、安全边界与构建说明见 Web GUI 与菜单栏 App。 Web GUI 内置 applied 配置 + 当前 Mac 本机模式的连通性页面，并提供 Net.Coffee 的 独立浏览器本机检测入口；两者都不会被描述成下游设备网关规则或 DHCP/DNS/TUN 路径 已经验收。

make gui-installer 会在取得真实 mihomo、dnsmasq 二进制后构建 macOS 安装包。 Developer ID 签名和 notarization 必须显式提供发布凭据。

readme truncated — read the full docs on github