--- description: Connect services and devices with post-quantum encrypted private networking through Cloudflare. title: Cloudflare Mesh image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Cloudflare Mesh Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Connect services and devices with post-quantum encrypted private networking through Cloudflare. Cloudflare Mesh gives every enrolled server, laptop, and phone a private Mesh IP. Participants can communicate by IP over TCP, UDP, or ICMP, including device-to-device connections that do not require customer-managed networking infrastructure. Mesh nodes run the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) in headless mode on Linux. They can also advertise routes to make private subnets and hostnames reachable from other Mesh participants. ![The Mesh network map in the Cloudflare dashboard showing nodes and devices connected through Cloudflare](https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=2070,height=875,format=webp/_astro/mesh-network-map.CED6jNHK.gif) Note Cloudflare Mesh was previously known as WARP Connector and peer-to-peer connectivity. Existing WARP Connectors are now called Mesh nodes. Existing deployments continue to work without migration. For details about how Mesh works, protocol requirements, and Mesh IP assignment, refer to [Concepts](https://developers.cloudflare.com/mesh/concepts/). ## Use cases - Connect enrolled devices to each other by private IP. - Provide bidirectional connectivity between servers, cloud networks, and sites. - Route traffic to devices that cannot run the Cloudflare One Client. - Preserve long-lived TCP connections for databases, replication, ERP systems, and remote administration. ## Get started ### [Set up Cloudflare Mesh](https://developers.cloudflare.com/mesh/get-started/) Configure your account and connect your first participant. ### [Understand Mesh](https://developers.cloudflare.com/mesh/concepts/) Learn how participants, Mesh IPs, routing, and policies work. ### [Explore features](https://developers.cloudflare.com/mesh/features/) Configure routes and high availability for Mesh nodes. ### [Follow a guide](https://developers.cloudflare.com/mesh/guides/) Connect client devices or deploy Mesh in containers. ## Mesh vs. Cloudflare Tunnel Use Mesh when participants need bidirectional private IP connectivity or when a workload requires stable, long-lived connections. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) when you want to publish specific applications, hostnames, or IP routes through an outbound-only connector. For a detailed comparison, refer to [How Cloudflare Mesh works](https://developers.cloudflare.com/mesh/concepts/#mesh-vs-tunnel). Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"WebPage","@id":"https://developers.cloudflare.com/mesh/#page","headline":"Cloudflare Mesh - Private networking · Cloudflare Docs","description":"Connect services and devices with post-quantum encrypted private networking through Cloudflare.","url":"https://developers.cloudflare.com/mesh/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Set up Cloudflare Mesh and connect your first server, laptop, or phone to your private network. title: Get started image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Get started Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/get-started/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Set up Cloudflare Mesh so your devices and servers can reach each other by private IP. ## Prerequisites - A [Cloudflare account ↗](https://dash.cloudflare.com/sign-up) - A [Zero Trust organization](https://developers.cloudflare.com/cloudflare-one/setup/#2-create-a-zero-trust-organization) with an active subscription, including the Free plan - A laptop or phone to connect as a client device - (Optional) A Linux server to deploy a Mesh node
Linux server requirements | **OS version** | RHEL 9 1, 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 | | **HD space** | 75 MB | | **Memory** | 35 MB | | **Network interface type** | Wi-Fi or LAN | | **MTU** | 1381 bytes recommended 2 | ## Footnotes 1. 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. ↩ 2. Minimum 1281 bytes with Path MTU Discovery ↩
Mesh nodes are optional Client-to-client connectivity works without any Mesh nodes. Two enrolled laptops can reach each other directly by Mesh IP. Mesh nodes are for running the client in headless mode on a server — either to make that server reachable by its Mesh IP, or to [route traffic to a private subnet](https://developers.cloudflare.com/mesh/features/routes/) behind it. Configure the [required account settings](#required-account-settings) before connecting participants. You can use the dashboard wizard, APIs, or Terraform. Cloudflare Mesh requires that the Mesh node's [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) is configured to use [MASQUE](https://developers.cloudflare.com/mesh/concepts/#protocol-requirement). Hostname routes, IPv6 CIDR routes, and high availability do not work if the device profile uses WireGuard instead. ## Choose a participant type Choose an enrollment method based on what you want to connect: | Goal | Participant type | Enrollment method | Browser required | | --- | --- | --- | --- | | Run a service or route a subnet from Linux | [Mesh node](#1-configure-mesh) | Connector token | No | | Connect an unattended Windows, macOS, or Linux device | [Headless client device](https://developers.cloudflare.com/mesh/guides/connect-client-devices/#headless-windows-macos-and-linux-devices) | Service token and managed deployment parameters | No | | Connect a user device with identity | [Client device](#2-connect-a-client-device) | Interactive identity provider enrollment | Yes | ## 1. Configure Mesh Choose the dashboard wizard or API and Terraform resources. The setup wizard [configures your account for Mesh networking](#required-account-settings) and optionally guides you through creating a Mesh node. This is a one-time setup. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select **Add a node**. 3. Enter a name for your node (for example, `web-server` or `staging-db`). 4. Select **Create node**. 5. (Optional) If you have a Linux server, run the install commands shown in the dashboard to bring the node online. If you do not have a server ready, select **I'll connect later** — you can install the node at any time from the node detail page.
Installation commands IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise CIDR routes, enable persistent forwarding before connecting it: ```sh 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 ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && 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 && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing cloudflare-warp. EPEL provides dependencies required by the Cloudflare One Client UI: ```sh sudo dnf install -y epel-release ``` Then install the package: ```sh curl -fsSl https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo yum install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ```
6. Select **View node details** to complete the setup wizard. If you installed the node, it should appear as **Online** on the Mesh overview page along with its assigned **Mesh IP**. If the node does not come online, refer to [Troubleshooting](#troubleshooting). The dashboard wizard is not required. After account bootstrap, APIs and Terraform can automate the supported Mesh resources. You will need your [account ID](https://developers.cloudflare.com/fundamentals/account/find-account-and-zone-ids/), Zero Trust team name, `jq`, and an [API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) with permissions for the resources you configure. Initial API token You must create the initial API token in the dashboard. An authorized token can [create subsequent user-owned or account-owned tokens through the API](https://developers.cloudflare.com/fundamentals/api/how-to/create-via-api/). Before continuing, configure every item in [Required account settings](#required-account-settings). The examples in this section configure the Mesh node device profile, node, and connector token. You must configure device enrollment and global settings separately. **Allow all Cloudflare One traffic to reach enrolled devices** and the ICMP Gateway proxy require dashboard configuration. Before connecting a node, create a safe Include-mode profile. This request requires the `Zero Trust Write` permission. It matches Mesh nodes, uses MASQUE in Traffic and DNS mode, and routes only the Mesh IP range through Cloudflare: ```bash set -euo pipefail PROFILE_RESPONSE=$( curl --fail-with-body --silent --show-error \ "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/devices/policy" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data "$(jq -n \ --arg match "identity.email == \"warp_connector@$TEAM_NAME.cloudflareaccess.com\"" \ '{ name: "Cloudflare Mesh nodes", description: "Route Mesh IP traffic through Cloudflare", enabled: true, precedence: 100, match: $match, service_mode_v2: {mode: "warp"}, tunnel_protocol: "masque", include: [{address: "100.96.0.0/12", description: "Cloudflare Mesh IPs"}] }')" ) jq -e '.success == true and (.result.id | type == "string")' \ <<< "$PROFILE_RESPONSE" > /dev/null PROFILE_ID=$(jq -r '.result.id' <<< "$PROFILE_RESPONSE") ``` Set `ACCOUNT_ID`, `TEAM_NAME`, and `CLOUDFLARE_API_TOKEN` in the shell before running the command. Use an unused `precedence` value that places this profile before broader profiles. Do not add an `exclude` field. A device profile cannot contain both `include` and `exclude`. The API response uses the standard `success`, `errors`, `messages`, and `result` fields. A non-2xx response causes `curl` to fail. A response with `success: false` or without `result.id` causes `jq` to fail. Do not continue until the command returns zero and `PROFILE_ID` is set. The following requests require an API token with either `Cloudflare One Connectors Write` or `Cloudflare One Connector: WARP Write` permission. To create a Mesh node and retrieve its connector token: ```bash 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") ``` 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. Install the node and replace `` with the value of `MESH_NODE_TOKEN`: IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/), enable persistent forwarding before connecting it: ```sh 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 ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && 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 && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing `cloudflare-warp`. EPEL provides dependencies required by the Cloudflare One Client UI: ```sh sudo dnf install -y epel-release ``` Then install the package: ```sh curl -fsSl https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo yum install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` You can also manage nodes with the [`cloudflare_zero_trust_tunnel_warp_connector` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_warp_connector) resource. Use [`cloudflare_zero_trust_tunnel_warp_connector_config` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_warp_connector_config) to manage node configuration. ## 2. Connect a client device Connect a laptop or phone to your Mesh network: ### Windows, macOS, and Linux To enroll your device using the client GUI: 1. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Client. 2. Launch the Cloudflare One Client. 3. On the **What would you like to use the Cloudflare One Client for?** screen, select **Zero Trust security**. 4. Enter your team name. 5. Complete the authentication steps required by your organization. Once authenticated, you will see a Success page and a dialog prompting you to open the Cloudflare One Client. 6. Select **Open the Cloudflare One Client** to complete the registration. 7. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Client. 8. Launch the Cloudflare One Client. 9. Select the Cloudflare logo in the menu bar. 10. Select the gear icon. 11. Go to **Preferences** > **Account**. 12. Select **Login with Cloudflare Zero Trust**. 13. Enter your team name. 14. Complete the authentication steps required by your organization. Once authenticated, you will see a Success page and a dialog prompting you to open the Cloudflare One Client. 15. Select **Open Cloudflare WARP.app** to complete the registration. ### iOS and Android 1. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Agent app. 2. Launch the Cloudflare One Agent app. 3. Select **Next**. 4. Review the privacy policy and select **Accept**. 5. Enter your team name. 6. Complete the authentication steps required by your organization. 7. After authenticating, select **Install VPN Profile**. 8. In the **Connection request** popup window, select **OK**. 9. If you did not enable [auto-connect ↗](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#auto-connect), manually turn on the switch to **Connected**. Once you see a **Connected** status, your device is on the mesh and receives its own Mesh IP. ## 3. Test connectivity From a Windows, macOS, or Linux client device, verify TCP connectivity to a Mesh node or another enrolled device. For example, test SSH: ```sh nc -vz 22 ``` ```powershell Test-NetConnection -Port 22 ``` Replace `` with the Mesh IP shown on the Mesh overview page. Replace port `22` with the port used by your service. You can test HTTP services from a mobile browser. A connected client or healthy connector status does not verify peer connectivity. Verify the application protocol you intend to use. If you turned on the ICMP Gateway proxy, you can also run `ping ` as a diagnostic check. ## Logs Traffic from Mesh nodes appears in [Gateway activity logs](https://developers.cloudflare.com/cloudflare-one/insights/logs/dashboard-logs/gateway-logs/) with the identity `warp_connector@.cloudflareaccess.com`. Client device traffic appears in Gateway activity logs under the enrolled user's identity. ## Required account settings The dashboard wizard configures the following Cloudflare One settings automatically for new deployments. Non-wizard deployments must configure the same settings: | Setting | What it does | | --- | --- | | [Device enrollment policy](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/device-enrollment/) | Allows devices to enroll into your Cloudflare One account using email-based [one-time PIN](https://developers.cloudflare.com/cloudflare-one/integrations/identity-providers/one-time-pin/). Only created if you do not already have an existing device enrollment policy in your account. | | [Device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) | Creates a profile configured with [Split Tunnels](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) in **Include mode**, so only Mesh traffic routes through Cloudflare. This prevents disrupting existing network connectivity on your server. Only created if you do not already have an active Mesh node (formerly WARP Connector) in your account. | | [Allow all Cloudflare One traffic to reach enrolled devices](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#allow-all-cloudflare-one-traffic-to-reach-enrolled-devices) and [Assign a unique IP address to each device](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#assign-a-unique-ip-address-to-each-device) | Enables device-to-device connectivity for Mesh networking. | | [Gateway proxy](https://developers.cloudflare.com/cloudflare-one/traffic-policies/proxy/) | Enables TCP and UDP proxying for Mesh services. ICMP proxying is optional and supports diagnostics such as `ping` and `traceroute`. | For automated deployments, the device profile documentation includes API and Terraform examples. Set `service_mode_v2 = { mode = "warp" }`, replace the generic example's `wireguard` protocol with `tunnel_protocol = "masque"`, and configure Split Tunnels to route `100.96.0.0/12` through Cloudflare. Match Mesh nodes with `identity.email == "warp_connector@.cloudflareaccess.com"`, and place this profile before broader profiles. The device enrollment documentation includes the Terraform enrollment-policy flow. ### Automated settings The [`cloudflare_zero_trust_device_settings` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_settings) resource supports unique device IPs and the TCP and UDP Gateway proxies: ```tf resource "cloudflare_zero_trust_device_settings" "mesh" { account_id = var.cloudflare_account_id use_zt_virtual_ip = true gateway_proxy_enabled = true gateway_udp_proxy_enabled = true } ``` ### Human-only settings The Terraform resource does not configure **Allow all Cloudflare One traffic to reach enrolled devices** or the ICMP Gateway proxy. Before connecting participants, turn on enrolled-device reachability in the dashboard. Turn on ICMP only if you require `ping`, `traceroute`, or another ICMP-based workflow. ### Existing Cloudflare One accounts If your account already has a Cloudflare One deployment, the setup wizard will not overwrite your existing configuration. Verify the following settings are enabled for Mesh to work: - **Device enrollment** — At least one [enrollment rule](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/device-enrollment/) must exist so that devices and nodes can register with your account. - **Device profile for Mesh nodes** — Your Mesh nodes need a [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) that routes the Mesh IP range ( `100.96.0.0/12`) through Cloudflare. In Include mode, add the Mesh range. In Exclude mode, verify that no custom or legacy entry contains the Mesh range. - **Mesh connectivity** — In your device profile settings, enable [Allow all Cloudflare One traffic to reach enrolled devices](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#allow-all-cloudflare-one-traffic-to-reach-enrolled-devices). - **Unique device IPs** — Enable [Assign a unique IP address to each device](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#assign-a-unique-ip-address-to-each-device) so that each participant gets a routable Mesh IP. - **Client mode** — Mesh nodes must run in [Traffic and DNS mode](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/modes/). DNS-only or proxy-only modes are not supported. - **Traffic proxying** — Turn on the [Gateway proxy](https://developers.cloudflare.com/cloudflare-one/traffic-policies/proxy/) for the protocols you use. TCP and UDP carry Mesh services. ICMP supports diagnostic tools such as `ping` and `traceroute`. ## Troubleshooting - **Node shows as Offline** — On the server, run `warp-cli status`. If the output does not show `Status update: Connected`: - Run `warp-cli connect`. - If your private network uses a firewall to restrict Internet traffic, ensure that it allows the [WARP ports and IPs](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/firewall/). - Review your [WARP daemon logs](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/troubleshooting/diagnostic-logs/) for information about why the connection is failing. - **Client device cannot reach Mesh IPs** — Verify that your Split Tunnel configuration routes the Mesh IP range ( `100.96.0.0/12`) through Cloudflare. For details, refer to [Connect client devices](https://developers.cloudflare.com/mesh/guides/connect-client-devices/). - **Windows firewall blocks Mesh traffic** — Windows Firewall blocks inbound traffic from `100.96.0.0/12` by default. Add a firewall rule that allows incoming requests from this range for your desired protocols and ports. For general client issues, refer to [Troubleshoot the Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/troubleshooting/). ## Next steps - [**Connect client devices**](https://developers.cloudflare.com/mesh/guides/connect-client-devices/) — Platform-specific installation details, Split Tunnel configuration, and firewall considerations. - [**Run in Docker / Kubernetes**](https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/) — Deploy a Mesh node as a Docker container for Docker Compose, Kubernetes, and CI/CD pipelines. - [**Add routes**](https://developers.cloudflare.com/mesh/features/routes/) — Make an entire subnet behind your node reachable (databases, printers, other servers). - [**Enable high availability**](https://developers.cloudflare.com/mesh/features/high-availability/) — Run multiple replicas for production resilience. - [**Tips and best practices**](https://developers.cloudflare.com/mesh/best-practices/) — Cloud VPC configuration, updating the client, running alongside cloudflared. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/get-started/#page","headline":"Get started with Cloudflare Mesh · Cloudflare Docs","description":"Set up Cloudflare Mesh and connect your first server, laptop, or phone to your private network.","url":"https://developers.cloudflare.com/mesh/get-started/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Learn how Cloudflare Mesh connects participants, assigns private IPs, routes traffic, and differs from Cloudflare Tunnel. title: How Cloudflare Mesh works image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # How Cloudflare Mesh works Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/concepts/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Cloudflare Mesh connects your services and devices with post-quantum encrypted networking. Route traffic privately between servers, laptops, and phones without VPNs or bastion hosts. Every enrolled device and node receives a private IP address (Mesh IP) and can reach any other participant by IP over TCP, UDP, or ICMP, with traffic routed through Cloudflare's network. Mesh nodes are Linux servers running the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) (`warp-cli`) in headless mode. Client devices are laptops and phones running the same client with a UI. ![The Mesh network map in the Cloudflare dashboard showing nodes and devices connected through Cloudflare](https://developers.cloudflare.com/cdn-cgi/image/onerror=redirect,width=2070,height=875,format=webp/_astro/mesh-network-map.CED6jNHK.gif) Note Cloudflare Mesh was previously known as WARP Connector and peer-to-peer connectivity. Existing WARP Connectors are now called mesh nodes. The WARP client is now the Cloudflare One Client. All existing deployments continue to work — no migration required. ## How it works Mesh has two types of participants: | | Mesh nodes | Client devices | | --- | --- | --- | | **Runs on** | Linux servers, VMs, containers | Laptops, phones, desktops | | **Client** | [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) (`warp-cli`), headless | [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) (`warp-cli`) with UI | | **Mesh IP** | Assigned on enrollment | Assigned on enrollment | | **Subnet routing** | Can advertise CIDR routes | No — clients reach subnets through nodes | | **High availability** | Supports active-passive replicas | Not applicable | Any participant can reach any other participant by Mesh IP. Client-to-client connectivity works without deploying any Mesh nodes. ``` flowchart LR subgraph nodes["Mesh nodes"] A["web-server
100.96.0.1"] B["db-replica
100.96.0.2"] end subgraph devices["Client devices"] C["MacBook
100.96.0.10"] D["iPhone
100.96.0.11"] end A <--> CF((Cloudflare
network)) B <--> CF CF <--> C CF <--> D ``` All traffic passes through Cloudflare, so [Gateway network policies](https://developers.cloudflare.com/cloudflare-one/traffic-policies/network-policies/), [device posture checks](https://developers.cloudflare.com/cloudflare-one/reusable-components/posture-checks/), and access rules apply to every connection. ## Protocol requirement Cloudflare Mesh requires that the [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) of each Mesh node is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. Most deployments do not need to change anything. If a Mesh node's device profile uses WireGuard instead, the following capabilities will not work: - [Hostname routes](https://developers.cloudflare.com/mesh/features/routes/#hostname-routes) - [IPv6 CIDR routes](https://developers.cloudflare.com/mesh/features/routes/#manage-cidr-routes) - [High availability](https://developers.cloudflare.com/mesh/features/high-availability/) ## Mesh IPs Every participant is assigned a private IP from the `100.96.0.0/12` range. In other parts of the Cloudflare One documentation, these addresses are referred to as [device IPs](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-ips/). This range uses [CGNAT address space ↗](https://datatracker.ietf.org/doc/html/rfc6598) to avoid conflicts with RFC 1918 private ranges (`10.x`, `172.16.x`, `192.168.x`). If the default range conflicts with your network, you can [configure a custom subnet](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-ips/). View a device's Mesh IP on the [Mesh overview page ↗](https://dash.cloudflare.com/?to=/:account/mesh) or on the node detail page in the dashboard. For details on reserved ranges, refer to [Reserved IP addresses](https://developers.cloudflare.com/cloudflare-one/networks/routes/reserved-ips/). ## Mesh vs. Tunnel Both Cloudflare Mesh and [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) connect private infrastructure to Cloudflare, but they solve different problems: | | Cloudflare Mesh | Cloudflare Tunnel | | --- | --- | --- | | **Traffic direction** | Bidirectional — any participant can initiate | Inbound to origin — clients connect to published services | | **Addressing** | Every participant gets a Mesh IP | Server-side only, no Mesh IPs | | **Use case** | Private IP connectivity between devices and servers | Publishing specific applications, hostnames, or IP routes | | **Connector** | `warp-cli` | `cloudflared` | | **Protocols** | TCP, UDP, ICMP | HTTP/S, TCP, SSH, RDP, SMB (proxied over WebSocket) | Use Mesh when devices need to reach each other by private IP, or when your workload requires stable, long-lived TCP connections (SAP, database replication, ERP systems, RDP sessions). Mesh operates at L3/L4 and preserves connections end-to-end, making it the recommended software on-ramp for any traffic sensitive to connection interruptions. Use Tunnel when you want to publish services by hostname or proxy traffic to specific IP ranges through `cloudflared`.
Coming from another mesh networking product? If you have used Tailscale, WireGuard, or a similar product, here is how concepts map to Cloudflare Mesh: | Other products | Cloudflare Mesh | | --- | --- | | Tailnet / mesh network | Your Cloudflare account's Mesh network | | Node / peer | Mesh node (servers) or client device (laptops/phones) | | Subnet router | Mesh node with CIDR routes | | MagicDNS / custom DNS | Local Domain Fallback + Gateway resolver policies | | ACLs / access rules | Gateway network policies + device posture | | Exit node | Attach a public CIDR to a Mesh node and traffic to those IPs exits through that node. For broader Internet filtering, use Gateway egress policies. | | Admin console | Cloudflare dashboard ↗ under **Networking** > **Mesh** | Key differences: - You manage configuration entirely through the Cloudflare dashboard or API — no command-line administration needed. - Gateway policies, device posture, and identity checks are built into the platform. - Traffic routes through the nearest Cloudflare data center, not directly between devices.
## Next steps 1. [**Create your first Mesh node**](https://developers.cloudflare.com/mesh/get-started/) — The dashboard wizard handles provisioning. Install the client on a Linux server with two commands. 2. [**Connect client devices**](https://developers.cloudflare.com/mesh/guides/connect-client-devices/) — Install the Cloudflare One Client on laptops and phones. They can reach each other and any Mesh node by Mesh IP. 3. [**Run in Docker / Kubernetes**](https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/) — Deploy a Mesh node as a Docker container for Docker Compose, Kubernetes, and CI/CD environments. 4. [**Add routes**](https://developers.cloudflare.com/mesh/features/routes/) (optional) — Make subnets behind a Mesh node reachable from any device. 5. [**Enable high availability**](https://developers.cloudflare.com/mesh/features/high-availability/) (optional) — Run multiple replicas of a node for failover. 6. [**Connect from Workers**](https://developers.cloudflare.com/workers-vpc/examples/connect-to-cloudflare-mesh/) (optional) — Use VPC Network bindings to reach private services from Cloudflare Workers. 7. [**Delegate access**](https://developers.cloudflare.com/cloudflare-one/networks/connectors/granular-permissions/) (optional) — Scope member permissions to specific Mesh nodes instead of granting account-wide control. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/concepts/#page","headline":"How Cloudflare Mesh works · Cloudflare Docs","description":"Learn how Cloudflare Mesh connects participants, assigns private IPs, routes traffic, and differs from Cloudflare Tunnel.","url":"https://developers.cloudflare.com/mesh/concepts/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Configure routing and high availability for Cloudflare Mesh nodes. title: Features image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Features Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/features/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) - [Routes](https://developers.cloudflare.com/mesh/features/routes/) - [High availability](https://developers.cloudflare.com/mesh/features/high-availability/) Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"WebPage","@id":"https://developers.cloudflare.com/mesh/features/#page","headline":"Features · Cloudflare Docs","description":"Configure routing and high availability for Cloudflare Mesh nodes.","url":"https://developers.cloudflare.com/mesh/features/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Configure active-passive replicas to provide high availability for routed Cloudflare Mesh networks. title: High availability image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # High availability Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/features/high-availability/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) For production deployments, you can run multiple replicas of a Mesh node in active-passive mode. All replicas share the same node identity and advertise the same [routes](https://developers.cloudflare.com/mesh/features/routes/). If the active replica goes down, Cloudflare automatically promotes a standby replica. MASQUE required This feature requires that the [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) of the Mesh node is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. ## When to use high availability High availability provides resilience for CIDR route prefixes advertised by a Mesh node. When the active replica disconnects, Cloudflare promotes a standby so that traffic to the advertised subnets continues to flow. This means HA is useful for nodes that have routes configured — nodes acting as subnet gateways for private networks behind them. If a node is only used for direct Mesh IP connectivity (no routes), HA has limited benefit because the node's Mesh IP is tied to the individual replica. ## How it works When you create a Mesh node with high availability enabled, Cloudflare generates a single token for that node. You install the Cloudflare One Client on multiple Linux hosts using this token. Each host registers as a replica of the same node. - All replicas advertise the same CIDR routes. - One replica is active at a time. The others are passive standby. - If the active replica disconnects, Cloudflare automatically promotes a passive replica. - Failover is handled by Cloudflare's network. ``` flowchart LR subgraph replicas["Mesh node: web-server"] R1["Replica 1
(active)"] R2["Replica 2
(standby)"] R3["Replica 3
(standby)"] end CF((Cloudflare)) <--> R1 CF -. failover .-> R2 CF -. failover .-> R3 client["Client device"] <--> CF ``` ## Create a node with high availability When you create a Mesh node through the dashboard, high availability is enabled by default. To create a new node: 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select **Add a node**. 3. Follow the setup wizard. The node is created with HA enabled automatically. 4. Copy the install commands and run them on your Linux host. To create a node with high availability via the API, set `ha: true` in the request body: ```sh curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{ "name": "web-server", "ha": true }' ``` The response includes a `token` field. Use this token to register replicas. ## Add replicas To add a replica to an existing high-availability node, install the Cloudflare One Client on a new Linux host and register it using the same node token. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select your Mesh node. 3. Select **Add a replica**. 4. A dialog shows the install commands and the node's token. 5. On a new Linux host, run the install commands shown in the dialog.
Installation commands IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise CIDR routes, enable persistent forwarding before connecting it: ```sh 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 ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && 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 && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing cloudflare-warp. EPEL provides dependencies required by the Cloudflare One Client UI: ```sh sudo dnf install -y epel-release ``` Then install the package: ```sh curl -fsSl https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo yum install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ```
1. Retrieve the node's token: ```sh curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/token" \ -H "Authorization: Bearer {api_token}" ``` The response contains the token string. 2. Install the client and register on a new Linux host: IP forwarding is not required to reach the node by its Mesh IP. If the node will advertise [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/), enable persistent forwarding before connecting it: ```sh 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 ``` ```sh curl -fsSL https://pkg.cloudflareclient.com/pubkey.gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/cloudflare-warp-archive-keyring.gpg && 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 && sudo apt-get update -qq && sudo apt-get install -y -qq cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` On RHEL 9 and later, enable the Extra Packages for Enterprise Linux (EPEL) repository before installing `cloudflare-warp`. EPEL provides dependencies required by the Cloudflare One Client UI: ```sh sudo dnf install -y epel-release ``` Then install the package: ```sh curl -fsSl https://pkg.cloudflareclient.com/cloudflare-warp-ascii.repo | sudo tee /etc/yum.repos.d/cloudflare-warp.repo && sudo yum install -y cloudflare-warp ``` ```sh sudo warp-cli --accept-tos connector new && sudo warp-cli --accept-tos connect ``` The new replica will be in standby mode until the active replica disconnects. ## View replicas 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select an HA-enabled node. HA nodes display an **HA** badge in the overview table. 3. The node detail page shows a tab for each replica. Each tab displays: - **Active** or **Passive** badge - Mesh IP (IPv4 and IPv6) - Edge data center - Origin IP - Platform, version, and device name - Connected since timestamp To view all replicas and their HA status, query the connections API endpoint: ```sh curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/connections" \ -H "Authorization: Bearer {api_token}" ``` The response includes each replica with its `ha_status` (`active` or `passive`), connection details, and the Cloudflare data center it is connected to: ```json { "success": true, "result": [ { "id": "bf69f118-238e-11f1-b113-ee02f3be4a5b", "conns": [ { "colo_name": "lhr16", "origin_ip": "34.105.147.200", "opened_at": "2026-03-19T12:25:47.400Z" } ], "run_at": "2026-03-19T12:25:47.400Z", "ha_status": "active" }, { "id": "e07272a6-21fc-11f1-8997-e28f01ba3991", "conns": [ { "colo_name": "lhr14", "origin_ip": "35.246.81.139", "opened_at": "2026-03-19T02:38:37.203Z" } ], "run_at": "2026-03-19T02:38:37.203Z", "ha_status": "passive" } ] } ``` ## Manual failover In addition to automatic failover when the active replica disconnects, you can manually promote a passive replica to active. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select an HA-enabled node. 3. Select the tab for the passive replica you want to promote. 4. Select **Promote to active**. 5. In the confirmation dialog, select **Promote to active** to confirm. Traffic reroutes to the promoted replica immediately. The previous active replica switches to passive standby. To manually trigger failover, send a `PUT` request with the `client_id` of the replica you want to promote: ```sh curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/warp_connector/{node_id}/failover" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{ "client_id": "e07272a6-21fc-11f1-8997-e28f01ba3991" }' ``` Get the `client_id` from the [connections endpoint](#view-replicas). Use the `id` field of the replica you want to promote. ## Considerations ### Setup requirements - High availability is set at node creation time and cannot be changed afterward. - You must install the client on at least two hosts for failover to work. A single replica means no redundancy. - High availability requires that the Mesh node's [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. ### Network configuration - All replicas must be on the same subnet and have the same network routing configuration (Split Tunnels, static routes). - HA provides resilience for CIDR route prefixes. Nodes without routes do not benefit from HA failover. ### Failover behavior - Failover time depends on how quickly Cloudflare detects the active replica has disconnected (typically seconds). - Inbound traffic (from Mesh clients to the subnet) fails over automatically on Cloudflare's network. Cloudflare routes traffic to the newly promoted active replica. - Outbound traffic (from devices on the subnet through the Mesh node) does not fail over automatically. Your environment must detect that a different replica has been promoted to active and update routing tables to send traffic through the now-active host. There is no client-side failover for on-ramp traffic at this time. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/features/high-availability/#page","headline":"High availability for Cloudflare Mesh nodes · Cloudflare Docs","description":"Configure active-passive replicas to provide high availability for routed Cloudflare Mesh networks.","url":"https://developers.cloudflare.com/mesh/features/high-availability/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Configure CIDR and hostname routes to send private network traffic through Cloudflare Mesh nodes. title: Routes image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Routes Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/features/routes/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) By default, a Mesh node is reachable only by its own [Mesh IP](https://developers.cloudflare.com/mesh/concepts/#mesh-ips). To make other devices on the subnet behind the node reachable — servers, databases, printers, IoT devices that cannot run the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) — add a route to the node. A Mesh node supports two types of routes: - **CIDR routes** — forward traffic for an IP range — private (for example, `10.0.0.0/24`) or public — through the node. - **Hostname routes** — attract traffic for a hostname to the node instead of an IP. This works for a **private** hostname (for example, `wiki.internal.local`), which is useful when the application has an unknown or ephemeral IP, as well as a **public** hostname (for example, `www.example.com`), which routes that hostname's traffic through the node and egresses via the node's public IP. When you add a route, the Mesh node acts as a gateway: traffic destined for the advertised CIDR or hostname is forwarded to the node, which delivers it to the appropriate host on the local network (or egresses it to the public Internet). Both IPv4 and IPv6 CIDR routes are supported. IPv6 routes require that the Mesh node's [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol); they will not work if the device profile uses WireGuard instead. ## When to use routes - **Without routes** — Devices on your Mesh can only reach the node itself by its Mesh IP. Services running directly on the node are reachable this way. - **With routes** — Devices on your Mesh can reach any host on the subnet behind the node. Use this when you have infrastructure that cannot run the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/). ``` flowchart LR subgraph subnet["Subnet 10.0.0.0/24"] node["Mesh node
10.0.0.1"] db["Database
10.0.0.50"] printer["Printer
10.0.0.100"] end client["Client device
100.96.0.10"] --> CF((Cloudflare)) --> node node --> db node --> printer ``` ## Manage CIDR routes Use CIDR routes to forward traffic from your mesh node to devices on your local network. ### Add a route 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select your Mesh node. 3. Go to the **Routes** tab. 4. Select **Add route**. 5. Enter the private CIDR you want to route through this node (for example, `10.0.0.0/24`). 6. (Optionally) add a description for the route. 7. Select **Add route**.
Required API token permissions At least one of the following token permissions is required: - Cloudflare One Networks Write - Cloudflare Tunnel Write
*Create a tunnel routebash* ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "network": "10.0.0.0/24", "tunnel_id": "{mesh_node_id}", "comment": "Staging subnet" }' ``` ### Edit a route 1. Go to **Networking** > **Mesh** > select your node > **Routes** tab. 2. Select the edit icon next to the route you want to modify. 3. Update the CIDR or description. 4. Select **Save**.
Required API token permissions At least one of the following token permissions is required: - Cloudflare One Networks Write - Cloudflare Tunnel Write
*Update a tunnel routebash* ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes/$ROUTE_ID" \ --request PATCH \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "network": "10.0.0.0/24", "comment": "Updated description" }' ``` ### Delete a route 1. Go to **Networking** > **Mesh** > select your node > **Routes** tab. 2. Select the delete icon next to the route. 3. Confirm deletion.
Required API token permissions At least one of the following token permissions is required: - Cloudflare One Networks Write - Cloudflare Tunnel Write
*Delete a tunnel routebash* ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/teamnet/routes/$ROUTE_ID" \ --request DELETE \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" ``` ## Configure Split Tunnels For traffic to reach your advertised CIDR, the range must route through Cloudflare on both the Mesh node and client devices. ### On the Mesh node In your Mesh node's device profile, ensure the advertised CIDR routes through Cloudflare: - **Include mode** (recommended for Mesh nodes): Add the CIDR to your include list. - **Exclude mode**: Remove the CIDR (or its parent range) from your exclude list. For example, if you are advertising `10.0.0.0/24` and your Split Tunnels exclude list contains `10.0.0.0/8`, you need to remove `10.0.0.0/8` and re-add the portions of the `10.0.0.0/8` range that you do not want to route through Cloudflare. ### On client devices Repeat the same Split Tunnel configuration on the device profiles used by your client devices, ensuring the advertised CIDR routes through Cloudflare. ## Return traffic routing The Mesh node forwards inbound traffic from Cloudflare to devices on the subnet. However, for **return traffic** (responses from subnet devices back to Mesh clients), the subnet devices need a route back to the Mesh node. ``` flowchart LR client["Client device
100.96.0.10"] -- request --> CF((Cloudflare)) -- request --> node["Mesh node
10.0.0.1"] node --> db["Database
10.0.0.50"] db -. "response:
needs route to node" .-> node -. response .-> CF -. response .-> client ``` How you configure this depends on where the Mesh node is installed: ### Option 1: Mesh node is the default gateway If the Mesh node is the subnet's default gateway (or is installed on the router), no additional configuration is needed. All traffic from subnet devices naturally routes through the node. ### Option 2: Mesh node is not the default gateway If the Mesh node is a regular host on the subnet, configure the subnet's router to send Mesh traffic through the node. Add a static route: - **Destination**: `100.96.0.0/12` (Mesh IP range) - **Next hop**: The Mesh node's local subnet IP (for example, `10.0.0.1`) This ensures that responses to Mesh clients are forwarded to the Mesh node for delivery through Cloudflare. ## Site-to-site routing When you have Mesh nodes at multiple sites, devices on one subnet can reach devices on another subnet through Cloudflare. ``` flowchart TD subgraph siteA["Site A — 10.0.0.0/24"] serverA["Server
10.0.0.50"] --- nodeA["Mesh node
10.0.0.1"] end subgraph siteB["Site B — 192.168.1.0/24"] serverB["Server
192.168.1.50"] --- nodeB["Mesh node
192.168.1.1"] end nodeA <--> CF((Cloudflare)) nodeB <--> CF ``` For this to work: 1. Each Mesh node must advertise the local subnet as a [CIDR route](#add-a-route) so Cloudflare knows which node to forward traffic to. 2. The remote subnet CIDRs must route through Cloudflare on each node. In your Mesh node's [Split Tunnel](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) configuration, add the remote site's CIDR to the include list (or remove it from the exclude list). 3. Each site's router needs static routes pointing remote subnets to the local Mesh node: **Site A router:** - **Destination**: `192.168.1.0/24` → **Next hop**: `10.0.0.1` (local Mesh node) - **Destination**: `100.96.0.0/12` → **Next hop**: `10.0.0.1` **Site B router:** - **Destination**: `10.0.0.0/24` → **Next hop**: `192.168.1.1` (local Mesh node) - **Destination**: `100.96.0.0/12` → **Next hop**: `192.168.1.1` For production site-to-site deployments, consider enabling [high availability](https://developers.cloudflare.com/mesh/features/high-availability/) on each node. HA provides failover for the CIDR routes advertised by a node — if the active replica goes down, Cloudflare promotes a standby so traffic to the subnet continues to flow. ## DNS filtering To filter DNS queries from the subnet using [Cloudflare Gateway](https://developers.cloudflare.com/cloudflare-one/traffic-policies/dns-policies/): 1. **Configure DNS on your router**: Point your router's DNS to the Gateway resolver IPs: - `172.64.36.1` - `172.64.36.2` 2. **Add IP routes to your router**: On your router, add static routes pointing the Gateway resolver IPs to your Mesh node's local IP. This allows DNS traffic to reach Cloudflare through the node. - **Destination**: `172.64.36.1` → **Next hop**: `10.0.0.1` (local Mesh node) - **Destination**: `172.64.36.2` → **Next hop**: `10.0.0.1` 3. **Configure Split Tunnels**: Ensure the following IPs route through the Mesh node in your [Split Tunnels](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) configuration: - The subnet's internal DNS resolver IP - Gateway initial resolved IP range: `172.64.128.0/20` (IPv4) and `2606:4700:0cf1:4000::/64` (IPv6) Gateway logs DNS queries with the private source IP of the originating device. You can use this to create [resolver policies](https://developers.cloudflare.com/cloudflare-one/traffic-policies/resolver-policies/) for internal DNS records. ## Hostname routes Instead of advertising an IP range, you can attract traffic for a specific hostname to a Mesh node. When a user requests the hostname, Cloudflare Gateway assigns an initial resolved IP and routes the traffic through the node. - **Private hostname** (for example, `wiki.internal.local`) — the node delivers the traffic to the application's private IP on the local network. Useful when the application has an unknown or ephemeral IP. - **Public hostname** (for example, `www.example.com`) — the node egresses the traffic to the public Internet using its own public IP. This lets you use a Mesh node as a dedicated egress for that hostname. Hostname routes replace [virtual networks](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/tunnel-virtual-networks/) as the way to reach resources: because a hostname is globally unique, **overlapping hostnames are not supported** and a hostname can only be routed to one node or tunnel at a time. 1. [Client device](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) Requests `wiki.internal.local` 2. DNS query↓ 3. [Cloudflare Gateway](https://developers.cloudflare.com/cloudflare-one/traffic-policies/) Returns a token IP, then rewrites the destination to the real private IP. `172.64.128.0/20` 4. [Hostname route](https://developers.cloudflare.com/mesh/features/routes/#hostname-routes)↓ 5. [Mesh node](https://developers.cloudflare.com/mesh/) Forwards traffic to the host on the local network 6. ↓ 7. Private host `wiki.internal.local` · `10.0.0.50` For a deeper look at the packet flow behind hostname routing, refer to the [announcement blog post ↗](https://blog.cloudflare.com/tunnel-hostname-routing/). ### Prerequisites - **Run a supported Mesh node version.** Hostname routing requires the Mesh node to run Linux Cloudflare One Client version `2026.6.822.0` or newer. - **Configure the Mesh node's [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol).** Hostname routing does not work if the device profile uses WireGuard instead. - **Enable the Gateway proxy** with TCP, UDP, and ICMP: 1. Go to **Traffic policies** > **Traffic settings**. 2. In **Proxy and inspection**, turn on **Allow Secure Web Gateway to proxy traffic**. 3. Select **TCP**. 4. Select **UDP** (required to proxy traffic to internal DNS resolvers). 5. (Recommended) To proxy traffic for diagnostic tools such as `ping` and `traceroute`, select **ICMP**. You may also need to [update your system](https://developers.cloudflare.com/cloudflare-one/traffic-policies/proxy/#icmp) to allow ICMP traffic through `cloudflared`. 1. Add the following permission to your [`cloudflare_api_token` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/api_token): - `Zero Trust Write` 2. Turn on the TCP and/or UDP proxy using the [`cloudflare_zero_trust_device_settings` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_device_settings) resource: ```tf resource "cloudflare_zero_trust_device_settings "global_warp_settings" { account_id = var.cloudflare_account_id gateway_proxy_enabled = true gateway_udp_proxy_enabled = true } ``` Cloudflare will now proxy traffic from enrolled devices, except for the traffic excluded in your [split tunnel settings](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/#3-route-private-network-ips-through-the-cloudflare-one-client). For more information on how Gateway forwards traffic, refer to [Gateway proxy](https://developers.cloudflare.com/cloudflare-one/traffic-policies/proxy/). - **Route the following IPv4 ranges through Cloudflare** in the [Split Tunnel](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) configuration of **both** the Mesh node's device profile **and** your client device profiles. In Include mode, add each range. In Exclude mode, ensure none of them (or their parent ranges) are excluded. | Purpose | IPv4 | | --- | --- | | Mesh device IP range | `100.96.0.0/12` | | Cloudflare source IP range | `100.64.0.0/12` | The hostname routing (token IP) range ( `172.64.128.0/20`) and all Cloudflare One IPv6 ranges are [automatically routed through Cloudflare](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/#automatically-managed-ranges) and do not need to be added manually. - **Remove the hostname's top-level domain from [Local Domain Fallback](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/local-domains/)** on client devices, so the DNS query is sent to Cloudflare Gateway for resolution. ### Add a hostname route 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select your Mesh node. 3. Go to the **Routes** tab. 4. Select **Add route**, then select **Private hostname**. 5. Enter the fully qualified domain name (FQDN) you want to route through this node (for example, `wiki.internal.local`).
Hostname format restrictions - **Character limit:** Must be less than 255 characters. - **Supported wildcards:** A single wildcard (*) is allowed, and it must represent a full DNS label. Example: *.internal.local - **Unsupported wildcards:** The following wildcard formats are not supported: - Partial wildcards such as *-dev.internal.local or dev-*.internal.local. - Wildcards in the middle, such as foo*bar.internal.local or foo.*.internal.local. - Multiple wildcards in the hostname, such as *.*.internal.local. - **Wildcard trimming**: Leading wildcards (*) are trimmed off and an implicit dot (.) is assumed. For example, *.internal.local is saved as internal.local but will match all subdomains at the wildcard level (covers foo.internal.local but not foo.bar.internal.local). - **Dot trimming:** Leading and ending dots (.) are allowed but trimmed off.
6. (Optionally) add a description for the route. 7. Select **Add hostname**.
Required API token permissions At least one of the following token permissions is required: - Cloudflare One Networks Write - Cloudflare Tunnel Write
*Create hostname routebash* ```bash curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/zerotrust/routes/hostname" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --json '{ "hostname": "wiki.internal.local", "tunnel_id": "{mesh_node_id}", "comment": "Internal wiki" }' ``` ### Configure DNS resolution For a **private** hostname, Gateway must be able to resolve the hostname to its private IP. How you configure this depends on whether DNS resolution and application traffic use the **same** connector or **different** connectors. #### The node resolves the hostname (default) By default, the Mesh node resolves the hostname using the DNS resolver configured on its host machine (for example, in `/etc/resolv.conf` on Linux) — the same way `cloudflared` does. If the node can already resolve the hostname to its private IP through that resolver, no further configuration is required. If the node cannot resolve the hostname on its own, the simplest option is to add an entry to the node's hosts file (for example, `/etc/hosts` on Linux) mapping the hostname to its private IP. Unlike a Cloudflare Tunnel, a Mesh node does **not** require you to run a dedicated DNS server: */etc/hoststxt* ```txt 10.0.0.50 wiki.internal.local ``` #### Split DNS: DNS and application traffic use different connectors You only need a Gateway [resolver policy](https://developers.cloudflare.com/cloudflare-one/traffic-policies/resolver-policies/) when the DNS query must be sent to a **different** connector than the application traffic — for example, the internal DNS server sits behind one Mesh node or Cloudflare Tunnel, while the application is reached through another. In that case: 1. Add a [CIDR route](#add-a-route) for the DNS server's IP so Gateway can reach it through the connector where the DNS server lives (a Mesh node or a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)). 2. Create a [resolver policy](https://developers.cloudflare.com/cloudflare-one/traffic-policies/resolver-policies/) that sends DNS queries for the hostname (or its domain) to that internal DNS server. Where to run the DNS server If the DNS server is reached through a Mesh node, you cannot run it on the **same machine** as that node — the node's DNS interface binds port `53`. Host the DNS server on a separate machine in the same private network. In that case, configure return routes on the subnet so the DNS server's responses can reach the client: - **Mesh device IP range**: `100.96.0.0/12` → next hop is the Mesh node's local IP - **Initial resolved IP range**: `172.64.128.0/20` → next hop is the Mesh node's local IP For a **public** hostname, the Mesh node handles resolution: Gateway sends the DNS query to the node, the node resolves it through its upstream DNS provider, and then routes the packet to the destination and egresses using its own public IP. No internal DNS server or resolver policy is required. ### Secure hostname traffic After adding a hostname route, secure it with either an [Access self-hosted application](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/non-http/self-hosted-private-app/) or [Gateway network policies](https://developers.cloudflare.com/cloudflare-one/traffic-policies/network-policies/). For details and examples, refer to [Connect a private hostname](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-private-hostname/#3-recommended-filter-network-traffic-with-gateway). ### Limitations Starting with [Chrome 142 ↗](https://developer.chrome.com/release-notes/142), Local Network Access (LNA) restricts requests from websites to local IP addresses. LNA is implemented at the Chromium engine level, so this affects all Chromium-based browsers (for example, Microsoft Edge, Brave, and Opera), not only Google Chrome. This can affect accounts whose Gateway initial resolved IP range is still drawn from Carrier-Grade NAT (CGNAT) address space (`100.64.0.0/10`) — for example, the legacy default range `100.80.0.0/16`, or a custom range configured within CGNAT space. These browsers categorize such addresses as belonging to a local network. When a website loaded from a public IP makes subrequests to a domain resolved through an initial resolved IP in this space, the browser treats this as a public-to-local network request and displays a prompt asking the user to allow access to devices on the local network. The browser blocks requests to these domains until the user accepts this prompt. This commonly occurs when an Egress policy matches broadly used domains (such as `cloudfront.net` or `github.com`), causing subrequests from public pages to resolve into CGNAT space. Accounts using the current default initial resolved IP range (`172.64.128.0/20`) are not affected, because this range is public Cloudflare address space rather than CGNAT. If your account was created before this default changed, or if you configured a custom CGNAT-space range, refer to [Configure initial resolved IPs](https://developers.cloudflare.com/cloudflare-one/networks/routes/configure-initial-resolved-ips/) to move to a non-CGNAT range instead of relying on the following browser workarounds. The workarounds below use Google Chrome Enterprise policies. If your organization manages a different Chromium-based browser, consult that browser's enterprise policy documentation for an equivalent control. #### Iframes If the affected request originates from within an iframe (for example, an application embedded in a third-party portal), the iframe must declare the `local-network-access` permission for the browser prompt to appear in the parent frame: - **Chrome 142-144**: Use the `allow="local-network-access"` attribute on the iframe element. - **Chrome 145+**: The permission was split into `allow="local-network"` and `allow="loopback-network"`. If iframes are nested, every iframe in the chain must include the appropriate attribute. Since third-party applications control their own iframe attributes, this may not be configurable by the end user. #### Workarounds To avoid this issue, choose one of the following options: - **Override IP address space classification (Chrome 146+)**: Use the [`LocalNetworkAccessIpAddressSpaceOverrides` ↗](https://chromeenterprise.google/policies/#LocalNetworkAccessIpAddressSpaceOverrides) Chrome Enterprise policy to reclassify your CGNAT-space initial resolved IP range (for example, `100.80.0.0/16`) as public. This is the most targeted fix because it only changes the classification for the initial resolved IP range rather than disabling security checks entirely. - **Allow specific URLs (Chrome 140+)**: Use the [`LocalNetworkAccessAllowedForUrls` ↗](https://chromeenterprise.google/policies/#LocalNetworkAccessAllowedForUrls) Chrome Enterprise policy to exempt specific websites from Local Network Access checks. Note that `https://*` is a valid entry to disable checks for all URLs. - **Allow specific URLs (Chrome 146+)**: Use the [`LocalNetworkAllowedForUrls` ↗](https://chromeenterprise.google/policies/#LocalNetworkAllowedForUrls) Chrome Enterprise policy, which replaces `LocalNetworkAccessAllowedForUrls` starting in Chrome 146. - **Opt out of Local Network Access restrictions (Chrome 142-152)**: Use the [`LocalNetworkAccessRestrictionsTemporaryOptOut` ↗](https://chromeenterprise.google/policies/#LocalNetworkAccessRestrictionsTemporaryOptOut) Chrome Enterprise policy to completely opt out of Local Network Access restrictions. This is a temporary policy and will be removed after Chrome 152. - **Disable the Chrome feature flag**: Go to `chrome://flags` and set the **Local Network Access Checks** flag to *Disabled*. This approach is suitable for individual users but not for enterprise-wide deployment. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/features/routes/#page","headline":"Configure routes for Cloudflare Mesh · Cloudflare Docs","description":"Configure CIDR and hostname routes to send private network traffic through Cloudflare Mesh nodes.","url":"https://developers.cloudflare.com/mesh/features/routes/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Connect devices and deploy Cloudflare Mesh in container environments. title: Guides image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Guides Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/guides/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) - [Connect client devices](https://developers.cloudflare.com/mesh/guides/connect-client-devices/) - [Run Mesh in Docker / Kubernetes](https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/) Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"WebPage","@id":"https://developers.cloudflare.com/mesh/guides/#page","headline":"Guides · Cloudflare Docs","description":"Connect devices and deploy Cloudflare Mesh in container environments.","url":"https://developers.cloudflare.com/mesh/guides/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ``` --- --- description: Connect laptops, phones, and desktops to Cloudflare Mesh and verify private network connectivity. title: Connect client devices image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Connect client devices Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/guides/connect-client-devices/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Client devices — laptops, phones, and desktops — join your Mesh network by installing the [Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/) and enrolling. Each device receives a [Mesh IP](https://developers.cloudflare.com/mesh/concepts/#mesh-ips) and can immediately communicate with every other enrolled device and Mesh node. ## Prerequisites - [Device enrollment permissions](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/device-enrollment/) are configured for your account. The Mesh [setup wizard](https://developers.cloudflare.com/mesh/get-started/) handles this automatically. ## 1. Enroll the Cloudflare One Client Connect a laptop or phone to your Mesh network: ### Windows, macOS, and Linux To enroll your device using the client GUI: 1. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Client. 2. Launch the Cloudflare One Client. 3. On the **What would you like to use the Cloudflare One Client for?** screen, select **Zero Trust security**. 4. Enter your team name. 5. Complete the authentication steps required by your organization. Once authenticated, you will see a Success page and a dialog prompting you to open the Cloudflare One Client. 6. Select **Open the Cloudflare One Client** to complete the registration. 7. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Client. 8. Launch the Cloudflare One Client. 9. Select the Cloudflare logo in the menu bar. 10. Select the gear icon. 11. Go to **Preferences** > **Account**. 12. Select **Login with Cloudflare Zero Trust**. 13. Enter your team name. 14. Complete the authentication steps required by your organization. Once authenticated, you will see a Success page and a dialog prompting you to open the Cloudflare One Client. 15. Select **Open Cloudflare WARP.app** to complete the registration. ### iOS and Android 1. [Download](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/) and install the Cloudflare One Agent app. 2. Launch the Cloudflare One Agent app. 3. Select **Next**. 4. Review the privacy policy and select **Accept**. 5. Enter your team name. 6. Complete the authentication steps required by your organization. 7. After authenticating, select **Install VPN Profile**. 8. In the **Connection request** popup window, select **OK**. 9. If you did not enable [auto-connect ↗](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#auto-connect), manually turn on the switch to **Connected**. ### Headless Windows, macOS, and Linux devices Do not use interactive CLI enrollment on a device without a browser. Instead, [create a Service Auth enrollment policy](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/device-enrollment/#check-for-service-token). Configure the [`organization`](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/mdm-deployment/parameters/#organization), [`auth_client_id`](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/mdm-deployment/parameters/#auth_client_id), and [`auth_client_secret`](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/mdm-deployment/parameters/#auth_client_secret) managed deployment parameters. For platform-specific installation methods and configuration file locations, refer to [Managed deployment](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/deployment/mdm-deployment/). For a complete Linux example, refer to [Deploy the Cloudflare One Client on headless Linux machines](https://developers.cloudflare.com/cloudflare-one/tutorials/deploy-client-headless-linux/). This method works on [supported Windows, macOS, and Linux systems](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/). Service-token devices use the shared identity `non_identity@.cloudflareaccess.com`. Policies based on identity provider users or groups do not apply to these devices. To assign device profiles, use the expression `identity.service_token_uuid == ""`, where `` is the service token resource UUID (`id`), not its `auth_client_id`. Place this [Service Token selector](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/#service-token) before broader OS or email profiles. Use the shared non-identity email only when all Service Auth devices should match the profile. After enrollment, the device receives a Mesh IP and connects to your Mesh network. ## 2. Verify connectivity From a Windows, macOS, or Linux device, test TCP connectivity to a Mesh node or another client device. For example, test SSH: ```sh nc -vz 22 ``` ```powershell Test-NetConnection -Port 22 ``` Replace `` with the Mesh IP of a node (visible on the [Mesh overview page ↗](https://dash.cloudflare.com/?to=/:account/mesh)) or another enrolled device. Replace port `22` with the port used by your service. You can test HTTP services from a mobile browser. If you turned on the ICMP Gateway proxy, you can also run `ping ` as a diagnostic check. If the device profile routes `www.cloudflare.com` through WARP, verify the data path: ```sh curl --silent https://www.cloudflare.com/cdn-cgi/trace | grep '^warp=on$' ``` ```powershell if (-not (curl.exe --silent https://www.cloudflare.com/cdn-cgi/trace | Select-String '^warp=on$')) { exit 1 } ``` In Include mode, expect `warp=off` for destinations that are not in the include list. Use the successful connection to an included Mesh IP as the data-path check. Do not rely only on the success message from `warp-cli`: Mesh connectivity requires Traffic and DNS mode. In DNS-only mode, use `warp-cli registration show` only to verify enrollment. DNS-only mode cannot carry Mesh traffic. ## What devices can reach Once connected, a client device can: - **Other client devices** — Reach any enrolled device by its Mesh IP. No Mesh nodes involved. - **Mesh nodes** — Reach any online node by its Mesh IP. SSH, database connections, API calls all work. - **Subnets behind nodes** — Access hosts on private networks that a node advertises via [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/) (for example, printers, databases, or servers that cannot run the client). All traffic is subject to your [Gateway network policies](https://developers.cloudflare.com/cloudflare-one/traffic-policies/network-policies/), so you can control which users and devices can reach specific resources. ## Split Tunnel configuration For client devices to reach Mesh IPs, the Mesh IP range must route through Cloudflare. How you configure this depends on your [Split Tunnel mode](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/). ### Exclude mode (default) The Mesh setup wizard updates the default device profile to route the Mesh IP range through Cloudflare. If you did not use the wizard, or if another profile applies to the device, verify that `100.96.0.0/12` (or your custom device IP range) is not in the exclude list or contained by a broader exclusion. Depending on your Cloudflare networking configuration, you may need to remove additional IPs from your exclude list. For a list of IPs to check, refer to [Reserved IP addresses](https://developers.cloudflare.com/cloudflare-one/networks/routes/reserved-ips/). ### Include mode In Include mode, add the following to your include list: - `100.96.0.0/12` — Mesh IPs (device IPs) - Any CIDR routes you have [configured for your Mesh nodes](https://developers.cloudflare.com/mesh/features/routes/) The IPv4 range used for [hostname routing](https://developers.cloudflare.com/mesh/features/routes/#hostname-routes) (`172.64.128.0/20`; requires MASQUE) and all Cloudflare One IPv6 ranges are [automatically routed through Cloudflare](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/#automatically-managed-ranges) and do not need to be added manually. ## Firewall considerations Some operating systems block inbound traffic from the Mesh IP range by default: - **Windows** — Windows Firewall blocks inbound traffic from `100.96.0.0/12`. Add a firewall rule that allows incoming requests from `100.96.0.0/12` for your desired protocols and ports. - **macOS / Linux** — Most configurations allow this traffic by default. If you have custom firewall rules, ensure `100.96.0.0/12` is permitted. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/guides/connect-client-devices/#page","headline":"Connect client devices to Cloudflare Mesh · Cloudflare Docs","description":"Connect laptops, phones, and desktops to Cloudflare Mesh and verify private network connectivity.","url":"https://developers.cloudflare.com/mesh/guides/connect-client-devices/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Run a Cloudflare Mesh node as a Docker container for Docker Compose, Kubernetes, and CI/CD environments. title: Run Mesh in Docker / Kubernetes image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Run Mesh in Docker / Kubernetes Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) The [`cloudflare/mesh` ↗](https://hub.docker.com/r/cloudflare/mesh) Docker image packages a Cloudflare Mesh node for Linux containers. It runs the Cloudflare One Client's `warp-svc` daemon headlessly in a minimal [Wolfi ↗](https://wolfi.dev/)-based runtime. Use the container image to add Mesh nodes to Docker Compose stacks, Kubernetes clusters, and CI/CD pipelines — without installing packages on the host. ## Supported architectures The `latest` tag is a multi-platform manifest. Docker automatically selects the appropriate image for the host architecture. | Architecture | Tag | | --- | --- | | Multi-arch | `latest` | | x86-64 | `latest-amd64` | | ARM64 | `latest-arm64` | ## Prerequisites Before starting the container, create a Mesh node and copy its token. 1. In the Cloudflare dashboard, go to **Networking** > **Mesh**. [Go to **Mesh** ↗](https://dash.cloudflare.com/?to=/:account/mesh) 2. Select **Add a node**. 3. Enter a name for your node (for example, `k8s-gateway` or `docker-agent`). 4. Select **Create node**. 5. Copy the token shown in the dashboard. You will pass it to the container as `MESH_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: ```bash 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":"k8s-gateway"}' ) 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. Pass `MESH_NODE_TOKEN` to the container. Note Mesh nodes can also be managed with Terraform using the [`cloudflare_zero_trust_tunnel_warp_connector` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_warp_connector) resource. To manage node configuration, use [`cloudflare_zero_trust_tunnel_warp_connector_config` ↗](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/zero_trust_tunnel_warp_connector_config). If this is your first Mesh node, configure the [required account settings](https://developers.cloudflare.com/mesh/get-started/#required-account-settings). You can use the dashboard wizard, APIs, or Terraform. Caution Do not commit Mesh node tokens to source control. Use environment variables, `.env` files excluded from version control, or a secrets manager. ## Deploy with Docker Compose Docker Compose is the recommended way to run a Mesh node alongside your application services. Add a `cloudflare-mesh` service to your `compose.yaml`: ```yaml services: cloudflare-mesh: image: cloudflare/mesh:latest container_name: cloudflare-mesh cap_add: - NET_ADMIN - NET_RAW devices: - /dev/net/tun:/dev/net/tun environment: MESH_NODE_TOKEN: ${MESH_NODE_TOKEN} SRCNAT_ENABLED: "true" sysctls: net.ipv4.ip_forward: "1" net.ipv6.conf.all.forwarding: "1" net.ipv6.conf.default.forwarding: "1" volumes: - mesh_data:/var/lib/cloudflare-warp restart: unless-stopped volumes: mesh_data: ``` Start the stack: ```sh MESH_NODE_TOKEN="" docker compose up -d ``` Verify the node is connected: ```sh docker exec cloudflare-mesh warp-cli status ``` ## Deploy with Docker CLI For a standalone container without Compose: ```sh docker run -d \ --name cloudflare-mesh \ --cap-add NET_ADMIN \ --cap-add NET_RAW \ --device /dev/net/tun \ --sysctl net.ipv4.ip_forward=1 \ --sysctl net.ipv6.conf.all.forwarding=1 \ --sysctl net.ipv6.conf.default.forwarding=1 \ -e MESH_NODE_TOKEN="$MESH_NODE_TOKEN" \ -e SRCNAT_ENABLED=true \ -v mesh_data:/var/lib/cloudflare-warp \ --restart unless-stopped \ cloudflare/mesh:latest ``` ## Deploy on Kubernetes This example creates a one-replica `StatefulSet` with persistent registration state. It requires a Kubernetes cluster that permits `NET_ADMIN`, `NET_RAW`, and `/dev/net/tun` host access (for example, GKE Standard). ### 1. Create the token Secret ```sh kubectl create secret generic cloudflare-mesh \ --from-literal=MESH_NODE_TOKEN="$MESH_NODE_TOKEN" ``` ### 2. Apply the manifest Save the following as `cloudflare-mesh.yaml`: ```yaml apiVersion: v1 kind: Service metadata: name: cloudflare-mesh spec: clusterIP: None selector: app: cloudflare-mesh --- apiVersion: apps/v1 kind: StatefulSet metadata: name: cloudflare-mesh spec: serviceName: cloudflare-mesh replicas: 1 selector: matchLabels: app: cloudflare-mesh template: metadata: labels: app: cloudflare-mesh spec: containers: - name: mesh image: cloudflare/mesh:latest env: - name: MESH_NODE_TOKEN valueFrom: secretKeyRef: name: cloudflare-mesh key: MESH_NODE_TOKEN - name: SRCNAT_ENABLED value: "true" securityContext: capabilities: add: - NET_ADMIN - NET_RAW volumeMounts: - name: warp-data mountPath: /var/lib/cloudflare-warp - name: dev-net-tun mountPath: /dev/net/tun volumes: - name: dev-net-tun hostPath: path: /dev/net/tun type: CharDevice volumeClaimTemplates: - metadata: name: warp-data spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi ``` ### 3. Verify the node ```sh kubectl apply -f cloudflare-mesh.yaml kubectl rollout status statefulset/cloudflare-mesh kubectl exec cloudflare-mesh-0 -- warp-cli status ``` The `PersistentVolumeClaim` preserves the Mesh registration across Pod restarts. Note GKE Autopilot is not supported because it blocks the required `/dev/net/tun` `hostPath`. ## Kubernetes sidecar To connect an application container to Mesh, add the Mesh image as a sidecar in the same Pod. Containers in a Pod share the network namespace, so the Mesh sidecar connects the application to Cloudflare without any application changes. ### 1. Create the token Secret Create a separate Mesh node and Kubernetes Secret for the sidecar: ```sh kubectl create secret generic cloudflare-mesh-sidecar \ --from-literal=MESH_NODE_TOKEN="$MESH_NODE_TOKEN" ``` ### 2. Apply the manifest Save the following as `cloudflare-mesh-sidecar.yaml`: ```yaml apiVersion: v1 kind: Service metadata: name: cloudflare-mesh-sidecar-headless spec: clusterIP: None selector: app: cloudflare-mesh-sidecar --- apiVersion: apps/v1 kind: StatefulSet metadata: name: cloudflare-mesh-sidecar spec: serviceName: cloudflare-mesh-sidecar-headless replicas: 1 selector: matchLabels: app: cloudflare-mesh-sidecar template: metadata: labels: app: cloudflare-mesh-sidecar spec: containers: - name: application image: busybox:1.37.0 command: - sh - -c - | echo "Hello from the Kubernetes sidecar example" > /tmp/index.html httpd -f -p 8080 -h /tmp ports: - name: http containerPort: 8080 - name: mesh image: cloudflare/mesh:latest env: - name: MESH_NODE_TOKEN valueFrom: secretKeyRef: name: cloudflare-mesh-sidecar key: MESH_NODE_TOKEN - name: SRCNAT_ENABLED value: "true" securityContext: capabilities: add: - NET_ADMIN - NET_RAW volumeMounts: - name: warp-data mountPath: /var/lib/cloudflare-warp - name: dev-net-tun mountPath: /dev/net/tun volumes: - name: dev-net-tun hostPath: path: /dev/net/tun type: CharDevice volumeClaimTemplates: - metadata: name: warp-data spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi --- apiVersion: v1 kind: Service metadata: name: cloudflare-mesh-sidecar spec: selector: app: cloudflare-mesh-sidecar ports: - name: http port: 8080 targetPort: http ``` ### 3. Verify the sidecar ```sh kubectl apply -f cloudflare-mesh-sidecar.yaml kubectl rollout status statefulset/cloudflare-mesh-sidecar kubectl exec cloudflare-mesh-sidecar-0 -c mesh -- warp-cli status ``` ## Runtime configuration | Parameter | Description | | --- | --- | | `MESH_NODE_TOKEN` | **Required** for initial registration. Create the token under **Networking** > **Mesh** in the [Cloudflare dashboard ↗](https://dash.cloudflare.com/?to=/:account/mesh), or via the [API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/tunnels/subresources/warp_connector/methods/create/). | | `SRCNAT_ENABLED` | Controls [source NAT](#source-nat). Defaults to `true`. Accepts `true`, `false`, `1`, or `0`. | | `/var/lib/cloudflare-warp` | Stores registration state. Persist this path with a volume to maintain a stable Mesh identity across container recreation. |
Required capabilities and devices | Capability / device | Why it is needed | | --- | --- | | NET_ADMIN | Creates and configures the tunnel interface, routing, and nftables rules. | | NET_RAW | Enables raw-socket operations such as ICMP. Docker normally grants this capability by default, but it is declared explicitly here. | | /dev/net/tun | Creates the WARP TUN interface. | | IP-forwarding sysctls | Required when the node forwards traffic for routed subnets. |
## Source NAT Source NAT (masquerading) is enabled by default (`SRCNAT_ENABLED=true`). When a Mesh node receives traffic from the Cloudflare edge and forwards it to a destination on the local network, it translates the source IP from the Mesh CGNAT address (`100.96.x.x`) to the node's own local interface IP. This ensures return traffic routes correctly without requiring static routes in your VPC or on-premise network. Set `SRCNAT_ENABLED=false` only if the attached networks already have return routes to the Mesh IP range (`100.96.0.0/12`). For more details on return traffic routing, refer to [Routes](https://developers.cloudflare.com/mesh/features/routes/#return-traffic-routing). ## High availability on Kubernetes MASQUE required This feature requires that the [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) of the Mesh node is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. For [high availability](https://developers.cloudflare.com/mesh/features/high-availability/) with CIDR routes: 1. Use the same Mesh node token across multiple replicas. 2. Give each Pod its own `PersistentVolumeClaim`. Cloudflare operates replicas in active-passive mode. If the active replica goes offline, traffic fails over to a standby automatically. A single replica provides no redundancy. ## Hostname routes Containers support [hostname routing](https://developers.cloudflare.com/mesh/features/routes/#hostname-routes). To resolve Kubernetes Services through a hostname route, make sure the hostname matches the cluster's actual DNS suffix. The default is `cluster.local`, producing Service names like `service.namespace.svc.cluster.local`. MASQUE required This feature requires that the [device profile](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/device-profiles/) of the Mesh node is configured to use [MASQUE](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/settings/#device-tunnel-protocol), the default protocol for the Cloudflare One Client. It does not work if the device profile uses WireGuard instead. ## Site-to-site networking Deploy a separate Mesh node container at each site with a separate node token for each node identity. Each node should advertise its locally reachable subnet as a [CIDR route](https://developers.cloudflare.com/mesh/features/routes/). Configure each site's router or workloads to send traffic for the remote subnet through the local Mesh node. With `SRCNAT_ENABLED=true`, destinations see the Mesh node's local address. With source NAT disabled, the attached networks require return routes through their Mesh nodes. ## Troubleshooting ### Node registers as a regular Cloudflare One Client device Confirm that the correct Mesh node token is set in `MESH_NODE_TOKEN`. Existing registration state in the persistent volume takes precedence — remove the volume only when you intentionally want to discard that registration and create a new identity. ### `warp-cli status` remains Connecting Check the token, device profile, Gateway proxy, Split Tunnel configuration, outbound firewall connectivity, and container logs: ```sh docker logs cloudflare-mesh ``` ### A Kubernetes Service cannot be resolved Confirm that the [hostname route](https://developers.cloudflare.com/mesh/features/routes/#hostname-routes) matches the cluster's actual DNS suffix. The usual default is `cluster.local`, producing Service names such as `service.namespace.svc.cluster.local`. ### A hostname request arrives but no response returns Check source NAT and return routing first. Verify `SRCNAT_ENABLED` is set to `true` or that your network has return routes to the Mesh IP range. ### Check node status ```sh docker exec -it cloudflare-mesh warp-cli status ``` ```sh kubectl exec cloudflare-mesh-0 -- warp-cli status ``` ## Next steps - [**Add routes**](https://developers.cloudflare.com/mesh/features/routes/) — Make subnets behind the containerized node reachable from any device on your Mesh. - [**Enable high availability**](https://developers.cloudflare.com/mesh/features/high-availability/) — Run multiple replicas for production resilience. - [**Connect from Workers**](https://developers.cloudflare.com/workers-vpc/examples/connect-to-cloudflare-mesh/) — Use VPC Network bindings to reach private services from Cloudflare Workers. - [**Tips and best practices**](https://developers.cloudflare.com/mesh/best-practices/) — Cloud VPC configuration, MTU tuning, and running alongside Cloudflare Tunnel. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/#page","headline":"Run Cloudflare Mesh in containers · Cloudflare Docs","description":"Run a Cloudflare Mesh node as a Docker container for Docker Compose, Kubernetes, and CI/CD environments.","url":"https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks","Containers","Docker","Kubernetes"]} ``` --- --- description: Recommended practices for reliable Cloudflare Mesh deployments. title: Best practices image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Best practices Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/best-practices/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Operational guidance for managing Cloudflare Mesh deployments — updating the client, configuring cloud providers, running alongside Cloudflare Tunnel, and common troubleshooting. ## Update a Mesh node Updating a Mesh node means updating the `cloudflare-warp` package on the Linux host. The node briefly disconnects during the update, which interrupts traffic routed through it. If you have [high availability](https://developers.cloudflare.com/mesh/features/high-availability/) enabled, traffic fails over to a standby replica automatically. 1. Check the current version: ```sh warp-cli --version ``` 2. Update the package: ```sh sudo apt-get update && sudo apt-get install --only-upgrade cloudflare-warp ``` 1. Check the current version: ```sh warp-cli --version ``` 2. Update the package: ```sh sudo yum update cloudflare-warp ``` 3. Verify the node has reconnected: ```sh warp-cli status ``` You should see `Status update: Connected` in the output. ## Make IP forwarding persistent IP forwarding allows a Mesh node to act as a gateway, forwarding packets between its network interface and the Cloudflare network. This is only required if the node advertises [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/) — if you are only reaching the node by its Mesh IP, forwarding is not needed. Older installations may have used `sysctl -w` for IP forwarding, which does not persist across reboots. If your node loses route connectivity after a server restart, run the following to make forwarding permanent: ```sh 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 ``` You can verify the settings are active with: ```sh sysctl net.ipv4.ip_forward net.ipv6.conf.all.forwarding net.ipv6.conf.all.accept_ra ``` New installations include this step automatically. ## Cloud VPC deployments When deploying Mesh nodes in a cloud VPC, you may need to configure additional provider settings so the node can forward traffic for other devices on the subnet. ### Google Cloud Platform (GCP) [Enable IP forwarding ↗](https://cloud.google.com/vpc/docs/using-routes#canipforward) on the VM instance where you installed the Mesh node. ### Amazon Web Services (AWS) - Disable [source/destination checking ↗](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) on the EC2 instance. - In your [subnet route table ↗](https://docs.aws.amazon.com/vpc/latest/userguide/subnet-route-tables.html), add a route for Mesh traffic (for example, `100.96.0.0/12`) pointing to the EC2 instance. ### Microsoft Azure - [Enable IP forwarding ↗](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-network-network-interface?tabs=azure-portal#enable-or-disable-ip-forwarding) on the network interface of the VM. - Add a [user-defined route ↗](https://learn.microsoft.com/en-us/azure/virtual-network/manage-route-table) for Mesh traffic pointing to the VM's private IP. ## Running Mesh on a DNS server Mesh nodes run in [Traffic and DNS mode](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/modes/), which redirects DNS queries on the host to Cloudflare Gateway. This will conflict with DNS services running on the same machine (for example, Active Directory DNS, Pi-hole, Unbound, BIND, or dnsmasq). If your server runs a DNS service, do not install the Mesh node on that host. Instead, install the node on a separate machine on the same subnet and use [CIDR routes](https://developers.cloudflare.com/mesh/features/routes/) to make the DNS server reachable. ## Running Mesh alongside other VPN or mesh software The Cloudflare One Client creates a virtual network interface and manages the system routing table. Other software that does the same — Tailscale, WireGuard, OpenVPN, Cisco AnyConnect, GlobalProtect, ZScaler, Netskope, or any traditional VPN client — will compete for control of routing. Running them simultaneously causes unpredictable behavior: traffic may flow through the wrong tunnel or fail entirely. If you are migrating to Cloudflare Mesh from another solution: 1. Uninstall or disable the other client (for example, `sudo systemctl stop tailscaled && sudo systemctl disable tailscaled` on Linux, or quit the application from the system tray on macOS/Windows). 2. Restart the machine so the Cloudflare One Client's virtual network interface takes priority in the routing table. 3. Verify connectivity by running `warp-cli status` and pinging a Mesh IP. This applies to both Mesh nodes and client devices. ## Running Mesh with Cloudflare Tunnel A Mesh node (`warp-cli`) and [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) (`cloudflared`) can run on the same Linux host. This is useful when you want to use the Mesh node as a gateway for your private network while also using Cloudflare Tunnel to publish specific applications. The Mesh node captures outbound traffic and routes it through Cloudflare, which can prevent `cloudflared` from making its required outbound connections. To resolve this, use [Split Tunnels](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/route-traffic/split-tunnels/) to exclude the hostnames and IPs listed in [Tunnel with firewall](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/configure-tunnels/tunnel-with-firewall/#required-for-tunnel-operation). Note Split Tunnels is the only supported method of running both connectors on the same machine. The Mesh node's kernel-level integration overrides manual routing configurations (`ip route add`, `iptables`). ## Routing between Mesh and Cloudflare WAN To route traffic between Cloudflare Mesh and [Cloudflare WAN](https://developers.cloudflare.com/cloudflare-wan/) (for example, reaching a Mesh node from a WAN-connected site or vice versa), your account must be on [Unified Routing mode (beta)](https://developers.cloudflare.com/cloudflare-wan/reference/traffic-steering/#unified-routing-mode-beta). Unified Routing uses a single routing fabric for all connection types (Cloudflare One Client, Cloudflare Tunnel, IPsec, GRE, CNI). Without it, Mesh and WAN connections cannot exchange traffic. ## Connect Workers to Mesh Cloudflare Workers can connect to your Mesh network using [VPC Network bindings](https://developers.cloudflare.com/workers-vpc/configuration/vpc-networks/). Bind to `cf1:network` to reach any Mesh node, client device, or subnet route in your account — without specifying a particular tunnel UUID. The same binding also handles outbound traffic to public Internet destinations: requests egress through [Cloudflare Gateway](https://developers.cloudflare.com/cloudflare-one/traffic-policies/), so your existing Zero Trust traffic policies are enforced and Worker traffic appears in Gateway DNS, HTTP, and Network logs alongside the rest of your traffic. For setup instructions and examples, refer to [Connect Workers to Cloudflare Mesh](https://developers.cloudflare.com/workers-vpc/examples/connect-to-cloudflare-mesh/). ## Source IPs for Cloudflare services When Cloudflare services (such as [Load Balancing](https://developers.cloudflare.com/load-balancing/) health checks or [Workers](https://developers.cloudflare.com/workers/)) send traffic to your private network through a Mesh node, the traffic originates from the Cloudflare source IP range (default `100.64.0.0/12`). You may need to [configure Cloudflare source IPs](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-wan/configuration/how-to/configure-cloudflare-source-ips/) to avoid IP conflicts. ## MTU and packet fragmentation Mesh nodes use encapsulation to route traffic, which adds overhead to each packet. This is especially relevant for traffic between two Mesh participants, where the packet may be encapsulated twice (once by the sending node, and again by Cloudflare before delivery to the receiving side). If source devices send packets near the maximum size (1,460 bytes or more), the double encapsulation can push packets over 1,500 bytes, causing them to be dropped. ### Recommendations - Set the MTU on source devices (servers, cameras, IoT devices) to **1,280 bytes** to ensure packets fit after encapsulation. - For TCP-only traffic, apply MSS clamping on your router with a value of **1,240 bytes** (1,280 MTU - 20 byte IP header - 20 byte TCP header). - Modern applications using [Path MTU Discovery (PMTUD) ↗](https://www.cloudflare.com/learning/network-layer/what-is-mtu/) typically handle this automatically. Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/best-practices/#page","headline":"Best practices · Cloudflare Docs","description":"Recommended practices for reliable Cloudflare Mesh deployments.","url":"https://developers.cloudflare.com/mesh/best-practices/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["Private networks"]} ``` --- --- description: Review Cloudflare Mesh availability and platform requirements. title: Platform image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/mesh/llms.txt > Use this file to discover all available pages before exploring further. # Platform Last updated Sep 16, 2026|Copy as Markdown| [View as Markdown](https://developers.cloudflare.com/mesh/platform/index.md)| [Agent setup](https://developers.cloudflare.com/agent-setup/) Cloudflare Mesh is available in beta to Cloudflare One accounts, including accounts on the Free plan. ## Platform requirements - Mesh nodes require a [supported Linux distribution](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/#linux) or the [`cloudflare/mesh` container image](https://developers.cloudflare.com/mesh/guides/run-mesh-in-containers/). - Client devices can use any [operating system supported by the Cloudflare One Client](https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/cloudflare-one-client/download/). - Mesh nodes must use the MASQUE device tunnel protocol. Hostname routes, IPv6 CIDR routes, and high availability do not work with WireGuard. - Using Cloudflare Mesh with Cloudflare WAN requires [Unified Routing mode](https://developers.cloudflare.com/cloudflare-wan/reference/traffic-steering/#unified-routing-mode-beta). For deployment recommendations and interoperability constraints, refer to [Best practices](https://developers.cloudflare.com/mesh/best-practices/). Was this helpful? YesNo ## On this page [![](https://developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/mesh/platform/#page","headline":"Platform · Cloudflare Docs","description":"Review Cloudflare Mesh availability and platform requirements.","url":"https://developers.cloudflare.com/mesh/platform/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-16","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```