cloudflare-vpc-services

Q: How do I install cloudflare-vpc-services?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill cloudflare-vpc-services in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cloudflare-vpc-services/ (personal) or .claude/skills/cloudflare-vpc-services/ (project).

Q: Which AI agents can use cloudflare-vpc-services?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Q: Is cloudflare-vpc-services safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Q: Who maintains cloudflare-vpc-services?

It is published by nodnarbnitram in nodnarbnitram/claude-code-extensions. It has 67 recorded installs.

by nodnarbnitramDevOps & Cloud

Diagnose and create Cloudflare VPC Services for Workers to access private APIs in AWS, Azure, GCP, or on-premise networks. Use when troubleshooting dnserror, configuring cloudflared tunnels, setting up VPC service bindings, or routing Workers to internal services.

Installs: 67
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill cloudflare-vpc-services

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads cloudflare-vpc-services automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Cloudflare VPC Services

Enable Workers to securely access private APIs and services through encrypted tunnels without public internet exposure.

⚠️ BEFORE YOU START

This skill prevents 5 common errors and saves ~60% tokens.

Metric	Without Skill	With Skill
Setup Time	45+ min	10 min
Common Errors	5	0
Token Usage	~8000	~3000

Known Issues This Skill Prevents

dns_error from outdated cloudflared version or wrong protocol
Requests leaving VPC due to using public hostnames instead of internal
Port mismatch - fetch() port is ignored, service config port is used
Missing absolute URLs in fetch() calls
Incorrect tunnel ID or service binding configuration

Quick Start

Step 1: Verify Tunnel Requirements

# Check cloudflared version on remote infrastructure (K8s, EC2, etc.)
# Must be 2025.7.0 or later
cloudflared --version

# Verify QUIC protocol is configured (not http2)
# Check tunnel config or Cloudflare dashboard

Why this matters: Workers VPC requires cloudflared 2025.7.0+ with QUIC protocol. Older versions or http2 protocol cause dns_error.

Step 2: Create VPC Service

# Use Cloudflare API or dashboard to create VPC service
# See templates/vpc-service-ip.json or templates/vpc-service-hostname.json

Why this matters: The VPC service defines the actual target (IP/hostname) that the tunnel routes to. The fetch() URL only sets Host header and SNI.

Step 3: Configure Wrangler Binding

// wrangler.jsonc
{
  "vpc_services": [
    {
      "binding": "PRIVATE_API",
      "service_id": "<YOUR_SERVICE_ID>",
      "remote": true
    }
  ]
}

Why this matters: The binding name becomes the environment variable used in Worker code: env.PRIVATE_API.fetch().

Critical Rules

✅ Always Do

✅ Use absolute URLs with protocol, host, and path in fetch()
✅ Use internal VPC hostnames, not public endpoints
✅ Ensure cloudflared is 2025.7.0+ with QUIC protocol
✅ Allow UDP port 7844 outbound for QUIC connections

❌ Never Do

❌ Use port numbers in fetch() URL (they're ignored)
❌ Use public hostnames for services inside VPC
❌ Assume http2 protocol works (only QUIC is supported)
❌ Use relative URLs in fetch()

Common Mistakes

❌ Wrong:

// Port is ignored, relative URL fails
const response = await env.VPC_SERVICE.fetch("/api/users:8080");

✅ Correct:

// Absolute URL, port configured in VPC service
const response = await env.VPC_SERVICE.fetch("https://internal-api.company.local/api/users");

Why: The VPC service configuration determines actual routing. The fetch() URL only populates the Host header and SNI value.

Known Issues Prevention

Issue	Root Cause	Solution
`dns_error`	cloudflared < 2025.7.0 or http2 protocol	Update cloudflared, configure QUIC, allow UDP 7844
Requests go to public internet	Using public hostname in fetch()	Use internal VPC hostname
Connection refused	Wrong port in VPC service config	Configure correct http_port/https_port in service
Timeout	Tunnel not running or wrong tunnel_id	Verify tunnel status, check tunnel_id
404 errors	Incorrect path routing	Verify internal service path matches fetch() path

Configuration Reference

wrangler.jsonc

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "vpc_services": [
    {
      "binding": "PRIVATE_API",
      "service_id": "daf43e8c-a81a-4242-9912-4a2ebe4fdd79",
      "remote": true
    },
    {
      "binding": "PRIVATE_DATABASE",
      "service_id": "453b6067-1327-420d-89b3-2b6ad16e6551",
      "remote": true
    }
  ]
}

Key settings:

binding: Environment variable name for accessing the service
service_id: UUID from VPC service creation
remote: Must be true for VPC services

Common Patterns

Basic GET Request

export default {
  async fetch(request, env) {
    const response = await env.PRIVATE_API.fetch(
      "https://internal-api.company.local/users"
    );
    return response;
  }
};

POST with Authentication

const response = await env.PRIVATE_API.fetch(
  "https://internal-api.company.local/users",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${env.API_TOKEN}`
    },
    body: JSON.stringify({ name: "John", email: "john@example.com" })
  }
);

API Gateway with Path Routing

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/api/users')) {
      return env.USER_SERVICE.fetch(
        `https://user-api.internal${url.pathname}`
      );
    } else if (url.pathname.startsWith('/api/orders')) {
      return env.ORDER_SERVICE.fetch(
        `https://orders-api.internal${url.pathname}`
      );
    }

    return new Response('Not Found', { status: 404 });
  }
};

Bundled Resources

Templates

Located in templates/:

wrangler-vpc.jsonc - Ready-to-use wrangler config with VPC bindings
vpc-service-ip.json - IP-based VPC service API payload
vpc-service-hostname.json - Hostname-based VPC service API payload

Copy these templates as starting points for your implementation.

Scripts

Located in scripts/:

list-vpc-services.sh - List VPC services via Cloudflare API
tail-worker.sh - Debug VPC connections with live logs
set-api-token.sh - Set secrets for private API auth

References

Located in references/:

api-patterns.md - Comprehensive fetch() patterns and examples

Dependencies

Required

Package	Version	Purpose
wrangler	latest	Deploy Workers with VPC bindings
cloudflared	2025.7.0+	Tunnel daemon (on remote infrastructure)

Optional

Package	Version	Purpose
@cloudflare/workers-types	latest	TypeScript types for Workers

Official Documentation

Troubleshooting

dns_error when calling VPC service

Symptoms: Worker returns dns_error when calling env.VPC_SERVICE.fetch()

Solution:

Update cloudflared to 2025.7.0+ on remote infrastructure
Configure QUIC protocol (not http2)
Allow UDP port 7844 outbound

Requests going to public internet

Symptoms: Logs show requests hitting public endpoints instead of internal

Solution:

// Use internal hostname
const response = await env.VPC_SERVICE.fetch(
  "https://internal-api.vpc.local/endpoint"  // Internal
  // NOT "https://api.company.com/endpoint"   // Public
);

Connection timeout

Symptoms: Requests hang and eventually timeout

Solution:

Verify tunnel is running: check cloudflared logs
Verify tunnel_id matches in VPC service config
Check network connectivity from tunnel to target

Setup Checklist

Before using this skill, verify:

cloudflared 2025.7.0+ deployed on remote infrastructure
QUIC protocol configured (not http2)
UDP port 7844 outbound allowed
VPC service created with correct tunnel_id
wrangler.jsonc has vpc_services binding
Using internal hostnames (not public endpoints)
Using absolute URLs in fetch() calls

FAQ

What does the cloudflare-vpc-services skill do?

How do I install cloudflare-vpc-services?

Run npx skills add https://github.com/nodnarbnitram/claude-code-extensions --skill cloudflare-vpc-services in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cloudflare-vpc-services/ (personal) or .claude/skills/cloudflare-vpc-services/ (project).

Which AI agents can use cloudflare-vpc-services?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is cloudflare-vpc-services safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains cloudflare-vpc-services?

It is published by nodnarbnitram in nodnarbnitram/claude-code-extensions. It has 67 recorded installs.