SubConverter-Extended, a subscription conversion backend that hands Mihomo the fetching job

A conversion backend with no nodes to give away

SubConverter-Extended is a conversion service, and the README is unusually explicit about what that means. It states that the project provides no proxy servers, no proxy nodes and no node subscriptions, that it does not operate subscription resale services, and that its maintainers have no cooperation, agency or guarantee relationship with the operators of such services. What the code actually does is take subscription links or node links, apply a template and rules, and emit a configuration a specific client can import. The audience is therefore people who already hold their own subscriptions and want the format conversion removed from their workflow. The listed targets include `clash` and `clashr` for Mihomo node parsing, `surge`, `quanx`, `loon`, `surfboard` and `stash` for client native remote resources, `quan`, `mellow` and `singbox` for full configuration conversion, and a long tail of single node output formats such as `vless`, `hysteria2` and `trojan`.

Protocol parsers that lag, and the Mihomo bridge that answers

The project states three reasons for existing. The first is protocol lag: the upstream parser needed manual work whenever a protocol, transport or parameter changed, so `hysteria2`, `tuic` and `anytls` had to be adapted one at a time, and existing protocols such as `vless` kept needing attention as transport parameters evolved. The answer here is a parsing bridge. For `target=clash` and `target=clashr`, node links only enter the Mihomo parsing bridge, and the resulting protocol capability comes from a locked Mihomo dependency rather than from a parser maintained separately. The repository layout shows a Go bridge directory containing `converter.go`, `parser.go`, `preprocess.go`, `age.go` and `mieru.go`, alongside the C++ sources, so the Mihomo behavior is inherited rather than reimplemented. The README also marks Mihomo work as the first optimization direction, with `clash` and `clashr` parsing, provider and protocol parameter support taking priority over other clients.

Two routes a remote subscription can take

The interesting design decision is where the fetch happens. In the traditional subconverter flow, the conversion backend connects to the remote subscription server, downloads the content, parses it and returns a finished file. The project describes this as a failure point: some subscription providers restrict overseas IP addresses, restrict the User-Agent the converter uses, or block requests that do not come from a client, so the client can update its subscription directly while the converter cannot obtain the same content. Changing the User-Agent only handles User-Agent based restrictions and does nothing about region or egress IP limits. The Provider path answers this by generating `proxy-providers` entries for Mihomo, which lets the client itself update the remote subscription. For Surge, Quantumult X, Loon, Surfboard and Stash the service instead generates client native remote resources. The README is careful here: whether the client updates a remote subscription depends on the target format, the request parameters and the input type, and `list=true` and other client targets follow their own flows.

Running the service on port 25500 with Compose

The repository ships a Compose example. The image is published under the name `aethersailor/subconverter-extended`, the service listens on port 25500, and the container restarts unless stopped. The example keeps the timezone at `Asia/Shanghai` and shows the environment variables as comments, with the note that environment variables override the corresponding settings in `pref.toml`. The Compose file also carries a comment on the published port, explaining that keeping the all interface publication is convenient for LAN devices and that a host only binding can be written by hand. The Compose example is the shortest path to a running instance, and the Wiki also links separate Docker and native deployment pages for anyone who wants to build from source instead.

services:
  subconverter-extended:
    container_name: SubConverter-Extended
    image: aethersailor/subconverter-extended:latest
    ports:
      - "25500:25500/tcp"
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai

After the container starts, the service is reachable on port 25500 of the host. The README points first time users to the Wiki Getting Started page for producing a first configuration and to the compatibility page for deciding which `target` the client should use.

A build that follows a moving Mihomo ref

The Dockerfile shows a Go build stage, and its most consequential line is a build argument rather than a pinned version. `MIHOMO_REF` defaults to `Alpha`, and the build resolves the Mihomo module against that ref, then reads the resolved module version with `go list -m`. A separate `MIHOMO_CACHE_BUST` argument exists to force that resolution again, and the dependency step is wrapped in a retry helper that attempts the command three times with increasing sleeps before giving up. This matters for operators rather than for readers of the interface: a build that follows a moving ref means the protocol surface of a given image is only pinned by the build time, not by the source tree. The multi stage layout also mixes a Debian based Go builder with Alpine and Debian variants for the runtime, and the builder comment explains that the Go shared library is compiled against glibc to avoid a musl runtime initialization crash.

Security profile and resource control stay opt in

The Compose example documents three environment variables that change how the service accepts work. `SUBCONVERTER_SECURITY_PROFILE` selects a profile, with `lan` as the default that preserves existing LAN behavior, and `public` or `strict` to be chosen explicitly once Internet reachability is confirmed. `SUBCONVERTER_ALLOW_PUBLIC_UPLOAD` controls whether uploads are accepted, shown as `false` in the example. `SUBCONVERTER_RESOURCE_CONTROL` picks a concurrency mode: with the default Beast backend, `compat` uses a bounded synchronous path while `adaptive` and `force_max` use a cooperative asynchronous path. The `force_max` mode refuses to start unless the CPU, memory, PID and file descriptor envelope can be fully probed and the startup budget is valid. The comment also notes that the legacy fingerprint is deprecated and does not change capacity, and that all modes keep finite request deadlines. The defaults are conservative, but the permissive modes are one environment variable away.

Where a single unified pipeline still breaks

The long term goal is to make every client consume one template plus a subscription link, and the README says plainly that this is not yet achieved. Configuration structure, remote resource expression, protocol fields and template capability still differ between clients, so some scenarios still need per client configuration and handling. Closed source clients make this worse: the compatibility note says they must be verified for import and connectivity in their actual versions, and the release table is explicitly limited to the current formal release. Nodes that a target cannot express are filtered out for that target, which means the same input can produce a smaller configuration in one client than in another. A second limit is the upstream relationship. The maintainer tried to contribute improvements to the subconverter repository used daily but could not open pull requests or issues there, so this project stands on its own, and the README documents no rollback path for either side.

Three releases in four days and a floating image tag

The repository is not archived, and the last push was on 2026-10-19, four days after release v1.9.16. Two more releases landed just before it, v1.9.15 on 2026-10-13 and v1.9.14 on 2026-10-11, so the recent work is concentrated on the Mihomo path rather than spread across the whole client list. The upgrade picture for an operator is therefore simple but sharp: pull a new tag, redeploy, and expect the Mihomo related surface to have moved. The Compose example uses the floating `latest` tag, so two deployments of the same Compose file can run different binaries, and the build argument that resolves the Mihomo ref means a rebuild can also change behavior even at the same tag. Licensing is GPL-3.0, with the `LICENSE` file at the repository root, which carries source disclosure obligations when you distribute modified builds.

Editorial conclusion

Adopt SubConverter-Extended if you already maintain subscription links and want one template pipeline to feed Mihomo and the common iOS and desktop clients, and do not adopt it if you expected a node source, a rules repository or a turnkey public instance. Before deploying, verify the target format the client actually imports, confirm that a public instance is not required, and check the exposure of the published port 25500, since the Compose example binds it on all interfaces. If you self host, pin the Mihomo ref and the container image tag yourself, because the build follows a moving ref and the example ships the floating latest tag.

Frequently asked questions

Official sources

1. Aethersailor/SubConverter-Extended on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases