How to Add Nodes to sing-box: Configuration Files, Subscriptions, and Connection Troubleshooting

This article explains how to import nodes into sing-box, why a subscription URL might fail to import, and why websites may still be inaccessible after connecting. It also clarifies how exit IPs, DNS, and browser settings each affect your connection. Import options vary by platform and client version, so first check whether you have a node link, a subscription URL, or a sing-box configuration file.

1. Identify the type of node information you have

sing-box uses its own JSON configuration format, so not every proxy link can be imported directly as a complete configuration. First, determine which of these three types you have:

• Single node link: Usually starts with vless://, vmess://, trojan://, or a similar prefix. The client must explicitly support parsing that link type.
• Subscription URL: Usually an HTTPS link. It may return a node list, Clash YAML, or sing-box JSON, so you cannot determine compatibility from the URL alone.
• Complete configuration: Usually a JSON file containing inbounds, outbounds, routing, and other settings. This is the type to add through the configuration file option.

Supporting the sing-box core does not mean that every subscription format is supported.If the client cannot parse nodes or convert formats, ask your provider for a sing-box configuration compatible with your version. Do not simply change the file extension of a Clash file.

2. Import the configuration for your file type

1. Install a client suitable for your device from the project’s official release channel or a trusted app store. Check its documentation to confirm whether it supports local or remote configurations.
2. Open the client’s “Configuration,” “Profiles,” or similar page and add a configuration. Menu names vary between clients.
3. If you have a JSON file, choose the option to import from a file. If you only have the complete JSON text, paste and save it in an editor if the client supports one. If you have a remote configuration URL, choose the remote configuration option and enter the URL.
4. If you only have a single node link or a standard subscription, first check whether the client has an import option for it. If not, use a compatible configuration instead of pasting the link into a JSON editor.
5. Save the configuration, then run a configuration check or try starting it. If you see an unknown field or parsing error, note the error and check whether the configuration matches your client version.
6. Select the configuration and start it. Allow the VPN connection when prompted by your system. If the configuration includes multiple outbounds, select a node on the proxy or outbound page.

A subscription URL may contain a private token. Do not share screenshots of it or submit it to an untrusted online conversion site. When using free nodes from this site, first check which clients and formats they support. Successful import does not guarantee that a node will always be available.

3. Check your IP, DNS, and browser after connecting

First, open a regular webpage, then check your exit IP using a trusted IP lookup site. A connection status of “Connected” does not mean all your traffic is going through the proxy. Routing rules may send some websites directly, and an IP lookup site may also be routed directly. Check the client logs as well.

If the node connects but websites report that the domain cannot be resolved, check whether the DNS settings in your configuration are working. The browser’s secure DNS, the system’s encrypted DNS, and other VPN software may change the DNS resolution path. To troubleshoot, you can temporarily disable additional settings for comparison, then restore them as needed. Do not enter an unfamiliar DNS server without checking it first.

If the problem affects only one browser, try an incognito window and temporarily disable proxy extensions. Cookies, sign-in status, location permissions, and browser language can also affect how a website displays your region. Changing your exit IP does not guarantee that the region shown on the page will change as well.

4. Troubleshoot persistent problems in order

In order, check whether the subscription can be updated, whether your device’s clock is correct, whether the node is unavailable, and whether another proxy is conflicting. Use the logs to distinguish between configuration errors, connection timeouts, and DNS errors. Change only one setting at a time. Do not disable certificate verification just to clear an error. If the problem persists, ask for help with your client version and a redacted log, hiding addresses, tokens, passwords, and UUIDs.