qlinter
Menu
singbox-proxymanager-forclaude crates.io

singbox-watch

Download page Source on GitHub

singbox-watch is a Windows tray controller, watchdog and fail-safe toolkit for a sing-box tunnel with a static exit IP. If your computer routes all traffic through a SOCKS5 or TUN tunnel and you need to be sure it never silently falls back to the raw connection, this is that toolkit. Every feature answers a failure that actually happened.

It is two small Rust binaries using only the Windows API, plus an Android app that watches the phone's own tunnel.

Binary What it does
proxy-tray.exe Tray on/off switch, auto-enable guard, sub-second app kill-switch, health check (--doctor), keep-alive trigger, defaults enforcement
singbox-watch.exe Always-on-top warning banner when the exit IP stops matching the pinned IP

Install

  • Windows installer from qlinter.org (singbox-watch-setup-1.1.0.exe). This is the project's own one-file installer and needs no admin rights. It installs to your existing install's folder, or next to a running sing-box.exe, or %USERPROFILE%\singbox-watch (or a folder you pick). It turns on login autostart for both apps, adds the per-minute keep-alive task, offers to pin your current public IP, adds an Apps & Features entry and starts both apps. Re-run it to upgrade. Options: --silent [--dir <path>], --uninstall [--silent], --extract <dir>.
  • Android app from qlinter.org (singbox-watch-android-1.0.0.apk).
  • macOS build from qlinter.org (singbox-watch-mac-1.0.0.tar.gz), built from the repo's mac branch. It hasn't been tested much.
  • From source: build-installer.cmd builds both apps and target\release\singbox-watch-setup.exe.

Requirements: Windows 10 or 11 x64, and sing-box installed and runnable through a scheduled task (default name sing-box-tun), for example:

schtasks /Create /TN sing-box-tun /TR "wscript.exe C:\path\to\run-hidden.vbs" /SC ONLOGON /RL HIGHEST /F

Quick start

  1. Run the installer and let it pin your current public IP. That writes expected-exit-ip.txt, the ground truth every check compares against.
  2. Find the tray icon (under Show hidden icons on the taskbar) and pin it to the taskbar so it's always visible.
  3. Left-click the icon to turn the tunnel on or off. Right-click it for Settings and the other menu items.
  4. Check everything at once:
proxy-tray.exe --doctor

Features

  • Tray switch. Green when the exit IP matches the pinned IP, red when it doesn't. Left-click toggles the tunnel by starting or stopping the scheduled task; a UAC prompt appears when elevation is needed. The icon changes at once: red for off, amber while switching on, then green as soon as the exit IP verifies. The tooltip shows the live exit IP and an optional renewal countdown. The icon turns red the instant sing-box.exe exits.
  • Fail-closed kill-switch. Turning the proxy off first kills every matched app process natively, in under 100 ms.
  • Warning banner. A red "TUNNEL BYPASSED" banner when the exit IP changes unexpectedly; amber for an intentional off or no connectivity. Left-click snoozes it, right-click quits it.
  • Keep-closed policy. While the proxy is off, matched apps are closed within a tenth of a second of appearing, and a dialog asks once whether to keep them closed. No answer keeps them closed. No switches to auto-enable.
  • Auto-enable guard. If a matched app starts, or a fresh DNS lookup for a watched domain happens, while the tunnel is down, the app is suspended, the tunnel is started, and the app resumes only after the exit IP is verified. If the tunnel can't come up, the app stays suspended.
  • Keep-alive. A hidden scheduled task runs every minute and restarts the tray app, the banner and the tunnel itself (only when the proxy is meant to be on). A crashed tunnel heals in under a minute.
  • Doctor. proxy-tray.exe --doctor prints a full health report: exit IP against the pinned IP, processes, the keep-alive task, autostart entries, TCP congestion control, each browser's WebRTC leak policy and the renewal countdown.
  • Defaults enforcement and tuning. Every enable checks BBR2 congestion control and the WebRTC leak policy, and runs the tuning script if they've drifted (UAC, at most once every 30 minutes). apply-tuning.cmd switches Windows to BBR2, applies the machine-wide WebRTC disable_non_proxied_udp policy for Chrome, Edge and Brave, and restarts the tunnel.

Android app

The Android app works alongside the sing-box app (SFA) and checks that the phone's own traffic goes through the tunnel. It doesn't control the PC.

  • An instant alert when Android reports the VPN gone.
  • An exit-IP check against your pinned IP: a wrong IP is a red alert, no answer is amber.
  • An always-visible status notification and a renewal countdown.
  • Settings for watching, each kind of alert, vibration, quick re-checks, start after reboot and the check interval.
  • An Open sing-box button and a shortcut to Android's VPN settings, where Always-on VPN plus Block connections without VPN is Android's own kill switch.

Turn sing-box on, open the app and tap Pin current IP.

Commands

proxy-tray.exe                run (tray icon)
proxy-tray.exe --doctor       full health report, exit 0 = all good
proxy-tray.exe --state-once   print tunnel state and exit
proxy-tray.exe --kill-list    dry run: list everything the kill-switch would target
proxy-tray.exe --kill-now     kill matched processes immediately
proxy-tray.exe --install      turn on login autostart (--uninstall turns it off)
singbox-watch.exe             run (banner watcher)
singbox-watch.exe --check-once | --test-banner | --ip <addr> | --install | --uninstall

How it works

Both binaries are plain Win32 programs with no GUI framework, built as GUI-subsystem apps so there's no console window that could be closed by accident. The tunnel itself is sing-box, started and stopped through a scheduled task.

The tray waits on the sing-box.exe process handle, so it knows the instant the tunnel exits, and checks the exit IP at most every 35 seconds otherwise. The tray and the banner share one result in exit-ip-cache.txt (25 s) instead of each probing, because extra probes only deepen a saturated proxy. Probes fall back across ip-api.com, ifconfig.me and checkip.amazonaws.com.

The kill-switch takes a process snapshot, reads each process's command line straight from its memory, and calls TerminateProcess, with no PowerShell in the hot path. By design it targets claude.exe and any node.exe whose command line contains claude-code, minus exclusions. To guard other apps, change list_claude_targets() and kill_claude_blocking() in src/bin/proxy-tray.rs.

"No connectivity" is not "proxy off". Proxy providers often cap concurrent connections, and once the cap is hit every health check fails while the tunnel is still up. So the kill-switch acts only on positive evidence: a deliberate toggle-off, or a wrong exit IP that is re-verified live.

Configuration

Feature switches live in settings.txt, one key=on|off per line; edit it from the tray's Settings menu. A missing key keeps its default.

Key Default Switches
kill_on_off on Close matched apps when the proxy is turned off
close_while_off on Keep closing matched apps while the proxy is off
ask_keep_closed on The "keep them closed?" dialog (off keeps them closed silently)
auto_enable on Turn the proxy on when a matched app starts
dns_watch on Turn it on after claude.ai or anthropic.com DNS lookups
enforce_defaults on The BBR2 and WebRTC check on every enable
banner on The always-on-top warning banner
renew_countdown on The renewal countdown in the tooltip
Environment variable Default Meaning
SINGBOX_WATCH_TASK sing-box-tun Scheduled task used to start and stop the tunnel
SINGBOX_WATCH_KILL_EXCLUDE empty Comma-separated substrings; node.exe command lines containing any of them are never killed
File Meaning
expected-exit-ip.txt Your tunnel's public IPv4, exactly
renew-deadline.txt YYYY-MM-DD proxy expiry: a tooltip countdown that becomes a "RENEW NOW" nag in the last 5 days
proxy-state.txt, exit-ip-cache.txt, settings.txt State
proxy-tray.log Log, next to the exe

State files are looked for next to the exe first, then in %USERPROFILE%\.singbox-watch\.

Limits and troubleshooting

  • Windows only by design. The Mac build comes from a separate branch and is barely tested.
  • It assumes a single static exit IP.
  • Stopping a task that runs at highest integrity from a standard context needs a UAC prompt.
  • Don't launch the apps from an editor or agent shell: they share that shell's job object and die with it. Use the autostart entries or explorer.exe <path>.
  • The DNS watcher is best-effort. Browsers with secure DNS (DoH) bypass the system resolver.
  • After a UAC secure-desktop switch, Windows can keep a dead tray icon. The app deletes and re-adds it, retrying every 5 seconds.

Worked examples

First setup on a new PC. Install sing-box with a scheduled task named sing-box-tun, connect it, then run the singbox-watch installer and let it pin your current IP. The tray icon should turn green. Run proxy-tray.exe --doctor to confirm.

See what the kill-switch would close. proxy-tray.exe --kill-list lists every matched process without touching anything.

Protect your own tools from the kill-switch. Set SINGBOX_WATCH_KILL_EXCLUDE=my-editor,my-agent; node.exe command lines containing either are never killed.

Get reminded before the proxy expires. Put 2026-12-31 in renew-deadline.txt. The tooltip counts down and nags "RENEW NOW" in the last 5 days.

Test the banner. singbox-watch.exe --test-banner shows it without a real failure.

Watch the phone too. Install the Android app, turn sing-box on, open the app and tap Pin current IP. In Android's VPN settings, turn on Always-on VPN and Block connections without VPN for sing-box.

Edge cases

  • The proxy is up but saturated: providers often cap concurrent connections, so every check fails while the tunnel still works. That shows amber, not red, and the kill-switch doesn't fire.
  • sing-box crashes: the icon turns red at once, and the keep-alive task restarts it within a minute if the proxy is meant to be on.
  • A matched app starts while the tunnel is down: it's suspended until the exit IP verifies; if the tunnel can't come up, it stays suspended.
  • The exit IP changes: the red banner appears after a live re-check.
  • UAC prompts: starting or stopping a task that runs at highest integrity needs one.
  • Browsers with secure DNS: they bypass the system resolver, so the DNS watcher can't see their lookups.
  • Launched from an editor terminal: the apps die when that terminal closes. Use autostart or explorer.exe <path>.

FAQ

Does it replace sing-box? No, it watches and controls a sing-box tunnel you already run.

Which apps does the kill-switch close? claude.exe and node.exe processes running Claude Code. Change the matching in src/bin/proxy-tray.rs for other apps.

Can I turn features off? Yes, from Settings in the tray menu.

Does it need admin rights? The installer doesn't. Stopping a highest-integrity task does, through UAC.

What does amber mean? An intentional off, or no connectivity without proof the tunnel is down.

Does uninstalling delete my settings? No, it keeps your config, state and logs.

Does the Android app control the PC? No, it only watches the phone's own tunnel.

Version and source

This page describes singbox-watch 1.1.0 for Windows, and 1.0.0 for Android and macOS.

singbox-watch 是 Windows 上的系統匣控制器、監看程式和防護工具組，用於具有固定出口 IP 的 sing-box 通道。如果你的電腦把所有流量都經由 SOCKS5 或 TUN 通道送出，而你需要確定它絕不會悄悄退回原始連線，這就是你要的工具組。每個功能都對應一次真實發生過的故障。

它由兩個只用 Windows API 的小型 Rust 執行檔組成，另外還有一個監看手機自己通道的 Android App。

執行檔 作用
proxy-tray.exe 系統匣開關、自動啟用防護、不到一秒的 App 斷線開關、健康檢查（--doctor）、保活觸發、預設值強制
singbox-watch.exe 出口 IP 與釘選 IP 不符時，顯示永遠置頂的警告橫幅

安裝

  • Windows 安裝程式，來自 qlinter.org（singbox-watch-setup-1.1.0.exe）。這是專案自己的單一檔案安裝程式，不需要系統管理員權限。它會安裝到你現有安裝的資料夾，或執行中的 sing-box.exe 旁邊，或 %USERPROFILE%\singbox-watch（或你選的資料夾）。它會為兩個 App 開啟登入時自動啟動、加入每分鐘的保活工作、提議釘選你目前的公開 IP、加入「應用程式與功能」項目，並啟動兩個 App。重新執行即可升級。選項：--silent [--dir <path>]、--uninstall [--silent]、--extract <dir>。
  • Android App，來自 qlinter.org（singbox-watch-android-1.0.0.apk）。
  • macOS 版，來自 qlinter.org（singbox-watch-mac-1.0.0.tar.gz），由 repo 的 mac 分支建置。測試不多。
  • 從原始碼： build-installer.cmd 會建置兩個 App 和 target\release\singbox-watch-setup.exe。

需求：Windows 10 或 11 x64，以及已安裝、可透過工作排程器工作（預設名稱 sing-box-tun）執行的 sing-box，例如：

schtasks /Create /TN sing-box-tun /TR "wscript.exe C:\path\to\run-hidden.vbs" /SC ONLOGON /RL HIGHEST /F

快速開始

  1. 執行安裝程式，讓它釘選你目前的公開 IP。這會寫入 expected-exit-ip.txt，也就是每項檢查比對的基準。
  2. 找到系統匣圖示（在工作列的 顯示隱藏的圖示 底下），把它釘選到工作列，讓它一直看得到。
  3. 左鍵點圖示可開關通道。右鍵點它可打開 Settings 和其他選單項目。
  4. 一次檢查所有東西：
proxy-tray.exe --doctor

功能

  • 系統匣開關。 出口 IP 與釘選 IP 相符時為綠色，不符時為紅色。左鍵點擊會啟動或停止工作排程器工作來開關通道；需要提升權限時會出現 UAC 提示。圖示會立刻改變：關閉為紅色、開啟中為琥珀色，出口 IP 一確認就變綠色。工具提示會顯示即時出口 IP 和可選的續約倒數。sing-box.exe 一結束，圖示就立刻變紅。
  • 失效即關閉的斷線開關。 關閉代理時，會先以原生方式在 100 毫秒內砍掉所有符合條件的 App 程序。
  • 警告橫幅。 出口 IP 意外改變時顯示紅色的「TUNNEL BYPASSED」橫幅；刻意關閉或沒有連線時為琥珀色。左鍵點擊暫停提醒，右鍵點擊結束。
  • 保持關閉原則。 代理關閉時，符合條件的 App 一出現就在十分之一秒內被關閉，並跳出對話框詢問一次是否保持關閉。不回答就保持關閉。選 No 會改用自動啟用。
  • 自動啟用防護。 通道關閉時，如果有符合條件的 App 啟動，或出現對監看網域的新 DNS 查詢，該 App 會被暫停、通道會被啟動，等出口 IP 確認後才恢復 App。如果通道起不來，App 就一直保持暫停。
  • 保活。 一個隱藏的工作排程器工作每分鐘執行一次，重新啟動系統匣 App、橫幅和通道本身（只在代理應該開著時）。當掉的通道在一分鐘內自動恢復。
  • 健康檢查。 proxy-tray.exe --doctor 會印出完整的健康報告：出口 IP 與釘選 IP 的比對、程序、保活工作、自動啟動項目、TCP 壅塞控制、各瀏覽器的 WebRTC 外洩政策，以及續約倒數。
  • 預設值強制與調校。 每次啟用都會檢查 BBR2 壅塞控制和 WebRTC 外洩政策，偏離時執行調校指令稿（UAC，最多每 30 分鐘一次）。apply-tuning.cmd 會把 Windows 切換到 BBR2，為 Chrome、Edge 和 Brave 套用全機的 WebRTC disable_non_proxied_udp 政策，並重新啟動通道。

Android App

Android App 搭配 sing-box App（SFA）使用，確認手機自己的流量經由通道送出。它不會控制電腦。

  • Android 回報 VPN 中斷時立即提醒。
  • 比對出口 IP 與你釘選的 IP：IP 錯誤是紅色警示，沒有回應則是琥珀色。
  • 常駐的狀態通知和續約倒數。
  • 可設定監看、各類警示、震動、快速重新檢查、開機後啟動和檢查間隔。
  • Open sing-box 按鈕，以及前往 Android VPN 設定的捷徑；在那裡為 sing-box 開啟 永久連線 VPN 加上 封鎖未使用 VPN 的連線，就是 Android 自己的斷線開關。

打開 sing-box，開啟 App，點 Pin current IP。

指令

proxy-tray.exe                run (tray icon)
proxy-tray.exe --doctor       full health report, exit 0 = all good
proxy-tray.exe --state-once   print tunnel state and exit
proxy-tray.exe --kill-list    dry run: list everything the kill-switch would target
proxy-tray.exe --kill-now     kill matched processes immediately
proxy-tray.exe --install      turn on login autostart (--uninstall turns it off)
singbox-watch.exe             run (banner watcher)
singbox-watch.exe --check-once | --test-banner | --ip <addr> | --install | --uninstall

運作原理

兩個執行檔都是不用 GUI 框架的純 Win32 程式，並以 GUI 子系統建置，所以沒有可能被誤關的主控台視窗。通道本身是 sing-box，透過工作排程器工作啟動和停止。

系統匣會等待 sing-box.exe 的程序 handle，所以通道一結束就知道；其他時候最多每 35 秒檢查一次出口 IP。系統匣和橫幅共用 exit-ip-cache.txt 中的同一個結果（25 秒），而不是各自檢測，因為多餘的檢測只會讓已飽和的代理更塞。檢測會依序退回 ip-api.com、ifconfig.me 和 checkip.amazonaws.com。

斷線開關會取得程序快照，直接從每個程序的記憶體讀取命令列，再呼叫 TerminateProcess，關鍵路徑中不用 PowerShell。依設計，它鎖定 claude.exe，以及命令列含有 claude-code 的 node.exe（排除項目除外）。要保護其他 App，請修改 src/bin/proxy-tray.rs 中的 list_claude_targets() 和 kill_claude_blocking()。

「沒有連線」不等於「代理關閉」。代理供應商常會限制同時連線數，一旦達到上限，即使通道還在，所有健康檢查都會失敗。所以斷線開關只依據明確的證據行動：刻意關閉，或經即時重新確認的錯誤出口 IP。

設定

功能開關放在 settings.txt，每行一個 key=on|off；可從系統匣的 Settings 選單編輯。缺少的鍵維持預設值。

鍵 預設值 控制
kill_on_off on 關閉代理時關掉符合條件的 App
close_while_off on 代理關閉期間持續關掉符合條件的 App
ask_keep_closed on 「保持關閉嗎？」對話框（off 則直接保持關閉）
auto_enable on 符合條件的 App 啟動時開啟代理
dns_watch on 偵測到 claude.ai 或 anthropic.com 的 DNS 查詢時開啟代理
enforce_defaults on 每次啟用時檢查 BBR2 和 WebRTC
banner on 永遠置頂的警告橫幅
renew_countdown on 工具提示中的續約倒數
環境變數 預設值 意思
SINGBOX_WATCH_TASK sing-box-tun 用來啟動和停止通道的工作排程器工作
SINGBOX_WATCH_KILL_EXCLUDE 空 以逗號分隔的子字串；命令列含有其中任一個的 node.exe 永遠不會被砍掉
檔案 意思
expected-exit-ip.txt 你的通道的公開 IPv4，必須完全正確
renew-deadline.txt YYYY-MM-DD 代理到期日：工具提示倒數，最後 5 天變成「RENEW NOW」提醒
proxy-state.txt、exit-ip-cache.txt、settings.txt 狀態
proxy-tray.log log，與 exe 放在一起

狀態檔會先在 exe 旁邊尋找，再到 %USERPROFILE%\.singbox-watch\。

限制與疑難排解

  • 依設計僅限 Windows。Mac 版來自另一個分支，幾乎沒有測試。
  • 它假設只有一個固定的出口 IP。
  • 從一般權限停止以最高權限執行的工作，需要 UAC 提示。
  • 不要從編輯器或 agent 的 shell 啟動這些 App：它們會共用那個 shell 的 job object，並跟著一起結束。請用自動啟動項目或 explorer.exe <path>。
  • DNS 監看是盡力而為。使用安全 DNS（DoH）的瀏覽器會繞過系統解析器。
  • 經過 UAC 安全桌面切換後，Windows 可能留下失效的系統匣圖示。App 會刪除再重新加入，每 5 秒重試一次。

實例

在新電腦上初次設定。 安裝 sing-box 並建立名為 sing-box-tun 的工作排程器工作，連線後執行 singbox-watch 安裝程式，讓它釘選你目前的 IP。系統匣圖示應該會變綠。執行 proxy-tray.exe --doctor 確認。

看看斷線開關會關掉什麼。 proxy-tray.exe --kill-list 會列出所有符合條件的程序，但不動任何東西。

讓你自己的工具免於斷線開關。 設定 SINGBOX_WATCH_KILL_EXCLUDE=my-editor,my-agent；命令列含有其中任一個的 node.exe 永遠不會被砍掉。

在代理到期前收到提醒。 在 renew-deadline.txt 中寫入 2026-12-31。工具提示會倒數，最後 5 天提醒「RENEW NOW」。

測試橫幅。 singbox-watch.exe --test-banner 會在沒有真正故障時顯示橫幅。

也監看手機。 安裝 Android App，打開 sing-box，開啟 App 並點 Pin current IP。在 Android 的 VPN 設定中，為 sing-box 開啟 永久連線 VPN 和 封鎖未使用 VPN 的連線。

特殊情況

  • 代理還在但已飽和： 供應商常會限制同時連線數，所以即使通道仍可用，所有檢查都會失敗。這時顯示琥珀色而不是紅色，斷線開關也不會觸發。
  • sing-box 當掉： 圖示立刻變紅；如果代理應該開著，保活工作會在一分鐘內重新啟動它。
  • 通道關閉時有符合條件的 App 啟動： 它會被暫停，直到出口 IP 確認為止；如果通道起不來，就一直保持暫停。
  • 出口 IP 改變： 經過即時重新檢查後，紅色橫幅出現。
  • UAC 提示： 啟動或停止以最高權限執行的工作時需要。
  • 使用安全 DNS 的瀏覽器： 它們會繞過系統解析器，所以 DNS 監看看不到它們的查詢。
  • 從編輯器終端機啟動： 那個終端機關閉時，App 也會結束。請用自動啟動或 explorer.exe <path>。

常見問題

它會取代 sing-box 嗎？ 不會，它監看並控制你已經在執行的 sing-box 通道。

斷線開關會關掉哪些 App？ claude.exe 和執行 Claude Code 的 node.exe 程序。其他 App 請修改 src/bin/proxy-tray.rs 中的比對邏輯。

能關掉某些功能嗎？ 可以，從系統匣選單的 Settings。

需要系統管理員權限嗎？ 安裝程式不需要。停止以最高權限執行的工作需要，會透過 UAC。

琥珀色代表什麼？ 刻意關閉，或沒有連線但沒有證據顯示通道已中斷。

解除安裝會刪除我的設定嗎？ 不會，它會保留你的設定、狀態和 log。

Android App 會控制電腦嗎？ 不會，它只監看手機自己的通道。

版本與原始碼

本頁說明 Windows 版 singbox-watch 1.1.0，以及 Android 與 macOS 版 1.0.0。