Cloudflare WARP on a Linux VPS with warp-cli and wgcf

Cloudflare WARP gives your server a Cloudflare egress address, which is handy for reaching IPv6-only resources or changing the apparent outgoing IP. On a remote machine the classic trap is that the default WARP mode hijacks the routing table and cuts your SSH session. This guide shows two safe methods on a VPS Linux Infrawire: the official client in proxy mode, and wgcf with WireGuard and partial routing.

📋 Prerequisites

A VPS running Ubuntu 24.04 or Debian 12 with root SSH access (from your customer area you will find the VPS IP and the root password).
The public IP of your VPS noted down (VPS_IP).
A way to reach the VPS console in case a network change locks you out.
Packages curl, gpg and lsb-release installed.

📦 Install the official client

Add the Cloudflare repository and install the package:

Bash
1apt update && apt install -y curl gpg lsb-release
2curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | gpg --yes --dearmor --output /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg
3echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(lsb_release -cs) main" > /etc/apt/sources.list.d/cloudflare-client.list
4apt update && apt install -y cloudflare-warp
5systemctl enable --now warp-svc

🛡️ Proxy mode: keep SSH alive

In proxy mode WARP does not touch the routing table. It only opens a local SOCKS5 port that you use on demand. Set the mode before connecting, never the other way round.

Bash
1warp-cli --accept-tos registration new
2warp-cli mode proxy
3warp-cli proxy port 40000
4warp-cli connect
5warp-cli status

The proxy listens on 127.0.0.1:40000 only. Send a command through it:

Bash
1curl -x socks5h://127.0.0.1:40000 https://www.cloudflare.com/cdn-cgi/trace

The socks5h scheme matters: it makes the DNS resolution happen through the proxy as well. To stop, run warp-cli disconnect.

🔀 Alternative: wgcf and WireGuard

If you prefer a kernel WireGuard interface, wgcf creates a WARP account and generates a standard configuration. Download the wgcf release matching your architecture from the project's GitHub releases page, then:

Bash
1apt install -y wireguard-tools
2chmod +x wgcf_linux_amd64 && mv wgcf_linux_amd64 /usr/local/bin/wgcf
3cd /root && wgcf register && wgcf generate
4cp wgcf-profile.conf /etc/wireguard/wgcf.conf

Do not start it yet: the generated profile routes everything through the tunnel and would cut SSH.

✂️ Partial routing and IPv6 only

Edit /etc/wireguard/wgcf.conf. To send only IPv6 traffic through WARP and leave IPv4 (and your SSH session) untouched, restrict AllowedIPs, drop the DNS line and lower the MTU:

INI
1[Interface]
2MTU = 1280
3PostUp = ip rule add from VPS_IP lookup main
4PostDown = ip rule del from VPS_IP lookup main
5
6[Peer]
7AllowedIPs = ::/0
8Endpoint = engage.cloudflareclient.com:2408

Keep the keys and Address lines produced by wgcf. The ip rule pair makes sure replies from VPS_IP always use the main table, which protects incoming connections. If you only connect over IPv4, you can later replace ::/0 with 0.0.0.0/0, ::/0 to tunnel everything. Enable the interface:

Bash
1systemctl enable --now wg-quick@wgcf

✅ Verification

Check that WARP is active on the right path:

Bash
1curl -s https://www.cloudflare.com/cdn-cgi/trace | grep warp
2curl -6 -s https://www.cloudflare.com/cdn-cgi/trace | grep -E 'ip=|warp='
3wg show wgcf

warp=on on the IPv6 request, together with a recent handshake in wg show, means the tunnel works. The plain IPv4 request should still show warp=off.

🛠️ Troubleshooting

SSH access lost right after connecting. WARP was in full-tunnel mode. Open the VPS console and run warp-cli disconnect (or systemctl stop wg-quick@wgcf), then switch to warp-cli mode proxy before reconnecting. If you reach the server over IPv6, do not use ::/0 in AllowedIPs.

DNS stops resolving. wg-quick rewrites the resolver when a DNS line exists. Remove that line from the profile, or use the socks5h proxy so resolution happens on the Cloudflare side.

Large pages hang or TLS stalls. This is almost always an MTU problem. Keep MTU = 1280 in the WireGuard profile and test with ping -M do -s 1200 1.1.1.1.

🎉 Your VPS can now use Cloudflare WARP on demand without ever cutting your SSH session.