setup-sing-box

name	setup-sing-box
description	Install and configure a sing-box proxy client on macOS — one client that speaks BOTH Hysteria2 and Shadowsocks and switches between them. Installs binary via Homebrew, deploys a merged config, adds shortcut commands (sbstart, sbstop, sblog, sbstatus, sbrestart, sbedit, sbnode, sbon, sboff), and OPTIONALLY sets up a launchd auto-start service (asks the user first). Use this skill when the user mentions sing-box, singbox, a unified proxy client, switching between hysteria2 and shadowsocks, or wants one client for multiple protocols on a new Mac.
allowed-tools	["Bash","Read","Write","Edit","AskUserQuestion"]

Setup sing-box Client

Install and configure a sing-box client on macOS. One local proxy port fronts both a Hysteria2 and a Shadowsocks outbound — switch with sbnode, or let auto pick the fastest. Optionally runs as a launchd background service. Edit one JSON, run one command.

It coexists with setup-hysteria2: sing-box defaults to port 1082, hysteria2 uses 1080/1081, so both can run at once. (sing-box already includes a Hysteria2 outbound, so most people run either sing-box or the standalone hysteria2 client — not both.)

File layout

~/.config/sing-box/
  config.json                        ← edit this (chmod 600, contains your auth)
  aliases.sh                         ← shell shortcuts
  sing-box.log / sing-box.err.log    ← runtime logs
~/Library/LaunchAgents/
  com.sing-box.client.plist          ← runs `sing-box run -c config.json`
                                       (ONLY in service mode — omitted in manual mode)

3–4 files (the plist exists only when you choose the launchd service), no wrappers, no env injection.

Quick setup

Step 1 — ask the user how it should run. Before running the script, use AskUserQuestion to let the user choose the startup mode:

• Auto-start service (launchd) — starts automatically on login and is kept alive if it crashes. Best for a daily-driver machine. → pass --service
• Manual only — no launchd; the user starts/stops it themselves with sbstart / sbstop. Best for a shared/temporary machine or when the user wants full control. → pass --no-service

Recommend Auto-start service as the default.

Step 2 — run the script with the chosen flag:

bash ${CLAUDE_SKILL_DIR}/scripts/setup-sing-box.sh --service      # or --no-service

If run non-interactively (e.g. orchestrated by setup-macos), the flag can be omitted and it defaults to --service.

The script:

• Installs sing-box via Homebrew
• Deploys config.json template (preserves existing — never overwrites real secrets)
• Deploys aliases.sh
• Generates the launchd plist only in --service mode (in --no-service mode it removes any pre-existing plist)
• Adds source aliases.sh to ~/.zshrc.local

After setup — fill in 3 fields

sbedit           # opens config.json in $EDITOR, runs `sing-box check`, auto-restarts on save

Replace these placeholders (Hy2 and SS may point at different hosts — edit each server if so):

"server": "SERVER_HOST"        // both the hy2 and ss outbound
"password": "HY2_AUTH_TOKEN"   // in the hysteria2 outbound
"password": "SS_PASSWORD"      // in the shadowsocks outbound

Then:

source ~/.zshrc
sbstart          # start (validates config first)
sbstatus         # verify — shows current outbound + listening port
sbon             # set http/https/all_proxy → 127.0.0.1:1082 in this shell

Shortcut commands

Service control

These auto-detect the mode: with a plist they drive launchd; without one they start/stop the process directly.

Command	Action
sbstart	Start (runs sing-box check first; launchd service or background process)
sbstop	Stop (unload service if present, then kill the process)
sbrestart	Restart (launchctl kickstart -k, or stop+start in manual mode)
sbstatus	PID + mode + current outbound + listening port
sblog	Tail stdout + stderr (Ctrl+C to exit)
sblogs	Last 50 lines of logs
sbedit	Edit config.json + validate + auto-restart
sbhelp	Full command reference

Outbound switching

Command	Action
sbnode	Print the current default outbound
sbnode ss / sbnode hy2 / sbnode auto	Switch default outbound + restart (auto = url-test fastest)

Proxy control (current shell only)

sb-prefixed so they don't clash with setup-hysteria2's proxyon/proxyoff.

Command	Action
sbon	Set http_proxy / https_proxy / all_proxy → sing-box mixed port
sboff	Unset proxy env vars
sbproxystatus	Show current proxy state
sbip	Compare direct vs. proxy egress IP (labels current outbound)
sbspeed	Test proxy download speed

Combo

Command	Action
gosb	sbstart + sbon + sbip
stopsb	sbstop + sboff

Default port

Mixed (SOCKS5 + HTTP on one port): 127.0.0.1:1082. To change, edit listen_port in config.json AND SB_MIXED_PORT in aliases.sh.

Security

• config.json is chmod 600 — only your user can read it
• The setup script never overwrites an existing config.json (keeps your secrets safe across re-runs)
• aliases.sh and the plist ARE overwritten on re-run — they're managed code, not user data
• sbstart / sbedit run sing-box check before (re)starting, so a bad edit never silently breaks the service
• The launchd service (when used) runs as your user, not root
• The Hysteria2 outbound uses tls.insecure: true to match a self-signed server (as deployed by setup-hysteria2 --server). sing-box has no SHA256 cert-pinning option, so pinning is not enforced client-side — the QUIC password still authenticates the server.

Related

• setup-hysteria2 — standalone Hysteria2 client, and the server side (--server) that this client's hy2 outbound connects to
• setup-shadowsocks — the Shadowsocks server (--server) that this client's ss outbound connects to