1# Workerd Runtime
2 
3V8-based JS/Wasm runtime powering Cloudflare Workers. Use as app server, dev tool, or HTTP proxy.
4 
5## ⚠️ IMPORTANT SECURITY NOTICE
6**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.
7 
8## Decision Tree: When to Use What
9 
10**95% of users:** Use Wrangler
11- Local development: `wrangler dev` (uses workerd internally)
12- Deployment: `wrangler deploy` (deploys to Cloudflare)
13- Types: `wrangler types` (generates TypeScript types)
14 
15**Use raw workerd directly only if:**
16- Self-hosting Workers runtime in production
17- Embedding runtime in C++ application
18- Custom tooling/testing infrastructure
19- Debugging workerd-specific behavior
20 
21**Never use workerd for:**
22- Running untrusted/user-submitted code
23- Multi-tenant isolation (not hardened)
24- Production without additional security layers
25 
26## Key Features
27- **Standards-based**: Fetch API, Web Crypto, Streams, WebSocket
28- **Nanoservices**: Service bindings with local call performance
29- **Capability security**: Explicit bindings prevent SSRF
30- **Backwards compatible**: Version = max compat date supported
31 
32## Architecture
33```
34Config (workerd.capnp)
35├── Services (workers/endpoints)
36├── Sockets (HTTP/HTTPS listeners)
37└── Extensions (global capabilities)
38```
39 
40## Quick Start
41```bash
42workerd serve config.capnp
43workerd compile config.capnp myConfig -o binary
44workerd test config.capnp
45```
46 
47## Platform Support & Beta Status
48 
49| Platform | Status | Notes |
50|----------|--------|-------|
51| Linux (x64) | Stable | Primary platform |
52| macOS (x64/ARM) | Stable | Full support |
53| Windows | Beta | Use WSL2 for best results |
54| Linux (ARM64) | Experimental | Limited testing |
55 
56workerd is in **active development**. Breaking changes possible. Pin versions in production.
57 
58## Core Concepts
59- **Service**: Named endpoint (worker/network/disk/external)
60- **Binding**: Capability-based resource access (KV/DO/R2/services)
61- **Compatibility date**: Feature gate (always set!)
62- **Modules**: ES modules (recommended) or service worker syntax
63 
64## Reading Order (Progressive Disclosure)
65 
66**Start here:**
671. This README (overview, decision tree)
682. [patterns.md](./patterns.md) - Common workflows, framework examples
69 
70**When you need details:**
713. [configuration.md](./configuration.md) - Config format, services, bindings
724. [api.md](./api.md) - Runtime APIs, TypeScript types
735. [gotchas.md](./gotchas.md) - Common errors, debugging
74 
75## Related References
76- [workers](../workers/) - Workers runtime API documentation
77- [miniflare](../miniflare/) - Testing tool built on workerd
78- [wrangler](../wrangler/) - CLI that uses workerd for local dev
79