1# Workers VPC Connectivity
2 
3Connect Cloudflare Workers to private networks and internal infrastructure using TCP Sockets.
4 
5## Overview
6 
7Workers VPC connectivity enables outbound TCP connections from Workers to private resources in AWS, Azure, GCP, on-premises datacenters, or any private network. This is achieved through the **TCP Sockets API** (`cloudflare:sockets`), which provides low-level network access for custom protocols and services.
8 
9**Key capabilities:**
10- Direct TCP connections to private IPs and hostnames
11- TLS/StartTLS support for encrypted connections
12- Integration with Cloudflare Tunnel for secure private network access
13- Full control over wire protocols (database protocols, SSH, MQTT, custom TCP)
14 
15**Note:** This reference documents the TCP Sockets API. For the newer Workers VPC Services product (HTTP-only service bindings with built-in SSRF protection), refer to separate documentation when available. VPC Services is currently in beta (2025+).
16 
17## Quick Decision: Which Technology?
18 
19Need private network connectivity from Workers?
20 
21| Requirement | Use | Why |
22|------------|-----|-----|
23| HTTP/HTTPS APIs in private network | VPC Services (beta, separate docs) | SSRF-safe, declarative bindings |
24| PostgreSQL/MySQL databases | [Hyperdrive](../hyperdrive/) | Connection pooling, caching, optimized |
25| Custom TCP protocols (SSH, MQTT, proprietary) | **TCP Sockets (this doc)** | Full protocol control |
26| Simple HTTP with lowest latency | TCP Sockets + [Smart Placement](../smart-placement/) | Manual optimization |
27| Expose on-prem to internet (inbound) | [Cloudflare Tunnel](../tunnel/) | Not Worker-specific |
28 
29## When to Use TCP Sockets
30 
31**Use TCP Sockets when you need:**
32- ✅ Direct control over wire protocols (e.g., Postgres wire protocol, SSH, Redis RESP)
33- ✅ Non-HTTP protocols (MQTT, SMTP, custom binary protocols)
34- ✅ StartTLS or custom TLS negotiation
35- ✅ Streaming binary data over TCP
36 
37**Don't use TCP Sockets when:**
38- ❌ You just need HTTP/HTTPS (use `fetch()` or VPC Services)
39- ❌ You need PostgreSQL/MySQL (use Hyperdrive for pooling)
40- ❌ You need WebSocket (use native Workers WebSocket)
41 
42## Quick Start
43 
44```typescript
45import { connect } from 'cloudflare:sockets';
46 
47export default {
48  async fetch(req: Request): Promise<Response> {
49    // Connect to private service
50    const socket = connect(
51      { hostname: "db.internal.company.net", port: 5432 },
52      { secureTransport: "on" }
53    );
54 
55    try {
56      await socket.opened; // Wait for connection
57      
58      const writer = socket.writable.getWriter();
59      await writer.write(new TextEncoder().encode("QUERY\r\n"));
60      await writer.close();
61 
62      const reader = socket.readable.getReader();
63      const { value } = await reader.read();
64      
65      return new Response(value);
66    } finally {
67      await socket.close();
68    }
69  }
70};
71```
72 
73## Architecture Pattern: Workers + Tunnel
74 
75Most private network connectivity combines TCP Sockets with Cloudflare Tunnel:
76 
77```
78┌─────────┐     ┌─────────────┐     ┌──────────────┐     ┌─────────────┐
79│ Worker  │────▶│ TCP Socket  │────▶│   Tunnel     │────▶│   Private   │
80│         │     │ (this API)  │     │ (cloudflared)│     │   Network   │
81└─────────┘     └─────────────┘     └──────────────┘     └─────────────┘
82```
83 
841. Worker opens TCP socket to Tunnel hostname
852. Tunnel endpoint routes to private IP
863. Response flows back through Tunnel to Worker
87 
88See [configuration.md](./configuration.md) for Tunnel setup details.
89 
90## Reading Order
91 
921. **Start here (README.md)** - Overview and decision guide
932. **[api.md](./api.md)** - Socket interface, types, methods
943. **[configuration.md](./configuration.md)** - Wrangler setup, Tunnel integration
954. **[patterns.md](./patterns.md)** - Real-world examples (databases, protocols, error handling)
965. **[gotchas.md](./gotchas.md)** - Limits, blocked ports, common errors
97 
98## Key Limits
99 
100| Limit | Value |
101|-------|-------|
102| Max concurrent sockets per request | 6 |
103| Blocked destinations | Cloudflare IPs, localhost, port 25 |
104| Scope requirement | Must create in handler (not global) |
105 
106See [gotchas.md](./gotchas.md) for complete limits and troubleshooting.
107 
108## Best Practices
109 
1101. **Always close sockets** - Use try/finally blocks
1112. **Validate destinations** - Prevent SSRF by allowlisting hosts
1123. **Use Hyperdrive for databases** - Better performance than raw TCP
1134. **Prefer fetch() for HTTP** - Only use TCP when necessary
1145. **Combine with Smart Placement** - Reduce latency to private networks
115 
116## Related Technologies
117 
118- **[Hyperdrive](../hyperdrive/)** - PostgreSQL/MySQL with connection pooling
119- **[Cloudflare Tunnel](../tunnel/)** - Secure private network access
120- **[Smart Placement](../smart-placement/)** - Auto-locate Workers near backends
121- **VPC Services (beta)** - HTTP-only service bindings with SSRF protection (separate docs)
122 
123## Reference
124 
125- [TCP Sockets API Documentation](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/)
126- [Connect to databases guide](https://developers.cloudflare.com/workers/tutorials/connect-to-postgres/)
127- [Cloudflare Tunnel setup](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
128