Cloudflare.MagicTransit reference

MagicApp

Source: src/Cloudflare/MagicTransit/App.ts

A custom Magic WAN app — a named set of hostnames and/or IP subnets used for traffic steering and policy decisions, complementing Cloudflare’s managed app definitions.

Requires a Magic WAN subscription — accounts without it receive a typed MagicWanUnauthorized error (Cloudflare code 1025).

All properties are mutable in place via PATCH.

MagicApp: Creating an app

App matching hostnames

const app = yield* Cloudflare.MagicTransit.MagicApp("crm", {
  name: "Internal CRM",
  type: "Business",
  hostnames: ["crm.example.com"],
});

App matching IP subnets

const app = yield* Cloudflare.MagicTransit.MagicApp("voip", {
  name: "VoIP",
  type: "Communication",
  ipSubnets: ["192.0.2.0/24", "198.51.100.0/24"],
});

GreTunnel

Source: src/Cloudflare/MagicTransit/GreTunnel.ts

A Magic Transit / Magic WAN GRE tunnel between Cloudflare and a customer router.

Requires a Magic Transit or Magic WAN subscription on the account — accounts that are not onboarded receive a typed MagicTransitNotOnboarded error (Cloudflare code 1012).

The tunnel name is its routing identity (unique, ≤15 chars) — changing it triggers a replacement, as does changing bgp (the update API cannot modify BGP settings). Everything else is updated in place via PUT.

GreTunnel: Creating a GRE tunnel

Basic tunnel

const tunnel = yield* Cloudflare.MagicTransit.GreTunnel("office", {
  name: "office-gre-1",
  cloudflareGreEndpoint: "203.0.113.1",
  customerGreEndpoint: "198.51.100.1",
  interfaceAddress: "10.213.0.8/31",
});

Tunnel with health checks and MTU

const tunnel = yield* Cloudflare.MagicTransit.GreTunnel("office", {
  name: "office-gre-1",
  cloudflareGreEndpoint: "203.0.113.1",
  customerGreEndpoint: "198.51.100.1",
  interfaceAddress: "10.213.0.8/31",
  mtu: 1476,
  ttl: 64,
  healthCheck: { enabled: true, rate: "mid", type: "reply" },
});

GreTunnel: Routing traffic over the tunnel

yield* Cloudflare.MagicTransit.MagicStaticRoute("office-route", {
  prefix: "10.100.0.0/24",
  nexthop: "10.213.0.9",
  priority: 100,
});

IpsecTunnel

Source: src/Cloudflare/MagicTransit/IpsecTunnel.ts

A Magic Transit / Magic WAN IPsec tunnel between Cloudflare and a customer device.

Requires a Magic Transit or Magic WAN subscription on the account — accounts that are not onboarded receive a typed MagicTransitNotOnboarded error (Cloudflare code 1012).

The tunnel name is unique per account and immutable in practice — changing it triggers a replacement. The psk is write-only: Cloudflare never returns it, so the configured value is carried in state.

IpsecTunnel: Creating an IPsec tunnel

Basic tunnel with a provided PSK

const tunnel = yield* Cloudflare.MagicTransit.IpsecTunnel("branch", {
  name: "branch-ipsec-1",
  cloudflareEndpoint: "203.0.113.1",
  customerEndpoint: "198.51.100.1",
  interfaceAddress: "10.213.0.10/31",
  psk: yield* Config.Redacted("IPSEC_PSK"),
});

Tunnel with replay protection and health checks

const tunnel = yield* Cloudflare.MagicTransit.IpsecTunnel("branch", {
  name: "branch-ipsec-1",
  cloudflareEndpoint: "203.0.113.1",
  interfaceAddress: "10.213.0.10/31",
  replayProtection: true,
  healthCheck: { enabled: true, rate: "mid" },
});

MagicSite

Source: src/Cloudflare/MagicTransit/Site.ts

A Magic WAN site — represents a physical or logical network location (typically backed by a Magic WAN Connector appliance) under which LANs, WANs, and ACLs are configured.

Requires a Magic WAN subscription — accounts without it receive a typed MagicWanUnauthorized error (Cloudflare code 1025).

haMode is create-only — changing it triggers a replacement. Everything else is updated in place.

MagicSite: Creating a site

Basic site

const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {
  description: "Headquarters",
  location: { lat: "37.7749", lon: "-122.4194" },
});

Site with LAN and WAN

const site = yield* Cloudflare.MagicTransit.MagicSite("hq", {});

const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
  siteId: site.siteId,
  physport: 1,
});

const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
  siteId: site.siteId,
  physport: 2,
  vlanTag: 0,
});

MagicSiteAcl

Source: src/Cloudflare/MagicTransit/SiteAcl.ts

An ACL between two LANs of a Magic WAN site — allows traffic between LAN segments behind a Magic WAN Connector (all inter-LAN traffic is denied by default).

Requires a Magic WAN subscription — accounts without it receive a typed MagicWanUnauthorized error (Cloudflare code 1025).

siteId is create-only — changing it triggers a replacement. Everything else is updated in place.

MagicSiteAcl: Creating an ACL

Allow TCP between two LANs

yield* Cloudflare.MagicTransit.MagicSiteAcl("lan-to-lan", {
  siteId: site.siteId,
  name: "office-to-lab",
  lan1: { lanId: officeLan.lanId, ports: [443] },
  lan2: { lanId: labLan.lanId },
  protocols: ["tcp"],
});

Unidirectional ACL forwarded locally

yield* Cloudflare.MagicTransit.MagicSiteAcl("one-way", {
  siteId: site.siteId,
  name: "sensors-to-collector",
  lan1: { lanId: sensorsLan.lanId },
  lan2: { lanId: collectorLan.lanId, ports: [9000] },
  unidirectional: true,
  forwardLocally: true,
});

MagicSiteLan

Source: src/Cloudflare/MagicTransit/SiteLan.ts

A LAN attached to a Magic WAN site — describes a local network segment behind a Magic WAN Connector port (VLAN, addressing, routed subnets, NAT).

Requires a Magic WAN subscription — accounts without it receive a typed MagicWanUnauthorized error (Cloudflare code 1025).

siteId and haLink are create-only — changing either triggers a replacement. Everything else is updated in place.

MagicSiteLan: Creating a LAN

Untagged LAN with DHCP

const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
  siteId: site.siteId,
  physport: 2,
  vlanTag: 0,
});

LAN with static addressing and a routed subnet

const lan = yield* Cloudflare.MagicTransit.MagicSiteLan("hq-lan", {
  siteId: site.siteId,
  physport: 2,
  vlanTag: 10,
  staticAddressing: { address: "192.168.10.1/24" },
  routedSubnets: [
    { prefix: "10.10.0.0/24", nextHop: "192.168.10.254" },
  ],
});

MagicSiteWan

Source: src/Cloudflare/MagicTransit/SiteWan.ts

A WAN attached to a Magic WAN site — describes an uplink on a Magic WAN Connector port (addressing, VLAN, load-balancing priority). Cloudflare automatically creates IPsec tunnels over each WAN.

Requires a Magic WAN subscription — accounts without it receive a typed MagicWanUnauthorized error (Cloudflare code 1025).

siteId is create-only — changing it triggers a replacement. Everything else is updated in place.

MagicSiteWan: Creating a WAN

DHCP uplink

const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
  siteId: site.siteId,
  physport: 1,
});

Static uplink with priority

const wan = yield* Cloudflare.MagicTransit.MagicSiteWan("hq-wan", {
  siteId: site.siteId,
  physport: 1,
  priority: 10,
  staticAddressing: {
    address: "203.0.113.10/24",
    gatewayAddress: "203.0.113.1",
  },
});

MagicStaticRoute

Source: src/Cloudflare/MagicTransit/StaticRoute.ts

A Magic Transit / Magic WAN static route — steers traffic for a prefix to a next-hop (usually a Magic tunnel interface address).

Requires a Magic Transit or Magic WAN subscription on the account — accounts that are not onboarded receive a typed MagicTransitNotOnboarded error (Cloudflare code 1012).

All properties are mutable in place via PUT. A route’s practical identity is the (prefix, nexthop, priority) triple — when state is lost, read scans for a matching route and reports it as Unowned so takeover is gated behind --adopt.

MagicStaticRoute: Creating a static route

Route a prefix over a GRE tunnel

const tunnel = yield* Cloudflare.MagicTransit.GreTunnel("office", {
  name: "office-gre-1",
  cloudflareGreEndpoint: "203.0.113.1",
  customerGreEndpoint: "198.51.100.1",
  interfaceAddress: "10.213.0.8/31",
});

yield* Cloudflare.MagicTransit.MagicStaticRoute("office-route", {
  prefix: "10.100.0.0/24",
  nexthop: "10.213.0.9",
  priority: 100,
});

ECMP route scoped to a region

yield* Cloudflare.MagicTransit.MagicStaticRoute("ecmp-route", {
  prefix: "10.100.0.0/24",
  nexthop: "10.213.0.9",
  priority: 100,
  weight: 50,
  scope: { coloRegions: ["ENAM"] },
});