Run Mesh on Linux

A Mesh node is a Linux server that runs the Cloudflare One Client (cloudflare-warp package) in headless mode. The node joins your Mesh with its own Mesh IP. It can also route traffic to a private subnet behind it.

Use this guide to install a Mesh node directly on a Linux host. To run a Mesh node without installing packages on the host, refer to Run Mesh in Docker / Kubernetes.

Supported distributions

Mesh nodes support the following Linux distributions and hardware:

OS version	RHEL 9 ¹, RHEL 10, Debian 12, Debian 13, Fedora 43, Fedora 44, Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, Ubuntu 26.04 LTS
Processor	AMD64 / x86-64 or ARM64 / AArch64
vCPU	3 minimum, 4 recommended
RAM without a desktop	1 GB minimum, 2 GB recommended (for example, Ubuntu Server)
RAM with a desktop	4 GB minimum, 8 GB recommended (for example, Ubuntu GNOME)
Disk space	250 MiB minimum, 500 MiB recommended
Network interface type	Wi-Fi or LAN
MTU	1381 bytes recommended ²

On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) ↗︎ repository (sudo dnf install epel-release) before installing cloudflare-warp. EPEL provides dependencies required by the client UI. ↩
Minimum 1281 bytes with Path MTU Discovery ↩

Cloudflare One Client version 2026.6.822.0 and later support Cloudflare Mesh on RHEL 9 and RHEL 10. For support dates, refer to the support lifecycle.

Prerequisites

Before you install the client, create a Mesh node and get its token.

In the Cloudflare dashboard, go to Networking > Mesh.
Go to Mesh ↗
Select Add participant > Add node.
Enter a name for your node (for example, web-server or staging-db).
Select Create node.
Select Linux. The dashboard displays the install and registration commands for the node. The registration command includes the node token.

With an API token that has either Cloudflare One Connectors Write or Cloudflare One Connector: WARP Write permission, create a node and retrieve its connector token:

set -euo pipefail

NODE_RESPONSE=$(
	curl --fail-with-body --silent --show-error \
		"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/warp_connector" \
		--request POST \
		--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
		--header "Content-Type: application/json" \
		--data '{"name":"web-server"}'
)

jq -e '.success == true and (.result.id | type == "string")' \
	<<< "$NODE_RESPONSE" > /dev/null
NODE_ID=$(jq -r '.result.id' <<< "$NODE_RESPONSE")

TOKEN_RESPONSE=$(
	curl --fail-with-body --silent --show-error \
		"https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/warp_connector/$NODE_ID/token" \
		--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
)

MESH_NODE_TOKEN=$(jq -er \
	'select(.success == true) | .result | select(type == "string" and length > 0)' \
	<<< "$TOKEN_RESPONSE")

Install jq, then set ACCOUNT_ID and CLOUDFLARE_API_TOKEN before running the commands. The commands stop on an HTTP or API error. Do not continue until they return zero and set NODE_ID and MESH_NODE_TOKEN. If token retrieval fails after node creation, retry only the token request with the existing NODE_ID. Do not rerun the node creation request.

If this is your first Mesh node, configure the required account settings. The dashboard wizard configures them for new accounts.

1. Install the client

Install the cloudflare-warp package from the Cloudflare package repository. Choose the section for your distribution.

Debian and Ubuntu

Add the Cloudflare package signing key:

curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg

apt uses this key to verify that packages come from Cloudflare.

Add the Cloudflare repository:

echo "deb [signed-by=/usr/share/keyrings/cloudflare-warp-archive-keyring.gpg] https://pkg.cloudflareclient.com/ $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/cloudflare-client.list

The $VERSION_CODENAME variable resolves to your release codename (for example, noble or trixie). This selects the package build for your release.

Install the package:

sudo apt-get update && sudo apt-get install -y cloudflare-warp

RHEL

Enable the Extra Packages for Enterprise Linux (EPEL) ↗︎ repository:
```
sudo dnf install -y epel-release
```
EPEL provides dependencies that the Cloudflare One Client needs on RHEL 9 and later.
Add the Cloudflare repository:
```
curl -fsSL https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo
```
The repository file points yum to the package build for your RHEL version and to the Cloudflare signing key.
Install the package:
```
sudo yum install -y cloudflare-warp
```

2. Register and connect the node

To register the host as your Mesh node and connect it, run the following command. Replace <MESH_NODE_TOKEN> with the node token from the prerequisites.

sudo warp-cli --accept-tos connector new <MESH_NODE_TOKEN> && sudo warp-cli --accept-tos connect

This command runs two warp-cli subcommands:

Command	Purpose
`connector new`	Registers the host as the Mesh node that the token identifies. It does not enroll a user device.
`connect`	Connects the node to Cloudflare. The client reconnects automatically after reboots.
`--accept-tos` flag	Accepts the Cloudflare One Client terms of service without an interactive prompt.

If you use the same token on more than one host, each host joins as a replica of the same node. For more information, refer to High availability.

3. Verify the node

On the node, check the connection status:
```
warp-cli status
```
```
Status update: Connected
```
In the Cloudflare dashboard, go to Networking > Mesh. Confirm that the node shows as Online, and note its Mesh IP.
From an enrolled client device, test a service on the node. For example, to test SSH:
```
nc -vz <MESH_IP> 22
```
A Connected status does not prove that peers can reach the node. Test the application protocol you intend to use.

Turn on IP forwarding for routes

IP forwarding lets the node pass packets between the Mesh and its local network. Turn it on only if the node will advertise CIDR routes to make a subnet behind it reachable. You do not need it to reach the node by its own Mesh IP. You can turn it on at any time, before or after you connect the node.

To turn on forwarding and keep it across reboots, run:

printf 'net.ipv4.ip_forward = 1\nnet.ipv6.conf.all.forwarding = 1\nnet.ipv6.conf.all.accept_ra = 2\n' | sudo tee /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf &&
sudo sysctl --system

This command writes three kernel settings to a file in /etc/sysctl.d/, then reloads all settings:

Setting	Purpose
`net.ipv4.ip_forward = 1`	Forwards IPv4 packets between interfaces.
`net.ipv6.conf.all.forwarding = 1`	Forwards IPv6 packets between interfaces.
`net.ipv6.conf.all.accept_ra = 2`	Keeps accepting IPv6 router advertisements after forwarding is on. Without it, the host can lose IPv6 routes.

The 99-zzz- prefix makes the file load last, so other files in /etc/sysctl.d/ cannot override it.

If the host runs in a cloud VPC, you may also need provider settings, such as turning off source/destination checks on AWS. For more information, refer to Cloud VPC deployments.

Manage the node

Check status and reconnect

Command	Purpose
`warp-cli status`	Shows the current connection status.
`warp-cli connect`	Reconnects the node.
`warp-cli disconnect`	Disconnects the node without deregistering.
`warp-cli --version`	Shows the installed client version.

Update the client

Updating the client briefly disconnects the node. If you run high availability replicas, traffic fails over to a standby.

sudo apt-get update && sudo apt-get install --only-upgrade -y cloudflare-warp

sudo yum update -y cloudflare-warp

After the update, run warp-cli status to confirm the node reconnected.

View logs

The client runs as the warp-svc systemd service. To view recent service logs, run:

sudo journalctl -u warp-svc --since "15 minutes ago"

To collect a full diagnostic bundle for Cloudflare support, run warp-diag. For more information, refer to Diagnostic logs.

Remove the node

On the host, delete the registration:
```
sudo warp-cli registration delete
```

Uninstall the package:

sudo apt-get remove -y cloudflare-warp

sudo yum remove -y cloudflare-warp

(Optional) If you turned on IP forwarding for this node, remove the setting:

sudo rm /etc/sysctl.d/99-zzz-cloudflare-warp-connector.conf && sudo sysctl --system

In the Cloudflare dashboard, go to Networking > Mesh and delete the node. Skip this step if other replicas still use the node.

Troubleshooting

The node shows as Offline

Run warp-cli status on the node. If the status is not Connected:

Run warp-cli connect.
Confirm that your firewall allows the Cloudflare One Client ports and IPs.
Review the service logs.

The node registers as a regular client device

Confirm that you ran warp-cli connector new with a Mesh node token. If the host was enrolled as a user device before, run sudo warp-cli registration delete, then register it again with the node token.

Routed subnets are not reachable

Confirm that IP forwarding is on:

sysctl net.ipv4.ip_forward net.ipv6.conf.all.forwarding

Both values must be 1. Then confirm that the destination network can route return traffic to the Mesh IP range (100.96.0.0/12). For more information, refer to Return traffic routing.

Package install fails on RHEL

Run yum repolist and confirm that EPEL is enabled. For more information, refer to the EPEL getting started guide ↗︎.

For general client issues, refer to Troubleshoot the Cloudflare One Client.

Next steps

Add routes — Make subnets behind the node reachable from any participant on your Mesh.
Enable high availability — Run multiple replicas for production resilience.
Tips and best practices — Cloud VPC configuration, DNS servers, and running alongside Cloudflare Tunnel.