☁️ Cloudflare Warp

Table of Contents

• Motivation
• Features
• Installation
  • From GitHub Releases
  • Building from Source
  • Docker
• Usage
  • Command-line Flags
  • Register a new account
  • Add a license key
  • Generate WireGuard configuration
  • Check device status
  • Verify Warp/Warp+ works
  • Run the WARP proxy
  • Scan for the best WARP IP
• Configuration
• Performance
• Community
• Credits
• Notice of Non-Affiliation and Disclaimer
• Star History

💡 Motivation

Many VPN clients, including official WireGuard and Cloudflare WARP clients, often require kernel-level access or route all system traffic through the tunnel by default. cloudflare-warp was created to provide a more flexible, lightweight, and cross-platform alternative.

✨ Features

• Cross-Platform: Runs on Linux/macOS/Windows/FreeBSD/OpenBSD with platform-specific optimizations.
• User-Space Networking: Implements a user-space networking stack to handle traffic, avoiding the need for kernel-level privileges.
• Proxy Support: Includes support for HTTP and Socks5 proxies for secure and private browsing.
• Full SOCKS Support: Implements Socks5 with TCP (CONNECT) and UDP (ASSOCIATE) support.
• DPI Evasion: Utilizes techniques by AmneziaWG and uTLS helping to confuse Deep Packet Inspection (DPI) systems.
• IP Scanner: Built-in scanner to find the best Cloudflare WARP IP addresses with optimal RTT.

🚀 Installation

There are multiple ways to install cloudflare-warp.

From GitHub Releases

You can download pre-compiled binaries for various operating systems and architectures from the releases page.

Building from Source

Since the tool is written in Go, it should be rather trivial.

1. Ensure that you have Go installed on your system. You can download it from here. At least Go 1.24.4 is required (as per go.mod).

2. Clone this repository and switch to the project's root directory:

   git clone https://github.com/shahradelahi/cloudflare-warp.git
   cd cloudflare-warp

3. Build the project using the Makefile:

   make cloudflare-warp

   The compiled binary will be located in the build/ directory.

If you would rather cross compile, set the GOOS and GOARCH environment variables accordingly. For example, to build for Windows on a Linux system:

GOOS=windows GOARCH=amd64 CGO_ENABLED=0 make cloudflare-warp

Docker

You can also run cloudflare-warp using Docker. A Dockerfile is provided in the repository.

To build the image, run:

docker build -t cloudflare-warp .

Example usage (spawns a SOCKS proxy and exposes it on port 1080):

docker run -d \
  --name cloudflare-warp \
  -v ./warp-data:/var/lib/cloudflare-warp \
  -p 1080:1080 \
  --restart=unless-stopped \
  cloudflare-warp --socks-addr 0.0.0.0:1080

Note: Inside the container, the proxy must bind to 0.0.0.0 to be accessible from outside.

⚙️ Usage

Run warp in a terminal without any arguments to display the help screen. All commands and parameters are documented.

./warp --help

Command-line Flags

Run warp <command> --help for detailed information on each command's flags.

Register a new account

This command creates a fresh WARP account and saves the identity files.

warp generate

Add a license key

If you have an existing Warp+ subscription, you can bind the account generated by this tool to your phone's account, sharing its Warp+ status. Please note that there is a limit of 5 maximum devices linked at a time. You can remove linked devices from the 1.1.1.1 app on your phone.

Caution

Only subscriptions purchased directly from the official 1.1.1.1 app are supported. Keys obtained by any other means, including referrals, will not work and will not be supported.

First, get your Warp+ account license key. To view it on Android:

1. Open the 1.1.1.1 app
2. Click on the hamburger menu button in the top-right corner
3. Navigate to: Account > Key

Now, use the command below to update the account's name and license:

warp update --name "My Warp Device" --license "YOUR_LICENSE_KEY"

Generate WireGuard configuration

This command generates and prints the WireGuard configuration based on your WARP identity.

warp generate

Check device status

Run the following command in a terminal to check the status of your current Cloudflare Warp device:

warp status

Verify Warp/Warp+ works

After connecting to the WARP proxy (see Run the WARP proxy section), you can verify that Warp/Warp+ is working by checking your IP address or visiting a Cloudflare trace page.

Using curl:

curl -x socks5://127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace
# Or for HTTP proxy:
curl -x http://127.0.0.1:8118 https://cloudflare.com/cdn-cgi/trace

Look for warp=on or warp=plus in the output.

Using a web browser:

Open your browser and navigate to https://cloudflare.com/cdn-cgi/trace/. Look for warp=on or warp=plus on the page.

Run the WARP proxy

This command starts the proxy server and establishes a connection to the Cloudflare network. You can configure the proxy to use Socks5 or HTTP, specify WARP endpoints, and enable features like WARP+ connections.

Example: Run with a SOCKS5 proxy on port 1080 and an HTTP proxy on port 8118.

warp run --socks-addr 127.0.0.1:1080 --http-addr 127.0.0.1:8118

Example: Run with IP scanning enabled to find the best endpoint.

warp run --scan --4 --rtt 500ms

This will scan for IPv4 endpoints with a maximum RTT of 500ms.

Scan for the best WARP IP

This command scans for the best Cloudflare WARP IP addresses by testing a list of known CIDRs. It measures the Round-Trip Time (RTT) and displays a list of the fastest available endpoints. This is useful for finding optimal endpoints to use with the run command for better performance.

Example: Scan for IPv4 endpoints with a maximum RTT of 1000ms.

warp scanner --ipv4 --rtt 1000ms

📁 Configuration

For simplicity, the tool stores its identity and configuration in JSON files within a data directory. By default, this is ~/.cloudflare-warp on Linux/macOS or a platform-specific equivalent. You can specify a different data directory using the --data-dir flag.

The primary configuration files are:

• reg.json: Contains your WARP registration ID, token, and private key. Confidential.
• conf.json: Contains your WARP account details (license, quota, etc.) and the WARP configuration (peers, interface addresses).

These files are automatically managed by the warp commands (e.g., generate, update).

⚡ Performance

The project is in active development, and performance is a continuous focus. While the official client leverages highly optimized implementations, cloudflare-warp aims to provide a robust user-space solution. Performance can vary based on network conditions and system resources.

💬 Community

Welcome and feel free to ask any questions at Discussions.

🙏 Credits

• Cloudflare WARP: For the WARP service this project connects to.
• wiresocks - A user-space WireGuard client that exposes SOCKS and HTTP proxies, which this project builds upon.
• amneziawg-go - Go Implementation of Amnezia WireGuard.
• utls - A Go library for custom TLS client hellos, used for DPI evasion.
• cobra - Powerful CLI library for Go.
• And many other open-source projects and contributors that make this possible.

⚠️ Notice of Non-Affiliation and Disclaimer

We are not affiliated, associated, authorized, endorsed by, or in any way officially connected with Cloudflare, or any of its subsidiaries or its affiliates. The official Cloudflare website can be found at https://www.cloudflare.com/.

The names Cloudflare Warp and Cloudflare as well as related names, marks, emblems and images are registered trademarks of their respective owners.

This tool is an independent open-source project and is provided "as is" without any guarantees. Use at your own risk. We are not responsible for any consequences that may arise from using this tool, including but not limited to system damage, network issues, or legal implications.

License

MIT © Shahrad Elahi and contributors.

⭐ Star History