Quick Start

The core goal of Sublink Worker is to minimize the barrier to self-hosting subscription conversion/distribution tools. Below is a three-step onboarding process based on the most common deployment methods.

1. Cloudflare Workers One-Click Deployment

If you've previously deployed GitHub apps via Cloudflare, you might encounter an An unknown error occurred error. See FAQ for solutions.

Click the button above to automatically fork and deploy. Or manually:

1. Go to Cloudflare Dashboard, select Workers & Pages → Create application → Pages → Connect to Git.
2. Authorize GitHub and select your forked sublink-worker repository.
3. In Build settings:
   • Framework preset: None.
   • Build command: npm run deploy.
   • Build output directory: Keep default.
4. Bind a custom domain (optional) to avoid *.workers.dev accessibility issues in certain regions.

After deployment, Cloudflare will inject KV and Worker environment variables, which work by default. If you need to bind Redis/Upstash, continue reading Runtime & Storage.

2. Vercel Deployment

Click the button above to quickly deploy to Vercel. The system will automatically guide you through configuring necessary environment variables. Or manually:

1. Import the forked repository in Vercel console.
2. Go to Settings → Environment Variables and add KV_REST_API_URL and KV_REST_API_TOKEN (auto-generated if using Vercel KV).
3. Run vercel deploy to get a serverless app powered by /api/index.js.

3. Docker / Compose Deployment

Docker Compose (Recommended)

# Clone repository
git clone https://github.com/7Sageer/sublink-worker.git
# Enter directory
cd sublink-worker
# Start
docker compose up -d

Docker Run

docker run -p 8787:8787 ghcr.io/7sageer/sublink-worker:latest

By default, running Docker containers directly won't persist data - short links/configs will be lost. We recommend configuring Redis/Upstash for data persistence. See Runtime & Storage for details.

4. Node.js Deployment

# Clone repository
git clone https://github.com/7Sageer/sublink-worker.git
# Enter directory
cd sublink-worker
# Install dependencies
npm install
# Build
npm run build:node
# Run
node dist/node-server.cjs

By default, running Node.js directly won't persist data - short links/configs will be lost. We recommend configuring Redis/Upstash for data persistence. See Runtime & Storage for details.

For Node.js, we recommend using process managers like PM2.

Generate Your First Subscription

1. Open the Worker root path (or Docker-exposed http://localhost:8787).
2. Paste your Base64/URL-encoded subscription.
3. Select a rule template (Balanced/Comprehensive, etc.), or add custom rules below.
4. Click Convert to export Sing-Box, Clash, Surge, Xray configs or QR codes. If short links are enabled, links will be stored in KV.

For more details on storage/variables, see Runtime & Storage. If you plan to modify base configurations, jump to Base Config (Experimental).