cloudflare-deploy

Original source / Raw SKILL.md

---
name: cloudflare-deploy
description: Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.
metadata:
  author: github.com/openai/skills
  version: '1.0.0'
---

# Cloudflare Deploy

Consolidated skill for building on the Cloudflare platform. Use decision trees below to find the right product, then load detailed references.

## Prerequisites

- When sandboxing blocks the deployment network calls, rerun with `sandbox_permissions=require_escalated`.
- The deployment might take a few minutes. Use appropriate timeout values.

## Authentication (Required Before Deploy)

Verify auth before `wrangler deploy`, `wrangler pages deploy`, or `npm run deploy`:

```bash
npx wrangler whoami    # Shows account if authenticated
```

Not authenticated? → `references/wrangler/auth.md`

- Interactive/local: `wrangler login` (one-time OAuth)
- CI/CD: Set `CLOUDFLARE_API_TOKEN` env var

## Quick Decision Trees

### "I need to run code"

```
Need to run code?
├─ Serverless functions at the edge → workers/
├─ Full-stack web app with Git deploys → pages/
├─ Stateful coordination/real-time → durable-objects/
├─ Long-running multi-step jobs → workflows/
├─ Run containers → containers/
├─ Multi-tenant (customers deploy code) → workers-for-platforms/
├─ Scheduled tasks (cron) → cron-triggers/
├─ Lightweight edge logic (modify HTTP) → snippets/
├─ Process Worker execution events (logs/observability) → tail-workers/
└─ Optimize latency to backend infrastructure → smart-placement/
```

### "I need to store data"

```
Need storage?
├─ Key-value (config, sessions, cache) → kv/
├─ Relational SQL → d1/ (SQLite) or hyperdrive/ (existing Postgres/MySQL)
├─ Object/file storage (S3-compatible) → r2/
├─ Message queue (async processing) → queues/
├─ Vector embeddings (AI/semantic search) → vectorize/
├─ Strongly-consistent per-entity state → durable-objects/ (DO storage)
├─ Secrets management → secrets-store/
├─ Streaming ETL to R2 → pipelines/
└─ Persistent cache (long-term retention) → cache-reserve/
```

### "I need AI/ML"

```
Need AI?
├─ Run inference (LLMs, embeddings, images) → workers-ai/
├─ Vector database for RAG/search → vectorize/
├─ Build stateful AI agents → agents-sdk/
├─ Gateway for any AI provider (caching, routing) → ai-gateway/
└─ AI-powered search widget → ai-search/
```

### "I need networking/connectivity"

```
Need networking?
├─ Expose local service to internet → tunnel/
├─ TCP/UDP proxy (non-HTTP) → spectrum/
├─ WebRTC TURN server → turn/
├─ Private network connectivity → network-interconnect/
├─ Optimize routing → argo-smart-routing/
├─ Optimize latency to backend (not user) → smart-placement/
└─ Real-time video/audio → realtimekit/ or realtime-sfu/
```

### "I need security"

```
Need security?
├─ Web Application Firewall → waf/
├─ DDoS protection → ddos/
├─ Bot detection/management → bot-management/
├─ API protection → api-shield/
├─ CAPTCHA alternative → turnstile/
└─ Credential leak detection → waf/ (managed ruleset)
```

### "I need media/content"

```
Need media?
├─ Image optimization/transformation → images/
├─ Video streaming/encoding → stream/
├─ Browser automation/screenshots → browser-rendering/
└─ Third-party script management → zaraz/
```

### "I need infrastructure-as-code"

```
Need IaC? → pulumi/ (Pulumi), terraform/ (Terraform), or api/ (REST API)
```

## Product Index

### Compute & Runtime

| Product               | Reference                           |
| --------------------- | ----------------------------------- |
| Workers               | `references/workers/`               |
| Pages                 | `references/pages/`                 |
| Pages Functions       | `references/pages-functions/`       |
| Durable Objects       | `references/durable-objects/`       |
| Workflows             | `references/workflows/`             |
| Containers            | `references/containers/`            |
| Workers for Platforms | `references/workers-for-platforms/` |
| Cron Triggers         | `references/cron-triggers/`         |
| Tail Workers          | `references/tail-workers/`          |
| Snippets              | `references/snippets/`              |
| Smart Placement       | `references/smart-placement/`       |

### Storage & Data

| Product         | Reference                     |
| --------------- | ----------------------------- |
| KV              | `references/kv/`              |
| D1              | `references/d1/`              |
| R2              | `references/r2/`              |
| Queues          | `references/queues/`          |
| Hyperdrive      | `references/hyperdrive/`      |
| DO Storage      | `references/do-storage/`      |
| Secrets Store   | `references/secrets-store/`   |
| Pipelines       | `references/pipelines/`       |
| R2 Data Catalog | `references/r2-data-catalog/` |
| R2 SQL          | `references/r2-sql/`          |

### AI & Machine Learning

| Product    | Reference                |
| ---------- | ------------------------ |
| Workers AI | `references/workers-ai/` |
| Vectorize  | `references/vectorize/`  |
| Agents SDK | `references/agents-sdk/` |
| AI Gateway | `references/ai-gateway/` |
| AI Search  | `references/ai-search/`  |

### Networking & Connectivity

| Product              | Reference                          |
| -------------------- | ---------------------------------- |
| Tunnel               | `references/tunnel/`               |
| Spectrum             | `references/spectrum/`             |
| TURN                 | `references/turn/`                 |
| Network Interconnect | `references/network-interconnect/` |
| Argo Smart Routing   | `references/argo-smart-routing/`   |
| Workers VPC          | `references/workers-vpc/`          |

### Security

| Product         | Reference                    |
| --------------- | ---------------------------- |
| WAF             | `references/waf/`            |
| DDoS Protection | `references/ddos/`           |
| Bot Management  | `references/bot-management/` |
| API Shield      | `references/api-shield/`     |
| Turnstile       | `references/turnstile/`      |

### Media & Content

| Product           | Reference                       |
| ----------------- | ------------------------------- |
| Images            | `references/images/`            |
| Stream            | `references/stream/`            |
| Browser Rendering | `references/browser-rendering/` |
| Zaraz             | `references/zaraz/`             |

### Real-Time Communication

| Product      | Reference                  |
| ------------ | -------------------------- |
| RealtimeKit  | `references/realtimekit/`  |
| Realtime SFU | `references/realtime-sfu/` |

### Developer Tools

| Product            | Reference                        |
| ------------------ | -------------------------------- |
| Wrangler           | `references/wrangler/`           |
| Miniflare          | `references/miniflare/`          |
| C3                 | `references/c3/`                 |
| Observability      | `references/observability/`      |
| Analytics Engine   | `references/analytics-engine/`   |
| Web Analytics      | `references/web-analytics/`      |
| Sandbox            | `references/sandbox/`            |
| Workerd            | `references/workerd/`            |
| Workers Playground | `references/workers-playground/` |

### Infrastructure as Code

| Product   | Reference               |
| --------- | ----------------------- |
| Pulumi    | `references/pulumi/`    |
| Terraform | `references/terraform/` |
| API       | `references/api/`       |

### Other Services

| Product       | Reference                   |
| ------------- | --------------------------- |
| Email Routing | `references/email-routing/` |
| Email Workers | `references/email-workers/` |
| Static Assets | `references/static-assets/` |
| Bindings      | `references/bindings/`      |
| Cache Reserve | `references/cache-reserve/` |

## Troubleshooting

### Escalated Network Access

If deployment fails due to network issues (timeouts, DNS errors, connection resets), rerun the deploy with escalated permissions (use `sandbox_permissions=require_escalated`). The deploy requires escalated network access when sandbox networking blocks outbound requests.

Example guidance to the user:

```
The deploy needs escalated network access to deploy to Cloudflare. I can rerun the command with escalated permissions—want me to proceed?
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/wrangler/auth.md

```markdown
# Authentication

Authenticate with Cloudflare before deploying Workers or Pages.

## Quick Decision Tree

```
Need to authenticate?
├─ Interactive/local dev → wrangler login (recommended)
├─ CI/CD or headless → CLOUDFLARE_API_TOKEN env var
└─ Terraform/Pulumi → See respective references
```

## wrangler login (Recommended)

One-time OAuth flow for local development:

```bash
npx wrangler login     # Opens browser, completes OAuth
npx wrangler whoami    # Verify: shows email + account ID
```

Credentials stored locally. Works for all subsequent commands.

## API Token (CI/CD)

For automated pipelines or environments without browser access:

1. Go to: **https://dash.cloudflare.com/profile/api-tokens**
2. Click **Create Token**
3. Use template: **"Edit Cloudflare Workers"** (covers Workers, Pages, KV, D1, R2)
4. Copy the token (shown only once)
5. Set environment variable:

```bash
export CLOUDFLARE_API_TOKEN="your-token-here"
```

### Minimal Permissions by Task

| Task                 | Template / Permissions                                   |
| -------------------- | -------------------------------------------------------- |
| Deploy Workers/Pages | "Edit Cloudflare Workers" template                       |
| Read-only access     | "Read All Resources" template                            |
| Custom scope         | Account:Read + Workers Scripts:Edit + specific resources |

## Troubleshooting

| Error                         | Cause                         | Fix                                                            |
| ----------------------------- | ----------------------------- | -------------------------------------------------------------- |
| "Not logged in"               | No credentials                | `wrangler login` or set `CLOUDFLARE_API_TOKEN`                 |
| "Authentication error"        | Invalid/expired token         | Regenerate token in dashboard                                  |
| "Missing account"             | Wrong account selected        | `wrangler whoami` to check, add `account_id` to wrangler.jsonc |
| Token works locally, fails CI | Token scoped to wrong account | Verify account ID matches in both places                       |
| "Insufficient permissions"    | Token lacks required scope    | Create new token with correct permissions                      |

## Verifying Authentication

```bash
npx wrangler whoami
```

Output shows:

- Email (if OAuth login)
- Account ID and name
- Token scopes (if API token)

Non-zero exit code means not authenticated.

## See Also

- [terraform/README.md](../terraform/README.md) - Terraform provider auth
- [pulumi/README.md](../pulumi/README.md) - Pulumi provider auth

```