vpn-proxy/docs/superpowers/plans/2026-05-19-macos-client.md

macOS Docker Client Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a macOS Docker client mode that exposes a local HTTP/SOCKS proxy on 127.0.0.1:8080 with a friendlier UI and a curl installer.

Architecture: Reuse the current Node API, React UI, subscription parser, sing-box process manager, and routing rule generator. Add APP_MODE=client so the same backend emits a proxy-only sing-box config without TProxy, and use a dedicated Dockerfile/compose path for Mac installation.

Tech Stack: Node.js ESM, React/Vite, sing-box, Docker Compose, POSIX shell, node:test.

---

Task 1: Client Mode Config Contract

Files:

• Create: test/server/singbox-client-mode.test.js

• Modify: package.json

• Modify: src/server/config.js

• Modify: src/server/singbox.js

• Modify: src/server/index.js

• Add node:test coverage that proves APP_MODE=client config has mixed-in, no tproxy-in, no transparent fallback, and a VPN proxy fallback.

• Add npm test script.

• Add settings.appMode.

• Make buildGatewayConfig() conditionally emit client-only inbounds and route rules.

• Expose mode and hide irrelevant tproxy fields in public state.

Task 2: macOS Client Docker Runtime

Files:

• Create: entrypoint.client.sh

• Create: Dockerfile.client

• Create: docker-compose.client.yml

• Add an entrypoint that starts only the Node control server.

• Add a Dockerfile that builds the Vite frontend inside Docker and installs only client runtime dependencies plus sing-box.

• Add compose with loopback-only port publishing for UI and proxy.

Task 3: User-Friendly Client UI

Files:

• Create: src/web/components/ClientOverviewPage.jsx

• Modify: src/web/App.jsx

• Modify: src/web/components/Sidebar.jsx

• Modify: src/web/components/Topbar.jsx

• Modify: src/web/components/StatusPane.jsx

• Modify: src/web/components/RouteChecker.jsx

• Modify: src/web/styles.css

• Add a client overview with status, active server, copyable proxy URLs, and macOS setup commands.

• Hide gateway-only navigation and side status pane in client mode.

• Rename topbar brand to match current mode.

• Keep servers, logs, and settings reachable in client mode.

Task 4: curl Installer and Docs

Files:

• Create: scripts/install-macos-client.sh

• Modify: README.md

• Modify: .env.example

• Add curl-friendly installer with Docker/Git checks and update-or-clone behavior.

• Document one-line install command and manual compose command.

• Add client mode environment examples.

Task 5: Verification

Commands:

• npm test

• npm run build

• docker compose -f docker-compose.client.yml config

• Run all commands and fix any failures.

• Inspect the diff to confirm existing CI/runtime-base edits remain untouched.