SagerNet / SagerNet/sing-box

[FEAT] Add native support for Windows Service Control Handler

Open
#4,221 0 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
38.2k
Forks
4.6k
Avg merge
19d 15h
Merged PRs (30d)
1

Description

I am a heavy user of sing-box on Windows. Currently, to run sing-box as a background service, users have to rely on third-party wrappers like NSSM or WinSW. It would be a significant improvement if sing-box could support the native Windows Service Control Handler.

Why this is needed
  1. Reduce External Dependencies: Currently, setting up sing-box as a service requires installing additional tools (like NSSM), which adds complexity and potential maintenance overhead for users.
  2. Standardization: Native support would allow users to manage sing-box directly using standard Windows commands (e.g., sc start, sc stop) or the Services GUI (services.msc) without the need for an intermediary wrapper.
  3. Better Reliability: Native integration ensures that the service lifecycle (start, pause, stop, and status reporting) is handled cleanly by the OS, leading to better stability.
Proposed Implementation

I understand that sing-box is designed to be cross-platform. Perhaps this could be implemented optionally or via a build tag for Windows, so that the core codebase remains clean and lightweight for other platforms.

Environment

OS: Windows 11
sing-box version: 1.14.0-alpha.31

Additional Context

Many users in the community currently use sc create or third-party wrappers, but they often encounter "service did not respond" errors because sing-box does not implement the ServiceMain and Handler callbacks required by the Windows SCM (Service Control Manager).

Thank you for your hard work on this incredible project! I look forward to hearing your thoughts on whether this fits into the future roadmap.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Begin by mapping the cross-platform startup path and the proposed Windows-only build boundary. The issue identifies the Windows SCM ServiceMain and Handler callbacks as the integration points; confirm how they should support start, pause, stop, and status reporting. Done means sing-box can be managed through sc commands or services.msc without NSSM or WinSW.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.