S-UI Subscription Formats Explained: Link vs JSON vs Clash

S-UI provides three distinct subscription formats—Link, JSON, and Clash—each optimized for different proxy clients, ranging from simple URI lists to full Sing-Box configurations.

The alireza0/s-ui subscription service generates user-specific proxy configurations through a unified backend that formats data differently based on the target client ecosystem. Understanding these S-UI subscription formats ensures you select the appropriate output for your specific proxy application, whether you are running Sing-Box, Clash-Meta, or a basic V2Ray client.

The Three Subscription Formats

S-UI serves subscription data from the /sub/ endpoint (default port 2096 as defined in service/setting.go) in three mutually exclusive representations. Each format is generated by specialized service logic within the repository.

Link Format

The Link format returns a plain-text file where each line contains a single proxy URI. These URIs follow standard schemes such as vmess://, trojan://, or shadowsocks://, making the format universally compatible with any client that imports "URL-list" subscriptions.

According to the source code in sub/linkService.go, the LinkService.GetLinks method constructs this output. The implementation optionally enriches responses with client metadata via addClientInfo, but the core output remains strictly newline-separated proxy URLs without additional JSON structure or routing rules.

JSON Format (Sing-Box)

The JSON format emits a complete Sing-Box-compatible configuration object containing fully populated inbounds, outbounds, routing rules, and DNS settings. This is the most comprehensive format, preserving every advanced option including TLS parameters, transport configurations, and protocol-specific settings.

In sub/jsonService.go, the JsonService.GetJson method merges user outbound links into the defaultJson base template. This process constructs a runnable configuration file that Sing-Box can consume directly without further modification.

Clash Format

The Clash format produces a JSON structure compatible with Clash, Clash-Meta, and Clash-X clients. While it uses JSON syntax like the Sing-Box format, it specifically includes a proxies array and proxy-groups selectors required by the Clash ecosystem.

Notably, this format is generated by the same JsonService.GetJson function when the request includes format=clash. The method actively filters the Sing-Box configuration, stripping fields that Clash does not recognize (such as specific mtls settings or certain transport options) while retaining only Clash-compatible proxy definitions and group structures.

Technical Comparison: Data Structure and Compatibility

When choosing between S-UI subscription formats, consider three primary technical distinctions:

Data Richness

• JSON carries the complete feature set: custom DNS servers, route rules, and inbound listeners.
• Clash maintains full proxy object definitions but drops Sing-Box-specific extensions.
• Link provides only the connection URI, containing zero metadata about routing or DNS.

Client Compatibility

• Use Link for mobile applications and lightweight clients that expect simple URI imports.
• Use JSON exclusively for Sing-Box deployments requiring advanced routing logic.
• Use Clash when connecting to Clash-based clients that rely on proxy group selectors.

Payload Size

• Link files scale linearly with outbound count (one line per proxy) but remain text-compact.
• JSON files are the largest due to complete object hierarchies for every configuration aspect.
• Clash files occupy a middle ground, containing structured proxy objects plus group definitions.

Accessing Subscription Formats via API

S-UI exposes all formats through the same HTTP endpoint, differentiating output via the format query parameter. The following commands demonstrate fetching a subscription named mySub from a server running on HOST:2096:

# Link format (default behavior)

curl -s http://HOST:2096/sub/mySub > subscription.txt

# Sing-Box JSON format

curl -s "http://HOST:2096/sub/mySub?format=json" > sing-box.json

# Clash-compatible format

curl -s "http://HOST:2096/sub/mySub?format=clash" > clash.json

The Link response contains only URI strings (e.g., vmess://eyJhZGQiOi...), while the JSON responses return structured configuration objects appropriate for their respective clients.

Core Implementation Architecture

The subscription system relies on two primary service files:

• sub/linkService.go: Implements LinkService.GetLinks for URI generation and optional client info injection.
• sub/jsonService.go: Houses JsonService.GetJson for both Sing-Box and Clash JSON generation, utilizing the defaultJson template as a foundation.

The service configuration in service/setting.go defines the default subscription path (/sub/) and listening port (2096), as referenced in the project's README.md feature documentation.

Summary

• Link format provides minimalist, newline-separated proxy URIs suitable for universal client import, implemented in sub/linkService.go.
• JSON format delivers complete Sing-Box configurations with full routing and DNS support via JsonService.GetJson in sub/jsonService.go.
• Clash format filters the Sing-Box output into Clash-compatible structures with proxies arrays and proxy-groups, sacrificing Sing-Box-specific features for Clash ecosystem compatibility.
• All formats share the same /sub/ endpoint and backend user management logic, differing only in the final serialization layer.

Frequently Asked Questions

Which S-UI subscription format should I use with Sing-Box?

Use the JSON format. As implemented in sub/jsonService.go, this output provides the complete configuration structure—including inbounds, outbounds, and routing rules—that Sing-Box requires to function. The Link format would require manual configuration of routing logic, while the Clash format strips Sing-Box-specific features.

Why does the Clash format lack some transport options?

The Clash format intentionally filters out Sing-Box-specific fields because the Clash ecosystem does not recognize them. When JsonService.GetJson receives format=clash, it strips advanced parameters like custom mtls configurations and certain transport settings, retaining only the subset of fields defined in the Clash schema to ensure client compatibility.

Can I use the Link format with Clash clients?

Yes, most modern Clash variants (including Clash-Meta) can import the Link format, but with significant limitations. While Clash can parse individual proxy URIs from the plain-text list, you lose the benefit of proxy-groups and automatic selectors that the Clash JSON format provides. For full Clash functionality, use the dedicated Clash format endpoint.

How do I retrieve my subscription via command line?

Use curl to request the specific format via the /sub/ endpoint. The default request returns Link format, while appending ?format=json or ?format=clash returns the respective configuration types. Ensure you target port 2096 (or your configured subscription port defined in service/setting.go) and include your subscription name in the path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}