sing-box Documentation

File: README.md Copy Chapter

sing-box

The universal proxy platform.

Documentation Copy Chapter

https://sing-box.sagernet.org

License Copy Chapter

Copyright (C) 2022 by nekohasekai <[email protected]>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

In addition, no derivative work may use the name or imply association
with this application without prior consent.

File: docs/clients/apple/features.md Copy Chapter

:material-decagram: Features

UI options

• Always On
• Include All Networks (Proxy traffic for LAN and cellular services)
• (Apple tvOS) Import profile from iPhone/iPad

Service

SFI/SFM/SFT allows you to run sing-box through NetworkExtension with Application Extension or System Extension.

TUN

SFI/SFM/SFT provides an unprivileged TUN implementation through NetworkExtension.

Chore Copy Section

• Crash logs is located in Settings -> View Service Log

File: docs/clients/apple/index.md Copy Chapter

icon: material/apple Copy Chapter

sing-box for Apple platforms

SFI/SFM/SFT allows users to manage and run local or remote sing-box configuration files, and provides
platform-specific function implementation, such as TUN transparent proxy implementation.

!!! failure ""

We are temporarily unable to update sing-box apps on the App Store because the reviewer mistakenly found that we violated the rules (TestFlight users are not affected).

:material-graph: Requirements Copy Chapter

• iOS 15.0+ / macOS 13.0+ / Apple tvOS 17.0+
• An Apple account outside of mainland China

:material-download: Download Copy Chapter

• App Store
• TestFlight (Beta)

TestFlight quota is only available to sponsors
(one-time sponsorships are accepted).
Once you donate, you can get an invitation by join our Telegram group for sponsors from @yet_another_sponsor_bot
or sending us your Apple ID via email.

:material-cellphone-arrow-down: Download (iOS jailbreak version) Copy Chapter

• GitHub Releases (SFI-iphoneos-arm64.deb)

The jailbroken version of SFI: requires rootless iOS 15.0+

Additional features:

• It can run a Tailscale SSH server on the device.
• Process matching (process_name, process_path, user, and so on) works in route and DNS rules.

:material-file-download: Download (macOS standalone version) Copy Chapter

• Homebrew Cask

# brew install sfm

• GitHub Releases

:material-source-repository: Source code Copy Chapter

• GitHub

File: docs/clients/android/features.md Copy Chapter

:material-decagram: Features

UI options

• Display realtime network speed in the notification

Service

SFA allows you to run sing-box through ForegroundService or VpnService (when TUN is required).

TUN

SFA provides an unprivileged TUN implementation through Android VpnService.

Override Copy Section

Overrides profile configuration items with platform-specific values.

Per-app proxy

SFA allows you to select a list of Android apps that require proxying or bypassing in the graphical interface to
override the include_package and exclude_package configuration items.

In particular, the selector also provides the “China apps” scanning feature, providing Chinese users with an excellent
experience to bypass apps that do not require a proxy. Specifically, by scanning China application or SDK
characteristics through dex class path and other means, there will be almost no missed reports.

Chore Copy Section

• The working directory is located at /sdcard/Android/data/io.nekohasekai.sfa/files (External files directory)
• Crash logs is located in $working_directory/stderr.log

File: docs/clients/android/index.md Copy Chapter

icon: material/android Copy Chapter

sing-box for Android

SFA allows users to manage and run local or remote sing-box configuration files, and provides
platform-specific function implementation, such as TUN transparent proxy implementation.

:material-graph: Requirements Copy Chapter

• Android 5.0+

:material-download: Download Copy Chapter

• Play Store
• Play Store (Beta)
• GitHub Releases
• F-Droid (Unified signature via reproducible builds)

:material-source-repository: Source code Copy Chapter

• GitHub

File: docs/clients/general.md Copy Chapter

icon: material/pencil-ruler Copy Chapter

General

Describes and explains the functions implemented uniformly by sing-box graphical clients.

Profile Copy Section

Profile describes a sing-box configuration file and its state.

Local

• Local Profile represents a local sing-box configuration with minimal state
• The graphical client must provide an editor to modify configuration content

iCloud (on iOS and macOS)

• iCloud Profile represents a remote sing-box configuration with iCloud as the update source
• The configuration file is stored in the sing-box folder under iCloud
• The graphical client must provide an editor to modify configuration content

Remote

• Remote Profile represents a remote sing-box configuration with a URL as the update source.
• The graphical client should provide a configuration content viewer
• The graphical client must implement automatic profile update (default interval is 60 minutes) and HTTP Basic
  authorization.

At the same time, the graphical client must provide support for importing remote profiles
through a specific URL Scheme. The URL is defined as follows:

sing-box://import-remote-profile?url=urlEncodedURL#urlEncodedName

Dashboard Copy Section

While the sing-box service is running, the graphical client should provide a Dashboard interface to manage the service.

Status

Dashboard should display status information such as memory, connection, and traffic.

Mode

Dashboard should provide a Mode selector for switching when the configuration uses at least two clash_mode values.

Groups

When the configuration includes group outbounds (specifically, Selector or URLTest),
the dashboard should provide a Group selector for status display or switching.

Chore Copy Section

Core

Graphical clients should provide a Core region:

• Display the current sing-box version
• Provides a button to clean the working directory
• Provides a memory limiter switch

File: docs/clients/index.md Copy Chapter

:material-cellphone-link: Graphical Clients

Maintained by Project S to provide a unified experience and platform-specific functionality.

Some third-party projects that claim to use sing-box or use sing-box as a selling point are not listed here. The core
motivation of the maintainers of such projects is to acquire more users, and even though they provide friendly VPN
client features, the code is usually of poor quality and contains ads.

File: docs/clients/index.zh.md Copy Chapter

:material-cellphone-link: 图形界面客户端

由 Project S 维护，提供统一的体验与平台特定的功能。

此处没有列出一些声称使用或以 sing-box 为卖点的第三方项目。此类项目维护者的动机是获得更多用户，即使它们提供友好的商业
VPN 客户端功能， 但代码质量很差且包含广告。

File: docs/clients/privacy.md Copy Chapter

icon: material/security Copy Chapter

Privacy policy

sing-box and official graphics clients do not collect or share personal data,
and the data generated by the software is always on your device.

Android Copy Chapter

The broad package (App) visibility (QUERY_ALL_PACKAGES) permission
is used to provide per-application proxy features for VPN,
sing-box will not collect your app list.

If your configuration contains wifi_ssid or wifi_bssid routing rules,
sing-box uses the location permission in the background
to get information about the connected Wi-Fi network to make them work.