cloudflare · aberglund-cf · May 12, 2026
@@ -185,6 +185,103 @@ To prevent issues with DNS resolution for a Spectrum application, do not use the
 
 </Details>
 
+## Create a Spectrum application using a virtual network (private origin)
+
+To proxy TCP or UDP traffic to an origin on your private network, attach a Cloudflare Tunnel [virtual network](/cloudflare-one/networks/virtual-networks/) to a Spectrum application. Spectrum routes traffic through the connector (Cloudflare Tunnel or Cloudflare WAN connection) associated with that virtual network. This replaces the previous pattern of putting a load balancer in front of a private origin.
+
+Virtual network origins are only supported for TCP and UDP applications. The origin must be a single private IP routable within the specified virtual network. Port ranges, hostname origins (`origin_dns`), and multiple addresses in `origin_direct` are not supported. For details on validation errors, refer to [Error codes](/spectrum/reference/error-codes/).
+
+For a primer on virtual networks, refer to [Virtual networks](/cloudflare-one/networks/virtual-networks/).
+
+### Before you begin
+
+Set up the virtual network and a route covering your origin IP before creating the Spectrum application:
+
+- Create a virtual network and a Cloudflare Tunnel that carries it by following [Manage virtual networks](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/tunnel-virtual-networks/).
+- Attach a route covering your origin's private IP to the tunnel by following [Connect an IP/CIDR](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/).
+
+For Cloudflare WAN (formerly Magic WAN) as the connector, refer to [Get started with Cloudflare WAN](/cloudflare-wan/get-started/) for setting up tunnel endpoints and routes.
+
+<Details header="Add your application via Dashboard">
+
+1. In the Cloudflare dashboard, go to the **Spectrum** page.
+
+   <DashButton url="/?to=/:account/:zone/spectrum" />
+
+2. Select **Create an Application**.
+3. Under **Application Type**, select **TCP** or **UDP**.
+4. Under **Domain**, enter the domain that will use Spectrum.
+5. Under **Edge Port**, enter the port Cloudflare should use for your application.
+6. Under **Origin**, select **Virtual Network (private origin)**.
+7. Under **Virtual Network**, select the virtual network that contains your origin.
+8. Under **IP**, enter the private IP address of your origin.
+9. Under **Port**, enter a single port (port ranges are not supported).
+10. Select **Add**.
+
+</Details>
+
+<Details header="Add your application via API">
+
+Below is a curl example and the associated data being posted to the API.
+
+**API example:**
+
+<APIRequest
+	path="/zones/{zone_id}/spectrum/apps"
+	method="POST"
+	json={{
+		protocol: "tcp/22",
+		dns: {
+			type: "CNAME",
+			name: "ssh.example.com",
+		},
+		origin_direct: ["tcp://10.0.0.5:22"],
+		virtual_network_id: "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
+		proxy_protocol: "off",
+		ip_firewall: true,
+		tls: "off",
+		edge_ips: {
+			type: "dynamic",
+			connectivity: "all",
+		},
+		traffic_type: "direct",
+	}}
+/>
+
+Set `origin_direct` to the private IP of your origin and `virtual_network_id` to the ID of the virtual network that the IP is routable within. You can list virtual networks for your account with the [List virtual networks](/api/resources/zero_trust/subresources/networks/subresources/virtual_networks/methods/list/) endpoint.
+
+**Example data:**
+
+```json
+{
+	"success": true,
+	"errors": [],
+	"messages": [],
+	"result": {
+		"id": "ea95132c15732412d22c1476fa83f27a",
+		"protocol": "tcp/22",
+		"dns": {
+			"type": "CNAME",
+			"name": "ssh.example.com"
+		},
+		"origin_direct": ["tcp://10.0.0.5:22"],
+		"virtual_network_id": "f70ff985-a4ef-4643-bbbc-4a0ed4fc8415",
+		"proxy_protocol": "off",
+		"ip_firewall": true,
+		"tls": "off",
+		"edge_ips": {
+			"type": "dynamic",
+			"connectivity": "all"
+		},
+		"traffic_type": "direct",
+		"created_on": "2014-01-02T02:20:00Z",
+		"modified_on": "2014-01-02T02:20:00Z"
+	}
+}
+```
+
+</Details>
+
 ## View traffic
 
 You can now proxy traffic through Cloudflare without additional configuration. As you run traffic through Cloudflare, you will see the last minute of traffic from **Spectrum** in the dashboard.

@@ -94,6 +94,22 @@ Network analytics data for Spectrum does not reflect the outcomes of IP Access r
 
 Once Argo Smart Routing is enabled for your application, traffic will automatically be routed through the fastest and most reliable network path available. Argo Smart Routing is available for TCP and UDP (beta) applications.
 
+## Virtual network origin
+
+Spectrum applications can route `origin_direct` traffic to a private origin through a Cloudflare Tunnel [virtual network](/cloudflare-one/networks/virtual-networks/). Set `virtual_network_id` on the application to the ID of the virtual network that the origin IP is routable within. Traffic to the application is delivered through the connector associated with that virtual network — typically a [Cloudflare Tunnel](/cloudflare-one/networks/connectors/cloudflare-tunnel/) or a [Cloudflare WAN](/cloudflare-wan/) (formerly Magic WAN) connection.
+
+To create the virtual network and attach a route covering your origin IP, refer to [Manage virtual networks](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/tunnel-virtual-networks/) and [Connect an IP/CIDR](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/).
+
+The following restrictions apply when `virtual_network_id` is set:
+
+- Application type must be TCP or UDP. HTTP/HTTPS applications do not support virtual network origins.
+- The origin must be specified with `origin_direct`. Hostname origins (`origin_dns`) are not supported.
+- `origin_direct` must contain exactly one address. Multiple addresses are not supported.
+- The origin port must be a single port. Port ranges are not supported.
+- The origin IP must be routable within the specified virtual network. The virtual network must already have a route covering the IP.
+
+For the validation error codes returned when these constraints are violated, refer to [Error codes](/spectrum/reference/error-codes/).
+
 ## Edge TLS Termination
 
 If you enable **Edge TLS Termination** for a Spectrum application, Cloudflare will encrypt traffic for the application at the Edge. The Edge TLS Termination toggle applies only to TCP applications.

@@ -0,0 +1,67 @@
+---
+pcx_content_type: reference
+title: Error codes
+description: Error codes returned by the Cloudflare Spectrum API.
+products:
+  - spectrum
+---
+
+This page documents validation error codes returned by the [Spectrum API](/api/resources/spectrum/subresources/apps/) when creating or updating Spectrum applications.
+
+## How errors are returned
+
+Spectrum API errors follow the standard Cloudflare v4 error envelope. The response body includes an `errors` array with `code` and `message` fields:
+
+```json
+{
+  "errors": [
+    {
+      "code": 11044,
+      "message": "no matching routes in the specified virtual network"
+    }
+  ],
+  "messages": [],
+  "success": false,
+  "result": null
+}
+```
+
+Look up the `code` in the sections below for the cause and resolution.
+
+## Virtual network origin errors
+
+The following codes are returned by `POST /zones/:zone/spectrum/apps` and `PATCH /zones/:zone/spectrum/apps/:id` when validating an application that uses a [virtual network origin](/spectrum/reference/configuration-options/#virtual-network-origin).
+
+### Virtual network requires origin direct (11041)
+
+`virtual_network_id` was set on a request that uses `origin_dns`. Virtual network origins are only supported with IP-based origins.
+
+**Resolution:** Replace `origin_dns` with `origin_direct` and provide the private IP and single port that the virtual network routes to.
+
+### Virtual network requires single origin (11042)
+
+`origin_direct` contained more than one address. Virtual network origins must resolve to a single private IP and port.
+
+**Resolution:** Reduce `origin_direct` to a single entry of the form `tcp://<ip>:<port>` or `udp://<ip>:<port>`.
+
+### Virtual network no port range (11043)
+
+`origin_port` was set to a range. Virtual network origins do not support port ranges.
+
+**Resolution:** Use a single port instead of a range. If you need to expose multiple ports, create a separate Spectrum application per port.
+
+### Virtual network route not found (11044)
+
+The combination of IP and `virtual_network_id` does not match any route in the specified virtual network. This covers two cases: the virtual network does not exist, or the IP is not routable within the virtual network you specified.
+
+**Resolution:**
+
+- Confirm `virtual_network_id` matches a virtual network on your account. You can list virtual networks with the [List virtual networks](/api/resources/zero_trust/subresources/networks/subresources/virtual_networks/) endpoint.
+- Confirm the origin IP is within a route attached to that virtual network. You can list routes with the [List network routes](/api/resources/zero_trust/subresources/networks/subresources/routes/) endpoint.
+- If no matching route exists, add one by following [Connect an IP/CIDR](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/connect-cidr/).
+
+### Virtual network invalid UUID (11045)
+
+`virtual_network_id` is not a valid UUID.
+
+**Resolution:** Provide a UUID. Virtual network IDs are returned by the [List virtual networks](/api/resources/zero_trust/subresources/networks/subresources/virtual_networks/methods/list/) endpoint in the `id` field of each entry.