cf-SubCloud: a Cloudflare Worker that turns subscriptions into Mihomo configs

What cf-SubCloud does with a subscription link

cf-SubCloud sits between a set of subscription sources and a client that needs a configuration file. The README describes it as a Mihomo, formerly Clash Meta, subscription aggregation tool with Sub-Store built in, able to generate Clash and singbox configuration files quickly and to provide routing rules and privacy protection features.

The output side is broad. The tool natively produces mihomo, Clash and singbox configuration files, and the README stresses that all node parameters are retained without conversion loss, that it is compatible with various subscription link formats, and that conversion runs through an integrated Sub-Store backend. The input side is broader still: multiple subscriptions can be aggregated into one output, a single node address is accepted, singbox gets automatic node filtering, and custom routing rules can be applied.

The package manifest describes the project in one line as a Cloudflare Worker for Mihomo subscription service, version 1.4.33, marked private and MIT licensed. The README title is a configuration generator, and the wording matters: nothing here forwards your traffic. A client asks the deployed worker for a configuration, the worker assembles one from your sources, and the client then makes its own connections. The privacy claims in the README, DNS ad blocking through the built-in Adblock function, protection against DNS and WebRTC leaks, and secure DNS with DoH support, are properties of the generated configuration rather than of the worker process.

The client side of that contract is where the Singbox-specific work shows up. The README states support for singbox 1.11.x and above, automatic adaptation to the version when generating the configuration, and a no-popup experience across the iOS, Google and GitHub versions of the client.

How a request becomes a configuration file

The repository layout explains the mechanism. There is a src directory holding the worker code, a template directory holding the rule templates, a test directory, and an esbuild.js build script with a dev-esbuild.js counterpart for the watch mode used during development. The presence of .gitmodules at the root is the important detail: Sub-Store is pulled in as a git submodule rather than vendored, which is why the deployment guide makes initialising and updating submodules an explicit step.

Configuration is assembled from two template references. The TPLMH variable points at a mihomo rule template and TPLSB points at a singbox rule template, and the README gives a raw template URL for each of them as a reference. The templates are ordinary YAML files, and the only runtime dependency besides core-js is the yaml package, which is what lets the worker read and rewrite those documents.

Request handling has one switch worth naming. The CHECKUA variable is described as request validation with the example value `true`, and the README's usage advice asks users to turn off all override features, that is the override options themselves rather than the ability to override, and recommends the clashmi client. The other variables shape the response rather than the routing: IMG is the background image URL shown by the web console, and BEIAN and BEIANURL carry a filing notice and the link it points to, which in the README's example is a Chinese ICP registration number and a link to it.

Setting up a local copy with pnpm and the Sub-Store submodule

The deployment guide is written for a self-hosted build rather than for a package install, and the order of the steps matters. Dependencies first, then the submodule, then the build.

pnpm install
git submodule update --init --recursive
git submodule update --remote --recursive
pnpm build
pnpm run dev

The submodule step is not optional. `git submodule update --init --recursive` fetches Sub-Store into the working tree, and a later step, `git submodule update --remote --recursive`, moves the checkout to the latest upstream commit. A build run before those commands would produce a worker without its conversion backend, which is the most likely first failure for someone cloning the repository and running the build script straight away.

The build itself is a node script, `node esbuild.js`, and package.json exposes it as the build script. For development, the dev script runs two things at once with concurrently: an esbuild watch process that rebuilds when src or package.json changes, and a runner that waits for dist/min.js to exist before executing it under nodemon. The wait-on dependency is there for exactly that ordering.

The manifest also lists prettier as the lint script, so formatting is applied by `prettier --write .` rather than by a separate style configuration, and the repository carries a .prettierrc and .prettierignore. The dev dependencies are modest and current: esbuild 0.25.8, wrangler 4.107.1, vercel 50.37.3, nodemon, concurrently and wait-on.

Deploying the worker to Vercel or Cloudflare Workers

Two hosting targets are documented, and the same codebase serves both. The Vercel path offers a one-click deploy button and a CLI alternative. The README lists the prerequisites as a Vercel account, Node.js v16 or newer and Git, and the button path is a four-step flow ending with a one to three minute wait. The CLI path is a single command.

npm run deploy
npx wrangler deploy --keep-vars
npm run deploy:workers

The Cloudflare Workers path uses the official deploy button as well, and it spells out the two parameters the dashboard needs. The build command is `npm run build` and the deploy command is `npx wrangler deploy --keep-vars`, where the keep-vars flag preserves the environment variables already configured on the worker instead of overwriting them with the local defaults. That flag is the difference between a redeploy that keeps your configuration and one that silently resets it, and it is easy to miss.

The wrangler.toml file at the repository root holds the worker configuration, and the package.json scripts map to the same two targets: `vercel --prod` for a production Vercel deployment and `wrangler deploy` for Workers. The build output is bundled by esbuild into a single file, dist/min.js, which is what the worker entry point loads.

The environment variables that shape the output

Seven variables control the worker, and the README tabulates each one with an example value.

IMG
SUB
BEIAN
BEIANURL
CHECKUA
TPLMH
TPLSB

Four of them decide what the worker actually serves. SUB is the conversion backend address, and the example points at a Sub-Store-node deployment, which means the worker calls out to a backend to do the conversion rather than doing it in-process. TPLMH and TPLSB supply the mihomo and singbox rule templates, and CHECKUA turns request validation on or off. The remaining three are presentation: IMG is the background image for the console, BEIAN is the filing information text, and BEIANURL is where that filing notice links to.

The design consequence of the SUB variable is worth pausing on. Because the conversion backend is a separate address, a deployment has two moving parts, and the worker needs network access to that backend. That affects where you deploy, since a Worker in one region reaching a backend in another adds latency to every config fetch, and it affects availability, since the backend becomes part of your failure path. Pointing SUB at a backend you control is the difference between a service you can fix and a service you can only wait for.

Where cf-SubCloud is the wrong tool

The first limitation is the one implied by the architecture. The worker is a configuration generator, not a tunnel and not a client, so it does nothing for a device that cannot run mihomo or singbox. The README's own advice points at a specific client, clashmi, and the Singbox section assumes an iOS, Google or GitHub build of that client family. If your devices run something else, the generated file has no consumer.

The second is the flip side of a public deployment. The convenience of one URL that clients fetch is exactly what makes a hosted instance worth thinking about carefully: subscription URLs are credentials in practice, and a configuration service that is publicly reachable is a place where those URLs could leak, whether through the project's code or through a mistake in your own configuration. The CHECKUA request validation option is the project's answer to that concern, and enabling it is the sensible default, but the README does not document how validation is performed or what it protects against, so treat it as a mitigation rather than a guarantee.

The alternative worth comparing is running Sub-Store yourself, without the worker, on a machine or server you control, and pointing a client at it directly. The difference in approach is concrete. The worker gives you a hosted URL that any client can fetch with no local software, which is the right choice when the devices are locked-down or shared. A local Sub-Store keeps the subscription URLs on your own network and removes the deployed service from the path entirely, at the cost of running it yourself. Which one is better depends on where the subscriptions live and who hosts them, not on speed.

On maintenance, the repository is not archived and the last push was on 2026-09-06, with releases v1.4.32 on 2026-09-04 and v1.4.31 on 2026-09-03. The licence is MIT, copyright 2025 Kwisma, which means you can fork and self-host the generator without restriction on use, which matters because the README's own deployment targets are account-based services.

Editorial conclusion

cf-SubCloud is worth adopting when your clients are mihomo or singbox based and you want one public URL that returns a refreshed configuration, and when you can host it yourself on Vercel or Cloudflare Workers with your own Sub-Store backend. It is the wrong tool if you need a local private aggregation point or if your clients are not mihomo family clients. Verify first that the Sub-Store submodule initialises with `git submodule update --init --recursive`, because the build depends on it, and that the SUB backend you point at is reachable from the deployed region.

Frequently asked questions

Official sources

1. Kwisma/cf-SubCloud on GitHub
2. License: MIT
3. Project website
4. README
5. Releases