README

workerd is NOT a hardened sandbox. Do not run untrusted code. It’s designed for deploying YOUR code locally/self-hosted, not multi-tenant SaaS. Cloudflare production adds security layers not present in open-source workerd.

Decision Tree: When to Use What

95% of users: Use Wrangler

• Local development: wrangler dev (uses workerd internally)
• Deployment: wrangler deploy (deploys to Cloudflare)
• Types: wrangler types (generates TypeScript types)

Use raw workerd directly only if:

• Self-hosting Workers runtime in production
• Embedding runtime in C++ application
• Custom tooling/testing infrastructure
• Debugging workerd-specific behavior

Never use workerd for:

• Running untrusted/user-submitted code
• Multi-tenant isolation (not hardened)
• Production without additional security layers

Key Features

• Standards-based: Fetch API, Web Crypto, Streams, WebSocket
• Nanoservices: Service bindings with local call performance
• Capability security: Explicit bindings prevent SSRF
• Backwards compatible: Version = max compat date supported

Architecture

Quick Start

Platform Support & Beta Status

workerd is in active development. Breaking changes possible. Pin versions in production.

Core Concepts

• Service: Named endpoint (worker/network/disk/external)
• Binding: Capability-based resource access (KV/DO/R2/services)
• Compatibility date: Feature gate (always set!)
• Modules: ES modules (recommended) or service worker syntax

Reading Order (Progressive Disclosure)

Start here:

1. This README (overview, decision tree)
2. patterns.md - Common workflows, framework examples

When you need details: 3. configuration.md - Config format, services, bindings 4. api.md - Runtime APIs, TypeScript types 5. gotchas.md - Common errors, debugging

Related References

• workers (opens in a new tab) - Workers runtime API documentation
• miniflare (opens in a new tab) - Testing tool built on workerd
• wrangler (opens in a new tab) - CLI that uses workerd for local dev