explaingit

vvbbnn00/warp-clash-api

8,853PythonAudience · generalComplexity · 3/5Setup · moderate

TLDR

A self-hosted server that converts Cloudflare's free WARP+ VPN into a subscription URL for popular proxy apps like Clash, Surge, and Shadowrocket. Automatically refreshes WARP+ traffic allowance and filters servers by speed and reliability.

Mindmap

mindmap
  root((warp-clash-api))
    What it does
      WARP to subscription URL
      Auto traffic refresh
      Server speed filtering
    Supported apps
      Clash
      Surge
      Shadowrocket
    Setup
      Docker Compose
      Environment variables
      Optional secret key
    Audience
      VPN power users
      Self-hosters
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Generate a subscription URL that lets Clash or Surge connect through Cloudflare's WARP+ network without manual configuration.

USE CASE 2

Automatically keep your WARP+ traffic topped up by running the server continuously in the background.

USE CASE 3

Filter available WARP server addresses by latency and packet loss so your VPN app always connects to the fastest node.

Tech stack

PythonDocker

Getting it running

Difficulty · moderate Time to first run · 30min

Requires an always-on server or machine to keep running, the primary README is in Chinese.

In plain English

Cloudflare WARP is a free internet service that routes your traffic through Cloudflare's network, and the paid WARP+ tier provides access to faster nodes. WARP-Clash-API is a self-hosted tool that lets you use WARP+ through popular VPN client apps like Clash, Surge, and Shadowrocket by generating a subscription link those apps can read. The README is primarily in Chinese, though the project description includes an English summary. The tool runs as a small server on your own machine or a remote server. Once running, it produces a subscription URL that you paste into a VPN client app. That app then connects using the WARP+ configuration the server provides. One of the tool's features is automatically refreshing WARP+ traffic allowance by periodically calling Cloudflare's systems, which the README says can add 1 GB of traffic every 18 seconds. Another feature is IP selection: since WARP uses many different server addresses, the tool tests them for speed and packet loss and filters out slow or unreliable ones. You can also run the IP selection process manually at any time. The configuration is done through environment variables in a file you create locally. Options include how often to refresh traffic, what delay threshold to use when filtering server addresses, whether to protect the subscription URL with a secret key, and whether to share the subscription publicly. Deployment is done via Docker Compose, which means you start the whole service with a single command. An optional configuration file handles any settings you want to change from the defaults. The README notes this is a non-commercial project intended for learning and exchange, not for illegal use. The project builds on several other open-source tools for proxy pooling and WireGuard configuration, which are credited in the README.

Copy-paste prompts

Prompt 1
I'm setting up warp-clash-api with Docker Compose. Show me what environment variables to put in my .env file to set the traffic refresh interval and the latency threshold for filtering servers.
Prompt 2
How do I get the subscription URL from my running warp-clash-api instance and add it to Clash on my phone?
Prompt 3
How do I add a secret key to my warp-clash-api deployment so the subscription URL is only accessible to me?
Prompt 4
My warp-clash-api container is running but the subscription URL returns an error. What steps should I take to debug the connection to Cloudflare's WARP service?
Open on GitHub → Explain another repo

← vvbbnn00 on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.