explaingit

cyfdecyf/cow

8,433GoAudience · generalComplexity · 3/5Setup · moderate

TLDR

A self-configuring HTTP proxy that automatically detects which websites are blocked in China and routes only those through a secondary proxy, leaving all other traffic to connect directly.

Mindmap

mindmap
  root((COW))
    What It Does
      Route blocked sites
      Auto-detect blocking
      Direct for others
    Proxy Backends
      SOCKS5
      Shadowsocks
      HTTP proxy
    Smart Routing
      Auto-retry via proxy
      PAC file generated
      Learning history
    Platforms
      macOS
      Linux and ARM
      Windows
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

Set up a proxy on a home computer in China that automatically routes blocked sites through a secondary proxy without slowing down unblocked browsing.

USE CASE 2

Configure COW with a Shadowsocks backend to bypass internet filtering with minimal manual list maintenance.

USE CASE 3

Generate a PAC file for your browser so it automatically chooses direct or proxy connections on a per-domain basis.

USE CASE 4

Run COW on a Linux ARM device as a shared network proxy for all devices on a home network.

Tech stack

Go

Getting it running

Difficulty · moderate Time to first run · 30min

Requires a working secondary proxy (SOCKS5, Shadowsocks, or HTTP) configured before COW can route blocked traffic.

In plain English

COW, which stands for "Climb Over the Wall", is an HTTP proxy server written in Go. Its primary purpose is to help users in China access websites that are blocked by the country's internet filtering system. The key design goal is automation: COW tries to detect which sites are blocked on its own and routes only those through an external proxy, leaving other traffic to connect directly. This avoids slowing down access to sites that do not need to go through a proxy. When COW encounters a site it has not seen before, it first attempts a direct connection. If that connection is reset or times out in ways that match known blocking behavior, COW automatically retries the request through a secondary proxy. It records which sites needed the proxy and which did not, and uses that history to skip the detection step on future visits to the same site. After two minutes it will quietly retry a direct connection to avoid locking a site into the proxy path when the block was temporary or misdetected. COW supports several types of secondary proxies: SOCKS5, HTTP proxies, Shadowsocks (a popular protocol for circumventing censorship), and other COW instances running on a remote server. You can configure multiple secondary proxies and COW will spread requests across them. The tool also generates a PAC file, which is a small script that browsers can use to route only certain domains through the proxy and connect to everything else directly, improving speed. Configuration is done through a plain text file. COW comes with built-in lists of sites known to be blocked and sites known to be accessible without a proxy in China, so most users do not need to maintain those lists manually. The program runs on macOS, Linux (including ARM devices), and Windows. The README is written in Chinese, with a link to a separate English README in the repository.

Copy-paste prompts

Prompt 1
How do I configure COW with a Shadowsocks proxy so blocked sites are automatically routed through Shadowsocks while everything else connects directly?
Prompt 2
Set up COW on macOS and configure my browser to use its generated PAC file for automatic proxy switching.
Prompt 3
Walk me through COW's configuration file format, what do I need to set to add a custom list of domains that should always go through the proxy?
Prompt 4
How does COW detect whether a site is blocked, and how can I view which sites it has learned to route through the proxy versus directly?
Open on GitHub → Explain another repo

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

Verify against the repo before relying on details.