workerd vs Cloudflare Workers Architecture: Key Differences Explained

workerd is the open-source, self-hostable runtime that powers Cloudflare Workers, sharing the same V8 isolate execution model but differing in deployment, configuration, and infrastructure management.

The cloudflare/workerd repository contains the runtime that implements the core execution environment of the Cloudflare Workers platform. While both systems execute JavaScript in V8 isolates and expose identical Web API surfaces, their architectural approaches to deployment, networking, and service bindings diverge significantly based on who controls the surrounding infrastructure.

Execution Environment and Deployment Model

Both platforms create a V8 isolate per request to execute JavaScript, but the surrounding infrastructure differs fundamentally.

Cloudflare Workers (Hosted)

Cloudflare Workers run in isolated V8 isolates created on Cloudflare's edge servers across approximately 200 Points of Presence (PoPs). The edge network handles request routing, TLS termination, and load balancing before the isolate is invoked. Code uploads via the Wrangler CLI or Dashboard automatically distribute scripts to every edge location through Cloudflare's control plane.

workerd (Self-Hosted)

workerd also creates a V8 isolate per request, but the runtime is a single binary that runs on any POSIX-compatible host (Linux, macOS, Windows). All networking, TLS, and socket handling are performed by the binary itself. You build a Cap'n Proto configuration file that describes services, sockets, and bindings, then launch the binary with workerd serve. This architecture allows deployment on a single machine, a fleet behind a load balancer, or inside container orchestrators like Kubernetes.

Configuration and Capability Bindings

The method for declaring services and bindings represents the most visible architectural difference between the two platforms.

Wrangler and Managed Bindings

Cloudflare Workers use a declarative wrangler.toml file where bindings (KV, Durable Objects, R2) are declared and resolved automatically by Cloudflare's edge services. The platform enforces zero-trust capability isolation without operator intervention.

Cap'n Proto Configuration

workerd uses the Cap'n Proto text format (.capnp) defined in src/workerd/server/workerd.capnp. This schema supports multiple services, socket definitions, and fine-grained capability wiring. Bindings are expressed in the configuration file, but the actual backing services must be supplied by the operator—whether a local SQLite database for KV, a custom Durable Object implementation, or a remote Cloudflare API endpoint.

Networking Stack and Request Flow

The data flow through each architecture illustrates their operational differences.

Cloudflare Workers:

1. Client request arrives at Cloudflare's edge
2. TLS termination and global routing select the nearest PoP
3. V8 isolate executes the script
4. Outbound fetches route through Cloudflare's edge network

workerd:

1. Client request reaches the host OS networking stack
2. workerd binary receives the connection via its built-in HTTP server (src/workerd/server/)
3. TLS is handled by the binary if enabled, or via inherited pre-opened sockets (--socket-fd)
4. V8 isolate executes the script and returns the response directly

Extensibility and Security Model

Cloudflare Workers offer limited extensibility to the services Cloudflare provides, with custom extensions requiring Cloudflare-managed solutions like Workers KV or Durable Objects. In contrast, workerd can be extended with custom C++ modules or Rust components (see src/rust/), and the binary can embed additional WASM modules, making it a programmable HTTP proxy.

Security hardening differs substantially. Cloudflare adds multiple layers including sandboxing, Content Security Policy (CSP), request-level rate limiting, and Spectre mitigations that remain outside the worker's control. workerd provides process-level isolation but relies on the host OS or container runtime for additional hardening. According to the README, workerd is not a hardened sandbox on its own.

Code Examples

Basic HTTP Handler

Cloudflare Workers (hosted):

addEventListener("fetch", event => {
  event.respondWith(new Response("Hello from Cloudflare!"));
});

Deploy with wrangler publish.

workerd (self-hosted):

Create hello.js:

addEventListener("fetch", event => {
  event.respondWith(new Response("Hello from workerd!"));
});

Create hello.capnp:

using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
  services = [
    (name = "hello", worker = .helloWorker),
  ],
  sockets = [
    (name = "http",
      address = "*:8080",
      http = (),
      service = "hello")
  ]
);

const helloWorker :Workerd.Worker = (
  serviceWorkerScript = embed "hello.js",
  compatibilityDate = "2023-02-28"
);

Run:

workerd serve hello.capnp

The runtime listens on http://localhost:8080, but you control the deployment, binding resolution, and networking stack.

KV Binding Configuration

Cloudflare Workers:

# wrangler.toml

kv_namespaces = [{ binding = "MY_KV", id = "xxxxxxx" }]

workerd:

const config :Workerd.Config = (
  services = [
    (name = "app",
      worker = .appWorker,
      bindings = [
        (name = "MY_KV", type = kv, config = (namespace = "my-kv"))
      ]
    ),
  ],
  # ... sockets configuration ...

);

The operator must provide the actual KV service implementation, unlike the hosted platform where Cloudflare manages the backend automatically.

Key Source Files in the workerd Repository

Understanding the architecture requires familiarity with these core components:

• src/workerd/server/workerd.capnp — Core Cap'n Proto schema for configuration, services, sockets, and bindings
• src/workerd/jsg/ — JavaScript glue layer mapping V8 objects to C++ JSG-exposed types
• src/workerd/api/ — Implementations of standard Web APIs (fetch, crypto, streams) and the Node.js compatibility layer
• src/workerd/io/ — I/O subsystem handling request tracking, actor lifecycle, and storage back-ends
• src/workerd/server/ — Main server entry point and command-line handling
• src/node/ — TypeScript implementation of Node.js compatibility (e.g., fs, buffer)
• src/cloudflare/ — Cloudflare-specific APIs including Workers AI and Durable Objects
• AGENTS.md — High-level architectural overview for developers
• README.md — Build instructions and deployment guidance

Summary

• workerd is the open-source runtime powering Cloudflare Workers, executing JavaScript in V8 isolates just like the hosted platform.
• Deployment differs fundamentally: Cloudflare manages global edge distribution automatically, while workerd requires manual configuration via Cap'n Proto files and self-managed infrastructure.
• Configuration uses wrangler.toml for hosted Workers versus src/workerd/server/workerd.capnp schema definitions for workerd.
• Bindings are automatically resolved by Cloudflare's platform but require operator-provided backing services in workerd.
• Security relies on Cloudflare's multi-layer edge sandbox for hosted Workers, while workerd depends on host OS/container isolation.
• Extensibility is limited on Cloudflare's platform but supports custom C++, Rust, and WASM modules in workerd.

Frequently Asked Questions

Is workerd a fully sandboxed environment like Cloudflare Workers?

No. While workerd provides process-level isolation for V8 isolates, it lacks the multi-layer sandboxing, CSP enforcement, and Spectre mitigations that Cloudflare implements at the edge. The README explicitly states that workerd is not a hardened sandbox on its own and relies on the host operating system or container runtime for additional security boundaries.

Can I use Cloudflare-specific APIs like KV and Durable Objects with workerd?

Yes, but with significant differences. The src/cloudflare/ directory contains TypeScript implementations of Cloudflare-specific APIs. However, while the API surface is compatible, you must provide the actual backing services yourself. For KV, you might connect to a local SQLite database or a remote Cloudflare API endpoint, whereas Durable Objects require implementing the actor lifecycle management that Cloudflare handles automatically in their hosted platform.

How does the compatibility date system work in workerd versus Cloudflare Workers?

Both platforms use the same compatibilityDate mechanism. In Cloudflare Workers, compatibility dates are managed centrally by the platform to ensure API behavior remains consistent. In workerd, the compatibilityDate field in the Cap'n Proto config selects the API surface, but because you control the runtime binary, you can run any released version of workerd on your own hardware and update on your own schedule.

What are the performance implications of self-hosting with workerd?

workerd eliminates network latency to Cloudflare's edge, which can improve response times for local or private network deployments. However, you lose Cloudflare's global load balancing, automatic TLS certificate management, and DDoS protection. The binary itself is highly optimized and shares the same execution engine as the hosted platform, but performance depends entirely on your infrastructure's compute resources and networking configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}