Self-hosted sing-box subscription server: automated config delivery

What is a VPN Subscription Server and How to Automate Configs with a Sing-box Subscription URL?

You can automate VPN configuration distribution and ensure instant updates for dozens of clients by deploying your own subscription server on a VPS, which generates a single unique subscription url sing-box for each user, supporting up to 50 active connections on a 2 vCPU VPS.

If you've ever set up a VPN server for yourself, friends, family, or colleagues, you've likely encountered the hassle of manual configuration file distribution. Every server change—adding a new user, changing a port, updating a protocol, or simply optimizing settings—becomes a major headache: you need to generate a new config, send it to everyone via email, messenger, or file-sharing service, and then ensure each user installs and activates it. This process is inefficient, error-prone, and incredibly time-consuming. This is precisely where a VPN subscription server comes to the rescue.

A subscription server is a specialized component that allows you to centrally manage VPN configurations and automatically deliver them to client applications. Instead of sending files, you provide each user with a unique link—a VLESS subscription link, ShadowSocks, Hysteria2, or any other supported protocol. Client applications (e.g., Sing-box, Clash, Nekobox, V2RayNG) periodically query this link and automatically download the latest server list or updated settings. This ensures automatic configuration updates, freeing you from routine tasks and guaranteeing that everyone always has working configurations.

Why is Automated VPN Configuration Distribution Critical?

• Time Savings: Forget hours spent on forwarding and support. You spend 5 minutes on a server change, not 5 minutes * N users.
• Minimizing Errors: Human error is eliminated. The client always receives a correct and up-to-date configuration.
• Rapid Response to Blocks: If one of the servers or ports is blocked, you can quickly update it on the subscription server, and the changes will instantly propagate to all clients.
• User Convenience: Users don't need to do anything beyond adding the subscription link once.
• Centralized Management: It's always clear who is using which config and when.

How Do VPN Subscription Links Work? From VLESS to Sing-box Subscription URL

The mechanism behind VPN subscription links is both simple and elegant. Essentially, a VLESS subscription link or any other protocol's link is a regular HTTP(S) URL that returns a text file upon request. This file contains one or more VPN configurations, encoded in a specific way. Client applications like Sing-box, Xray-core, or Clash are capable of parsing the content of this file and using it for connection.

Common subscription formats include:

1. Base64-encoded JSON or Text List: Commonly used for VLESS, VMess, and ShadowSocks. The server generates a list of URL schemes (e.g., vless://..., ss://...), concatenates them into a single string, Base64-encodes it, and sends it to the client. The client then decodes the string to retrieve a list of available servers.
2. Clash-compatible YAML: For Clash clients and its forks, the server returns a YAML file containing the full configuration, including proxy servers, proxy groups, routing rules, and other logic. This powerful format enables fine-grained control over the VPN's behavior on the client side.
3. Sing-box JSON: With the emergence of Sing-box, a versatile client and server supporting numerous protocols including VLESS, Hysteria2, TUIC, and Reality, a subscription format returning a Sing-box-compatible JSON configuration has gained popularity. This enables using Sing-box as both server and client with a single, robust configuration. Deploying Sing-box on a VPS allows you to set up a universal server supporting all modern protocols.

When a user adds a Sing-box subscription URL or another link to their client, the application:

• Performs an HTTP request to the link.
• Receives a response containing encoded data.
• Decodes and parses the data.
• Automatically adds or updates the list of servers in its configuration.

Many clients allow you to configure an update interval (e.g., every 1, 3, 6, or 12 hours), ensuring configurations remain current without user intervention. This is particularly useful when you set up your own VLESS subscription on a VPS. It significantly streamlines config distribution to clients and keeps settings up-to-date.

Subscription Server Architecture: Generating and Storing Per-User VPN Configurations

At its core, a subscription server's power lies in its ability to generate unique and up-to-date configurations for each individual user or user group. Unlike a static file simply hosted on a web server, a dynamic subscription server operates as follows:

1. Unique User Identifier (UUID): Each user is assigned a unique UUID. This can be a UUID used in VLESS/VMess protocols or a simple unique token for subscription identification. This UUID or token is embedded within the subscription link itself (e.g., https://sub.valebyte.com/get_config?token=USER_UUID).
2. User Database: The subscription server stores information about each user, including their UUID, permitted protocols, traffic limits (if applicable), subscription expiry date, and activity status.
3. Dynamic Generation: When a client requests a subscription link, the server performs these steps:
   • Extracts the UUID/token from the URL.
   • Validates it against the database: checking if the user is active, if the subscription has expired, and if access is permitted.
   • Based on user data and the current VPN server status (available ports, IP addresses, protocols), it generates an up-to-date list of configurations.
   • Formats this list into the required format (Base64, YAML, Sing-box JSON).
   • Returns the result to the client.
4. Access Revocation: To block a user's access, simply change their status in the database. The next time the client requests a subscription, the server will either deny the configuration or return an empty list, effectively revoking access.

This approach provides flexible management of both access and configurations. For instance, you can temporarily disable a user if they exceed their traffic limit, or switch them to an alternative server if the primary one is overloaded or blocked. For anyone looking to build their own VPN service on a VPS with billing and automation, this architecture forms the foundation.

Quick pick

Need a dedicated server?

Bare metal with NVMe in 70+ locations — configure and order in minutes.

Browse servers

Practical Implementation: Deploying a VPN Subscription Server on a VPS with HTTPS

To deploy your own subscription server, you'll need a reliable VPS. Valebyte.com offers various plans perfectly suited for these tasks. Your VPS should have a stable internet connection, ample bandwidth, and ideally SSD/NVMe disks for optimal performance.

VPS Requirements and Basic Tech Stack

• Operating System: Linux (Ubuntu Server, Debian).
• Web Server: Nginx or Caddy for proxying requests and providing HTTPS.
• Programming Language/Environment: Python (with Flask/Django), Node.js (with Express), Go, PHP (with Laravel/Symfony), or even a simple Bash script with CGI.
• Database: SQLite (for simple solutions), PostgreSQL, or MySQL (for scalable systems).
• Domain Name: Required for issuing HTTPS certificates.

Step-by-Step Setup Guide (General Approach)

1. VPS Preparation:

   Install the necessary packages:

   sudo apt update
   sudo apt upgrade -y
   sudo apt install -y nginx python3 python3-pip certbot python3-certbot-nginx
   

2. Domain and HTTPS Configuration:

   Point a subdomain (e.g., sub.yourdomain.com) to your VPS's IP address. Use Certbot to obtain a free Let's Encrypt SSL certificate:

   sudo certbot --nginx -d sub.yourdomain.com
   

3. Creating the Subscription Generation Script:

   Assume you have a Python script that accepts a token and returns a Base64-encoded list of VLESS configurations. This script can interact with your main VPN server or a database storing user UUIDs and their settings.

   Example VLESS response structure (Base64-encoded):

   vless://<UUID>@<SERVER_IP>:<PORT>?security=tls&type=ws&path=%2Fws&host=<DOMAIN>#Valebyte-User1
   vless://<UUID2>@<SERVER_IP2>:<PORT2>?security=tls&type=tcp&flow=xtls-rprx-vision#Valebyte-User2
   

   This text is then Base64-encoded.

4. Configuring Nginx for Proxying:

   Configure Nginx to proxy requests to your subscription script. Example Nginx configuration (file /etc/nginx/sites-available/sub.yourdomain.com):

   server {
       listen 80;
       listen [::]:80;
       server_name sub.yourdomain.com;
       return 301 https://$host$request_uri;
   }
   
   server {
       listen 443 ssl http2;
       listen [::]:443 ssl http2;
       server_name sub.yourdomain.com;
   
       ssl_certificate /etc/letsencrypt/live/sub.yourdomain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/sub.yourdomain.com/privkey.pem;
       ssl_session_cache shared:SSL:10m;
       ssl_session_timeout 10m;
       ssl_protocols TLSv1.2 TLSv1.3;
       ssl_prefer_server_ciphers on;
       ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES128-SHA256:DHE-RSA-AES256-SHA256";
   
       location / {
           proxy_pass http://127.0.0.1:5000; # Порт, на котором слушает ваш скрипт
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }
   

   After saving the file, activate the configuration and restart Nginx:

   sudo ln -s /etc/nginx/sites-available/sub.yourdomain.com /etc/nginx/sites-enabled/
   sudo nginx -t
   sudo systemctl restart nginx
   

Subscription Link Security: Preventing Leaks and Managing Expiration

The uniqueness of a subscription link is both its strength and its vulnerability. If a link leaks, anyone can use it. To minimize risks:

• Limited Validity Period: Generate links with a limited validity period (e.g., 30 days) and automatically revoke them upon expiration. The user will then need to request a new link.
• IP Binding: For critical subscriptions, you can implement binding to the IP addresses from which requests originate. If requests start coming from unfamiliar IPs, the link can be temporarily blocked.
• One-time Use Tokens: Links that issue a configuration only once and then become invalid. The client must save the config locally. This is less convenient but maximally secure.
• Usage Monitoring: Track the number of requests to each link. An abnormally high number of requests may indicate a leak.
• Complex and Long UUIDs/Tokens: The more complex the token in the link, the harder it is to guess or brute-force.

VPN Control Panels with Subscription Support: 3x-ui and Marzban

For those who prefer not to build from scratch, ready-made control panels significantly simplify the deployment and management of VPN servers with subscription support. These panels automate config generation, user management, and link distribution.

3x-ui: A User-Friendly and Feature-Rich VPN Panel

3x-ui is a web panel for managing Xray-core (a V2Ray fork), offering an intuitive interface for user creation, management, and subscription link generation. It supports VLESS, VMess, Trojan, ShadowSocks, and other protocols.

Key Features of 3x-ui:

• Create users with individual UUIDs and settings.
• Generate subscription links (Base64-encoded URL list) for each user or all at once.
• Manage traffic limits and expiry dates.
• Monitor traffic usage per user.
• Support for TLS and Reality for traffic obfuscation.

After installing 3x-ui on your VPS, you can access the web interface, add a new user, select a protocol (e.g., VLESS with Reality), and the panel will automatically generate a subscription link. You then simply provide this link to the client.

Example subscription link provided by 3x-ui:

https://your_3xui_domain.com/api/v1/client/subscribe/<UNIQUE_TOKEN>

This panel is an excellent choice for deploying your own VPN on a VPS with VLESS Reality and Xray-core in 10 minutes and managing it through subscriptions.

Marzban: A Powerful Solution for Advanced Users

Marzban is a more advanced panel built on Xray-core, offering extensive capabilities for managing VPN servers, including multi-server configurations, billing, and highly detailed subscription settings. Marzban is particularly popular for its flexibility and API, which enables integration with other systems.

Key Advantages of Marzban:

• Support for multiple servers (nodes) and user distribution among them.
• Advanced settings for each user: protocols, limits, groups.
• Detailed traffic usage statistics.
• Built-in tools for domain and SSL certificate management.
• API for task automation and integration with billing systems.
• Support for various subscription formats (Base64, Clash YAML, Sing-box JSON).

Marzban not only allows issuing individual VLESS subscription links but also managing them centrally, making it an excellent choice for those who use Hiddify on a VPS or plan to deploy a more complex VPN service.

How to Build a Minimal VPN Subscription Server from Scratch: An Automation Script

If off-the-shelf panels seem excessive or you desire full control over the process, you can create a minimal VPN subscription server using a simple script. Let's explore an example in Python, leveraging Flask for the web server and SQLite for the user database.

Project Structure

vpn_sub_server/
├── app.py
├── users.db
└── vless_template.json

1. vless_template.json File (VLESS Configuration Template)

This template will be used to generate VLESS links. Here, <UUID>, <SERVER_IP>, <PORT>, <DOMAIN> will be dynamically replaced.

{
    "vless_server_ip": "YOUR_VPN_SERVER_IP",
    "vless_port": 443,
    "vless_domain": "your.vpn.domain.com",
    "vless_path": "/ws",
    "vless_security": "tls",
    "vless_type": "ws"
}

2. app.py File (Main Script)

import json
import base64
import sqlite3
from flask import Flask, Response, request
import os

app = Flask(__name__)
DATABASE = 'users.db'
VLESS_TEMPLATE_FILE = 'vless_template.json'

# Инициализация базы данных
def init_db():
    with sqlite3.connect(DATABASE) as conn:
        cursor = conn.cursor()
        cursor.execute('''
            CREATE TABLE IF NOT EXISTS users (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                uuid TEXT NOT NULL UNIQUE,
                name TEXT NOT NULL,
                is_active BOOLEAN DEFAULT 1,
                created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                expires_at DATETIME
            )
        ''')
        # Добавляем тестового пользователя, если его нет
        cursor.execute("INSERT OR IGNORE INTO users (uuid, name, is_active) VALUES (?, ?, ?)", 
                       ('your_test_uuid_1234567890abcdef', 'TestUser', 1))
        conn.commit()

# Загрузка шаблона VLESS
def load_vless_template():
    if not os.path.exists(VLESS_TEMPLATE_FILE):
        # Создаем шаблон, если его нет
        with open(VLESS_TEMPLATE_FILE, 'w') as f:
            json.dump({
                "vless_server_ip": "192.0.2.1", # Замените на IP вашего VPN-сервера
                "vless_port": 443,
                "vless_domain": "vpn.valebyte.com", # Замените на домен вашего VPN-сервера
                "vless_path": "/ws",
                "vless_security": "tls",
                "vless_type": "ws"
            }, f, indent=4)
    with open(VLESS_TEMPLATE_FILE, 'r') as f:
        return json.load(f)

# Генерация VLESS-ссылки
def generate_vless_url(user_uuid, user_name, template):
    server_ip = template['vless_server_ip']
    port = template['vless_port']
    domain = template['vless_domain']
    path = template['vless_path']
    security = template['vless_security']
    _type = template['vless_type']

    # Формируем VLESS-ссылку
    vless_url = (
        f"vless://{user_uuid}@{server_ip}:{port}?"
        f"security={security}&type={_type}&path={path}&host={domain}"
        f"#{user_name}"
    )
    return vless_url

@app.route('/subscribe/')
def subscribe(uuid_token):
    with sqlite3.connect(DATABASE) as conn:
        cursor = conn.cursor()
        cursor.execute("SELECT uuid, name, is_active, expires_at FROM users WHERE uuid = ?", (uuid_token,))
        user_data = cursor.fetchone()

        if not user_data:
            return Response("User not found or subscription expired.", status=404)

        user_uuid, user_name, is_active, expires_at = user_data

        if not is_active:
            return Response("Subscription inactive.", status=403)
        
        # Проверка срока действия (если expires_at есть)
        if expires_at and expires_at < str(os.datetime.now()): # Упрощенная проверка
             return Response("Subscription expired.", status=403)

        vless_template = load_vless_template()
        vless_url = generate_vless_url(user_uuid, user_name, vless_template)
        
        # Кодируем список URL (в данном случае один) в Base64
        encoded_config = base64.b64encode(vless_url.encode('utf-8')).decode('utf-8')

        return Response(encoded_config, mimetype='text/plain')

if __name__ == '__main__':
    init_db()
    # Создаем шаблон, если его нет
    load_vless_template() 
    app.run(host='127.0.0.1', port=5000, debug=False) # Запускаем на локальном порту

How it Works:

1. init_db(): Creates the SQLite database users.db and the `users` table if they don't exist. It also adds one test user with the UUID your_test_uuid_1234567890abcdef.
2. load_vless_template(): Loads VPN server parameters from vless_template.json. If the file doesn't exist, it creates it with default values that you'll need to modify.
3. generate_vless_url(): Constructs the full VLESS link based on the user's UUID and template data.
4. /subscribe/<uuid_token>: This is the endpoint that clients will access. It accepts a `uuid_token`, searches for it in the database. If the user is found and active, it generates a VLESS link, Base64-encodes it, and sends it to the client.

Running the Script:

pip install Flask
python3 app.py

Once launched, the script will listen on http://127.0.0.1:5000. Nginx, configured previously, will proxy requests from https://sub.yourdomain.com/subscribe/<uuid_token> to this local port.

To automatically update configs, simply modify vless_template.json (e.g., change the VPN server's IP or port), restart the Flask application, and clients will receive the new configuration on their next update. Adding a new user is as simple as adding a record to the `users.db` database.

Quick pick

Need a dedicated server?

Bare metal with NVMe in 70+ locations — configure and order in minutes.

Browse servers

Scaling and Security: Dedicated Domains for VPN Subscriptions and Access Revocation

As your user base grows and the threat of blocks increases, scaling and security become critically important for your VPN subscription server. This is particularly relevant when you're looking to distribute VPN access to friends or a larger group, not just 2-3 individuals, but dozens or hundreds.

Using a Dedicated Domain for VPN Subscription Links

A common challenge with VPN subscriptions is that the domain used for distributing them can also be blocked. Should this occur, clients will be unable to update their configurations, even if the VPN server itself is operating on a different IP or domain.

Solution: Use a separate domain (or subdomain) exclusively for your subscription server. For example, if your VPN server is accessible at vpn.valebyte.com, then subscription links could be at sub.valebyte.com. This offers several advantages:

• Risk Separation: A block on the subscription domain won't immediately affect the VPN server's operation, and vice-versa.
• Flexibility: You can host the subscription server on a separate VPS in a different location to make it more resilient to blocks.
• Obfuscation: The subscription domain doesn't necessarily need to resemble a VPN service, which can reduce attention from DPI systems.

It's crucial that the subscription domain also uses HTTPS to prevent link interception or modification. For enhanced resilience, you could configure a CDN for the subscription domain, though this adds architectural complexity.

Managing User Access and Revocation

Effective access management is a key component of a reliable subscription server. Beyond simply deactivating a user in the database, you can implement more sophisticated scenarios:

• Temporary Blocking: If a user exhibits suspicious behavior (e.g., too many subscription requests, unauthorized traffic), their access can be temporarily suspended.
• UUID Rotation: For enhanced security or in case of an old UUID leak, you can generate a new UUID for the user and automatically update it in their configurations.
• Multi-factor Authentication: For access to the subscription link itself, you can add additional authentication (e.g., by IP address or an extra token in HTTP headers).
• Automatic Deletion of Inactive Subscriptions: If a subscription hasn't been used for an extended period (e.g., 3-6 months), it can be automatically deactivated or deleted.

All these features help maintain order, reduce server load, and enhance the overall security of your client config distribution system.

Choosing the Right VPS for Your VPN Subscription Server and Traffic

Selecting the appropriate VPS is a fundamental step to ensure the stable and fast operation of your VPN service and subscription server. Valebyte.com offers a wide range of VPS and dedicated servers capable of meeting diverse needs—from a small VPN for friends to a large-scale service for hundreds of users.

When choosing a VPS for your VPN server and subscription server, it's important to consider several key parameters:

1. Server Location: Choose locations that provide minimal latency (ping) for your users. European locations are often optimal for users in Europe and surrounding regions, while Asian locations suit eastern regions.
2. Bandwidth: VPN servers consume significant traffic. Ensure your plan includes sufficient bandwidth (e.g., 1 Gbps) and a generous monthly traffic allowance (from 1 TB).
3. Processor (vCPU): Encryption and traffic processing demand CPU power. The more users you have, the more robust your processor needs to be. For 50-100 users, 4 vCPUs are recommended.
4. RAM: While Xray-core, Sing-box, and other VPN servers don't demand extensive RAM, the control panel (3x-ui, Marzban), database, and the subscription script itself will require a minimum of 2-4 GB.
5. Disk Subsystem (SSD/NVMe): Even a small amount of storage (20-40 GB) will suffice for configurations, logs, and the database, but it's crucial to use fast SSD or NVMe disks.

For 50-100 active VPN users, 4 vCPU, 8 GB RAM, and an 80 GB NVMe disk are sufficient.

If you're unsure which plan to choose, it's always better to start with a more powerful VPS to avoid performance and traffic issues down the line. Also, consider using a VPS or dedicated server for VPN when 100 Mbps is no longer sufficient.

Remember that a subscription server doesn't demand the same resources as the VPN server itself, which handles all traffic. Often, it can be hosted on the same VPS as your primary VPN if resources are sufficient, or on a separate, less powerful VPS for added fault tolerance.

Frequently Asked Questions

What is a VPN subscription server and why do I need it?

A VPN subscription server – is a tool for automatically distributing and updating VPN configurations. It provides users with a unique link from which their VPN client independently fetches the latest settings. This eliminates the need for manual config distribution with every change, saving time and minimizing errors, ensuring instant updates for dozens of users.

What is the advantage of a VLESS subscription link over a regular config file?

The main advantage of a VLESS subscription link is automation. Instead of manually copying and pasting a new VLESS config every time, the user adds the link once. The client application (e.g., Sing-box) periodically queries this link and automatically updates the configuration, which is especially convenient for frequent changes or blocks affecting up to 10-20% of servers.

How can I protect my subscription url sing-box from leaking?

To protect your subscription url sing-box, you can use several methods. First, generate complex and long UUIDs or tokens for each link. Second, consider setting an expiration date for subscriptions (e.g., 30 days) with automatic revocation. It's also useful to monitor the number of requests to each link; an abnormally high number of requests (more than 50-100 per hour) may indicate a leak.

How much does it cost to deploy my own VPN subscription server on a VPS?

The cost to deploy your own VPN subscription server on a VPS starts from approximately $5 per month for a basic VPS with 2 vCPU, 2 GB RAM, and a 20 GB NVMe disk (Valebyte.com price as of Q2 2024). This configuration is sufficient to serve up to 10-20 users and the subscription server itself. For higher loads (over 100 users), a VPS costing $20-$40 per month or more will be required.

Can the domain used for the subscription link be blocked?

Yes, the domain used for the subscription link can be blocked, just like the domain of the main VPN server. To mitigate this risk, it's recommended to use a separate, inconspicuous domain or subdomain exclusively for the subscription server. It's also beneficial to configure HTTPS on this domain so that requests appear as regular web traffic and are less noticeable to DPI systems.

Quick pick

Need a dedicated server?

Bare metal with NVMe in 70+ locations — configure and order in minutes.

Browse servers

Conclusion

Implementing your own VPN subscription server on a VPS is a fundamental solution for automating client config distribution and ensuring uninterrupted operation. Whether you opt for ready-made panels like 3x-ui and Marzban or build a minimal script, the key advantage remains automatic config updates via a single VLESS subscription link or Sing-box subscription URL. Valebyte.com offers reliable VPS solutions that provide an ideal foundation for your subscription server, guaranteeing stability and high performance.

SSD NVMe

Ready to launch your VPS?

NVMe VPS with 60-second activation: full root access, 20+ locations, pay with card or crypto.

Choose a plan