Sublink Worker: A Subscription Converter for Cloudflare Workers, Vercel, Node.js and Docker

The problem Sublink Worker solves, and who it is for

Proxy clients do not agree on subscription formats. A base64 blob that one client accepts may be useless to another, and a full Clash YAML is not something every client can consume. Sublink Worker takes those inputs and re-emits them in the format a chosen client expects. The README lists the inputs as base64 subscriptions, HTTP/HTTPS subscriptions and full configs (Sing-Box JSON, Clash YAML, Surge INI), and the outputs as Sing-Box, Clash, Xray/V2Ray and Surge.

The intended user is someone who already runs proxy servers and needs to hand a link to a phone, a laptop and a router without maintaining a separate config file for each. The project's own description, One Worker, All Subscriptions, is a fair summary of that scope. It is not a proxy server. It does not tunnel traffic. Every deployment target in the README is a converter and a link store, nothing more.

How the converter is put together

The repository layout points to a single codebase compiled for several runtimes. The package.json declares hono as the web framework, js-yaml for parsing and emitting YAML, ioredis for Redis access, and esbuild as the bundler. The build:node script bundles src/platforms/node-server.js into dist/node-server.cjs as CommonJS targeting node18, which is how the same source ends up running outside Cloudflare.

Storage differs by target. On Cloudflare Workers and Vercel the README points at KV, and the Vercel deploy button asks for KV_REST_API_URL and KV_REST_API_TOKEN. The Docker Compose file instead wires the worker container to a redis service on REDIS_HOST: redis and REDIS_PORT: 6379, with REDIS_KEY_PREFIX set to sublink. That prefix matters if you share a Redis instance with other applications, because every generated short link is written under it.

Short links are described as fixed or random and KV-based. The fixed variant is the interesting one: it implies a stable identifier you can bookmark, which is the reason to store links server-side at all rather than regenerate them on each request. The README does not explain how collisions between fixed links are handled, and the repository's test directory is the only place that would answer it.

Installing Sublink Worker and generating a first link

The README offers one-click deployment for Cloudflare Workers and Vercel through the buttons in the header. For a local run, clone the repository and install dependencies first.

npm install
npm run dev

The dev script is wrangler dev, so this starts the Worker locally under Wrangler rather than a plain Node process. If you want the Node.js build instead, the README gives two commands: build the bundle, then run it.

npm run build:node && node dist/node-server.cjs

For a container deployment, the README points at the published image and the Compose file ships a Redis service alongside it. The Compose file maps port 8787 on the host and sets CONFIG_TTL_SECONDS to 2592000, which is 30 days. Setting that variable to 0 keeps stored configs without automatic expiration.

services:
  worker:
    image: ${SUBLINK_WORKER_IMAGE:-ghcr.io/7sageer/sublink-worker:latest}
    ports:
      - "8787:8787"
    environment:
      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_KEY_PREFIX: sublink
      CONFIG_TTL_SECONDS: 2592000

After the service is up, the web interface at the mapped port is where you import a subscription and pick an output client. The README mentions a light/dark theme toggle, predefined rule sets and customizable policy groups in that interface, and a separate API for script automation documented at sublink.works/api. What you should see after importing is a generated short link; what the README does not show is the exact response shape of the API, so read the API reference before writing automation against it.

Where Sublink Worker is the wrong tool

The sharpest limitation is the storage dependency. Short links live in KV or Redis, so a deployment without either backend cannot persist them. The README's quick start says to click a deploy button and stop, but the Vercel button explicitly requires KV_REST_API_URL and KV_REST_API_TOKEN, and the Docker path requires a reachable Redis. If you deploy the Worker without binding KV, the converter may still transform a subscription, but the link-management half of the feature list has nowhere to write.

Staleness is the second issue. CONFIG_TTL_SECONDS defaults to 30 days in the Compose file, which means a link you handed out can expire without warning. Setting it to 0 removes expiration but shifts the cleanup burden onto you. Neither choice is documented with guidance in the README.

Finally, the protocol list is fixed: ShadowSocks, VMess, VLESS, Hysteria2, Trojan and TUIC. If your server speaks something outside that set, the converter has nothing to emit. The README also carries a disclaimer that the project is for learning and exchange purposes, which is worth reading literally before you build a service around it.

How this differs from running a subscription panel

The obvious alternative for many operators is a self-hosted subscription panel, the kind that pairs a database and an admin UI with the proxy server itself. The difference in approach is where state lives. A panel typically owns user accounts, traffic accounting and the server inventory in one application. Sublink Worker owns none of that. It reads a subscription you already have and rewrites it, and the only state it keeps is the mapping from short link to stored config.

That makes Sublink Worker smaller to operate and easier to place on a free tier, since Cloudflare Workers and Vercel both host it. It also means it cannot answer questions a panel answers: who used how much, which node is healthy, which account should be disabled. If you need those, a panel is the right shape and Sublink Worker is a component you might put in front of it, not a replacement. The README's multi-language support (Chinese, English, Persian, Russian) suggests the project is aimed at individual operators and small groups rather than billing platforms.

Maintenance, upgrades and licence

The repository is not archived, and the last push was on 2026-09-13, so the codebase has moved recently. Releases are tagged: v2.4.2 on 2026-04-27, v2.4.1 on 2026-04-11 and v2.4.0 on 2026-04-10, and package.json carries version 2.4.2. The gap between the April release and the September push means fixes have landed on main without a tagged release in between, so pinning to a tag and pinning to main are different decisions.

Upgrade cost depends on the runtime. On Cloudflare Workers and Vercel, redeploying from the repository is the upgrade path the README implies through its deploy buttons. On Docker, the Compose file sets pull_policy: always on the worker image, so a compose up will fetch the latest image unless you override SUBLINK_WORKER_IMAGE with a specific tag. That default is convenient and also the reason a restart can change behaviour unexpectedly; overriding the image variable with a digest or tag is the way to hold a version.

The licence is MIT, stated in the README and present as a LICENSE file at the repository root. MIT permits commercial use and modification with the copyright notice retained. It offers no patent grant and no warranty, and nothing here is legal advice; if you redistribute the project, read the LICENSE file itself.

Editorial conclusion

Adopt Sublink Worker if you already have a Cloudflare account and want a converter that runs at the edge with KV-backed short links, or if you would rather self-host the Node.js build behind Docker Compose with Redis. Skip it if you need a desktop GUI, a billing model, or a documented rollback path, because the README describes none of those. Before committing, verify which storage backend your target runtime uses (KV on Workers and Vercel, Redis in the Docker Compose file), confirm the CONFIG_TTL_SECONDS value you want, and check that the protocols your clients actually speak appear in the supported list.

Frequently asked questions

Official sources

1. 7Sageer/sublink-worker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases