Sing Box User Guide

Read in order: configuration format · add a profile · start and verify · groups · update and stop · troubleshoot.

Prepare the client and a compatible configuration

Choose an official graphical app from the download page: SFW for Windows, SFL for Linux, SFA for Android, SFM standalone for macOS, or sing-box MT from the iOS store. Ordinary sing-box archives contain the command-line core. Installing the app does not provide a proxy service or nodes.

A profile needs a complete sing-box JSON configuration compatible with the installed core. A remote profile downloads it from a URL; a local profile stores configuration content locally. Clash YAML, a node list and a single share link are different formats. Ask the provider for compatible sing-box output before importing; conversion still requires checking DNS, routing and version compatibility.

Add a remote or local profile

Open the profile list and add a profile. For a remote source, set a recognizable name, choose Remote, and enter the complete configuration URL. Apply authentication and update settings only as required by the provider. Save it, then check that the profile appears in the list. A download error belongs to this stage, before connection troubleshooting.

For local JSON, use the app’s local profile editor or supported import function to save the full configuration. Menu names and file-import controls differ across clients; the steps describe field meanings rather than identical button positions. Do not paste a software download page into the profile URL field.

Select, start, and verify access

Select the saved profile, start the service, and accept the required platform VPN or system permission prompt. Running time and traffic counters indicate service state; they do not establish that the chosen node, DNS and routing work. Test the intended website or app and use connection records or logs to check the expected outbound.

Select nodes only when the configuration defines groups

Selector and URLTest group outbounds provide the corresponding group controls. Selector is for manual selection; URLTest follows the configured test behavior. A configuration with a single outbound can have no group list. Mode selection depends on the configuration using at least two clash_mode values, so every profile need not have a Rule/Global switch.

Update profiles, upgrade the app, and stop

Refreshing a remote profile fetches its URL again; local content does not update with a remote source. Keep a recoverable copy before editing or upgrading, because a refresh can replace your edits. App upgrades and profile refreshes are separate tasks; check version changes and config compatibility before upgrading.

Use the service stop control when finished and verify that the required direct access has returned. Closing a desktop window can leave the app in the tray. Platform details: Android, iOS, macOS, and the Windows illustrated guide (Chinese).

Troubleshoot by the stage that failed

Download/import failed: check the URL, expiry, authentication and returned format. Saved but cannot start: use the first relevant startup error to check fields, core version, referenced files and permissions. Running but no access: check the selected profile and outbound, then DNS, routing and other VPN conflicts. Change one condition and retest.

The FAQ explains these branches. When asking for help, record OS, client/core version and the failed step. Redact URL tokens, node passwords and other private values from error excerpts; sharing the entire profile is usually unnecessary.

Platform, third-party and advanced guides

The related guides below cover platform installation, particular third-party clients and server setup. Follow the common profile steps above first, then choose only the guide that matches the app or task you use.