sub-trans-server

A lightweight subscription proxy server for V2Ray and Clash. It helps you pull and automatically decode/encode your subscription links, while masquerading as common clients to bypass API blockages.

Prerequisites

This tool uses Bun as its runtime. Please ensure Bun is installed on your system.

Quick Start

You do not need to clone the repository. You can run the server directly using bunx or npx:

# Recommended
bunx sub-trans-server

# Alternative (npm will still use Bun to execute it)
npx sub-trans-server

Environment Variables

You can configure the server using environment variables before running the command:

• PORT - The port for the server to listen on (default: 3000)
• UPSTREAM_URL - Optional. Your default fallback upstream subscription URL.

Example for Windows (PowerShell):

$env:PORT="8080"; bunx sub-trans-server

Example for Linux/macOS:

PORT=8080 bunx sub-trans-server

API Endpoints

• /ping Health check endpoint, returns pong.

• /sub?url=YOUR_SUB_LINK Proxy endpoint. Provide the target subscription link via the url parameter. If no URL is provided, it falls back to the UPSTREAM_URL environment variable. The server will fetch the link and automatically apply Base64 encoding if the original content is plain text.