The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 131 lines 4.68 KB
Raw
1 ---
2 title: Expose private origins with Tunnel
3 description: Connect a private origin to Cloudflare's edge with a Tunnel, declare its ingress rules as a Configuration resource, and point DNS at it with a proxied CNAME.
4 sidebar:
5 order: 25
6 ---
7
8 A Cloudflare Tunnel establishes an outbound connection from your
9 origin — a home lab, a Kubernetes cluster, a VM with no public IP —
10 to Cloudflare's edge. No open inbound ports, no public address. In
11 alchemy the tunnel, its routing rules, and the DNS record that
12 publishes it are all ordinary resources in one stack.
13
14 ## Create a tunnel
15
16 ```typescript
17 import * as Cloudflare from "@alchemy.run/cloudflare";
18
19 const tunnel = yield* Cloudflare.Tunnel.Tunnel("MyTunnel");
20 // Run the connector on your origin:
21 // cloudflared tunnel run --token <Redacted.value(tunnel.token)>
22 ```
23
24 The resource creates a remotely-managed `cfd_tunnel` and exposes
25 `tunnelId` plus a redacted connector `token` — hand the token to
26 `cloudflared` on the origin and it dials out to the edge. If you
27 omit `name`, a unique one is generated from the app, stage, and
28 logical ID; tunnel names are immutable, so changing the name (or
29 the `tunnelSecret`) triggers a replacement.
30
31 ## Route hostnames with a Configuration
32
33 A remotely-managed tunnel has a single routing document: an ordered
34 list of ingress rules that `cloudflared` matches top-down, first
35 match wins. The `Configuration` resource owns that document:
36
37 ```typescript
38 yield* Cloudflare.Tunnel.Configuration("Ingress", {
39 tunnelId: tunnel.tunnelId,
40 ingress: [
41 { hostname: "ui.internal", service: "http://ui.app.svc.cluster.local:80" },
42 { hostname: "api.internal", service: "http://api.app.svc.cluster.local:8080" },
43 ],
44 });
45 ```
46
47 `service` is the upstream each hostname forwards to — a private IP,
48 a Kubernetes Service DNS name, or a pseudo-service like
49 `http_status:404`. The required catch-all rule (a final entry with
50 no hostname) is appended automatically, since Cloudflare rejects a
51 config whose last rule has a hostname; override what it returns
52 with `catchAllService: "http_status:503"`.
53
54 :::note
55 For simple cases you can skip the separate resource and pass
56 `ingress` directly to the `Tunnel` itself — there, you author the
57 catch-all rule yourself (end with `{ service: "http_status:404" }`).
58 Both apply only to remotely-managed tunnels (`configSrc:
59 "cloudflare"`, the default); a `"local"` tunnel is configured by a
60 YAML file on the origin instead.
61 :::
62
63 ## Point DNS at the tunnel
64
65 Publishing a hostname through the tunnel is a proxied CNAME to
66 `<tunnelId>.cfargotunnel.com`:
67
68 ```typescript
69 yield* Cloudflare.DNS.Record("AppCname", {
70 zoneId: zone.zoneId,
71 name: "app.example.com",
72 type: "CNAME",
73 content: `${tunnel.tunnelId}.cfargotunnel.com`,
74 proxied: true,
75 });
76 ```
77
78 `proxied: true` is what makes it work — traffic must enter
79 Cloudflare's edge to be forwarded down the tunnel. See
80 [Domains & DNS](/cloudflare/networking/domains) for creating or adopting the
81 `zone` this record lives in.
82
83 ## Private hostnames and networks
84
85 For origins that should only be reachable by WARP clients — no
86 public DNS at all — route the hostname through the tunnel with a
87 `HostnameRoute`:
88
89 ```typescript
90 yield* Cloudflare.Tunnel.HostnameRoute("AppRoute", {
91 hostname: "app.internal.example.com",
92 tunnelId: tunnel.tunnelId,
93 comment: "internal wiki behind the datacenter tunnel",
94 });
95 ```
96
97 Hostname, tunnel, and comment are all mutable in place — updates
98 converge on the same route rather than replacing it. Hostnames are
99 unique per account.
100
101 To route entire private CIDR ranges — including overlapping ones —
102 create a `VirtualNetwork` and target it from a `Route`:
103
104 ```typescript
105 const vnet = yield* Cloudflare.Tunnel.VirtualNetwork("Staging", {
106 comment: "staging private network",
107 });
108
109 yield* Cloudflare.Tunnel.Route("StagingNet", {
110 tunnelId: tunnel.tunnelId,
111 network: "10.4.0.0/16",
112 virtualNetworkId: vnet.virtualNetworkId,
113 });
114 ```
115
116 Each virtual network is an isolated routing namespace, so two
117 environments can both claim `10.4.0.0/16` and WARP clients pick
118 which copy they see. Passing `vnet.virtualNetworkId` into the
119 `Route` also gets destroy ordering right — a virtual network can't
120 be deleted while routes still reference it.
121
122 ## Where next
123
124 - [Domains & DNS](/cloudflare/networking/domains) — the zone and records the
125 tunnel CNAME lives in.
126 - [Tunnel API reference](/providers/cloudflare/tunnel/tunnel) —
127 including the `ReadTunnel` / `WriteTunnel` / `ReadWriteTunnel`
128 bindings for managing tunnels from inside a deployed Worker.
129 - [Configuration API reference](/providers/cloudflare/tunnel/configuration)
130 - [HostnameRoute API reference](/providers/cloudflare/tunnel/hostnameroute)
131 - [VirtualNetwork API reference](/providers/cloudflare/tunnel/virtualnetwork)