A private, read-only map of listening ports on macOS. SocketSage tells you what is listening, whether it is local-only, which process and project own it, and what it is likely for. Facts and inferences are deliberately separate.
lsof can answer almost anything about sockets, but a one-off question such as “what is using this local port?” should not require decoding a raw process dump. SocketSage is the small, local-first middle ground:
- Lists TCP listeners and bound UDP sockets with their address scope.
- Groups endpoints that plausibly belong to the same app or project, while retaining each endpoint’s facts.
- Explains likely purpose, category and confidence with the rule evidence that supports them.
- Scores current CPU/RSS pressure against a category-specific reference range; it is not a health, security or quality verdict.
- Runs at
127.0.0.1, has GET-only APIs, no account, no telemetry, no cloud model and no process-control actions.
The interface is available in English, Simplified Chinese and French. The language preference is explicit choice, saved choice, browser language, then English fallback.
Requirements: macOS and Node.js 22 or newer.
git clone https://github.com/bopensourcez/socket-sage.git
cd socket-sage
npm ci
npm startOpen http://127.0.0.1:4188. Once loaded, the service table shows each listener’s protocol, address scope, port, owning process or project, and current CPU/RSS. Purpose, grouping and confidence are rule-based explanations; low confidence means the evidence is insufficient, not that startup failed.
Use Control-C to stop it. To choose a different port for SocketSage itself:
FLYENV_MONITOR_PORT=4190 npm startNo administrator permission, account or external service is required.
SocketSage is not a security scanner or historical monitor, and it never closes processes.
| Shown as | What it means |
|---|---|
| Protocol, address, port, PID, process, CPU and RSS | A current system observation from lsof or ps. |
| Purpose, category, risk wording and grouping | A local rule-based inference. The UI shows its evidence and confidence. |
| Low confidence or unclassified | Evidence is insufficient. Treat that as a useful answer, not a hidden failure. |
| Load score | A one-snapshot comparison with the reference range for the service category. It is not historical monitoring or an alarm. |
For an AI-made project, use the explicit local classification map. SocketSage never infers that a project was made with AI merely because its path, parent process or runtime mentions an AI tool. See the classification guide.
FlyEnv is optional. If its process, executable or working-directory evidence is present, SocketSage marks an endpoint as FlyEnv-managed; it does not read or modify FlyEnv’s private data.
- Architecture: a small Node HTTP server, native macOS commands and browser-native UI.
- Privacy and security boundary: exactly what is read, exposed and intentionally not done.
- Classification and load scoring: rules, confidence and local overrides.
- Internationalization: English canonical source, exact key parity and documentation policy.
- Competitive landscape and product positioning: where adjacent tools are stronger and why this narrower tool remains useful.
Each user guide has matching 中文 and français versions; links to the equivalent documents are at the top of each guide.
npm test
npm run buildFor the complete source-release verification sequence, including runtime, benchmark, audit and packaging checks, see CONTRIBUTING.md.
Please read CONTRIBUTING.md before proposing a change. The project is deliberately narrow: no remote host monitoring, packet capture, cloud AI, telemetry, database, Electron, Docker or process-kill controls.
For a security issue, use the private reporting path in SECURITY.md, not a public issue.
The code is MIT licensed. private: true intentionally prevents accidental npm publication; this repository is prepared for source release, not an npm package release.