sing-box
Installation and usage guide
Learn about sing-box graphical clients, remote profiles and everyday connection management. Covers installation, subscription import, everyday use and troubleshooting.
Get ready to connect
- A WahooVPN account you can sign in to, with an active plan and remaining traffic.
- Create a separate subscription link for this device using this format: sing-box JSON.
- Do not share your account password with strangers when installing third-party clients.
This guide uses a remote sing-box JSON configuration. Clash YAML and V2Ray node lists cannot be imported as a complete JSON configuration. Configuration fields must match the core version; capabilities such as VLESS, REALITY and XHTTP need individual verification. Cross-platform testing with a WahooVPN subscription on physical devices is still pending.
Choose the graphical client for your system
Open the official instructions below for your operating system, choose a compatible graphical client and install it. Interfaces and permission prompts differ by platform.
sing-box is a proxy core with graphical clients for different systems. For Android, follow the official SFA page; for iOS / macOS, use the Apple platform page; for Windows, use the desktop client page. Check each official page for system versions, architectures and download channels. The command-line core alone does not provide a graphical interface.
Get a sing-box subscription
Sign in to WahooVPN's Subscription Links page, select sing-box, create the link and copy the full URL. Use the server-provided configuration; do not give sensitive links to online converters.
Open WahooVPN subscription managementThe full link is shown only when created. If it is lost or exposed, manage the old link in your account and create a new one.
Add a Remote profile
Open the client's configuration / Profiles page, create a profile of type Remote, enter a name and subscription URL, then save. Exact button names depend on the installed client version.
Download and activate the profile
Update or download the remote profile. Check for JSON parsing, unknown field or download errors before selecting it as active. If an error occurs, check the sing-box format and core version first.
Start the service and choose an outbound connection
Start the current profile and grant the VPN or network permissions requested by the system. If the configuration includes selectable outbound groups, choose a node in the dashboard. Groups and modes depend on the configuration.
Test your target website and everyday apps
Check the service status and errors, open your target website, then try a commonly used local site. A running status only means the configuration has started; actual connectivity and routing still need testing.
Everyday use
Once connected, switch nodes, maintain subscriptions and check routing as needed.
Maintain remote profiles
- When nodes need refreshing, update the existing remote profile and check that it succeeds.
- Automatic updates and intervals depend on client settings. If needed, update manually and select the current profile again.
- Do not rely on direct edits to a remote profile for lasting customization; later downloads may overwrite local changes.
Understand modes and node groups
- The dashboard only offers modes and selectable outbound groups defined in the configuration.
- If node groups appear, check that the selected outbound connection is the one you intend to use. If no groups appear, check whether the configuration uses a fixed outbound connection.
- Do not assume that every sing-box client uses the Rule and Global mode menus found in other clients.
Check the core and configuration before upgrading
- Record the actual sing-box core version from the client information, then read official changes and migration notes before upgrading.
- For unknown or deprecated fields, compare server output with the core version. Do not arbitrarily delete fields just to make a profile load.
- When requesting help, share only redacted errors, app version and system information. Do not share the entire configuration or subscription URL.
Having trouble? Check these first.
Why does sing-box report JSON parsing errors or unknown fields?
Confirm that sing-box format was selected in your account, then check the required core version. Clash YAML, V2Ray node lists and complete sing-box JSON are different formats. Keep redacted errors for troubleshooting; do not bypass validation.
Why is there no node selector or mode switch?
Dashboard options depend on whether the configuration defines the relevant outbound groups and modes. The interface cannot create them on its own. First confirm the remote profile loaded correctly and is active.
Why is there no graphical interface after downloading?
The sing-box command-line core and graphical clients are separate releases. Return to the official client page for your platform and choose a graphical app matching your system and architecture. Avoid third-party repackaged installers.
What is a subscription link?
A subscription link is a personal configuration address supplied by a proxy service provider. It contains information such as nodes, connection configuration and traffic plan details.
How do third-party proxy clients differ from the WahooVPN app?
Both use the same WahooVPN server resources, but their workflows and features differ. The official WahooVPN app lets you sign in and connect with one tap, with automatic server selection and smart routing. Third-party clients such as Clash and v2rayN load server configurations through subscription links without signing in to your WahooVPN account; available features depend on the client.
Which client should a beginner choose?
Start with your device: Shadowrocket for iOS, v2rayNG for Android, or Clash Verge Rev for macOS and Windows. Once you choose an app, open its guide on this site to find the matching subscription format.
What if an update fails or the node list is empty?
Check that the URL is complete, the format matches and the link is enabled, unexpired and not revoked. Also check your account expiry and remaining traffic. Confirm your network can reach the subscription service. Do not paste credentials into third-party online testing tools.
Why can I import a subscription but still not connect?
Confirm an active node is selected and the proxy is started. Then check system proxy or VPN permissions, routing and conflicts with other VPNs. Some nodes may use transport parameters unsupported by the current core. Successful subscription parsing does not establish protocol compatibility.
What is the difference between the system proxy and TUN?
The system proxy is used by apps that follow system proxy settings. TUN handles traffic through a virtual network interface and usually needs extra permissions. Routing and app exclusions still determine its scope; it does not guarantee that all traffic uses the proxy.
What if a link is lost, exposed or expired?
The full link is shown only when created. Create a new link if you lose it. If you suspect exposure, revoke the old link in your account, then create and import a new one. Revocation is irreversible. Check link expiry and account plan expiry separately.
Sources and verification status
This guide is based on official client documentation. It has not yet been tested on the corresponding physical devices. Interface labels may change between versions; real screenshots and tested version records are still pending.
Read official client documentation