# Understanding the Kernel Metaphor in Cloudflare OS Architecture

> Discover Cloudflare OS architecture and its kernel metaphor. Learn how workshop-backend acts as the kernel, managing access and security via capability-based sandboxing for apps and services.

- Repository: [Cloudflare/cloudflare-os](https://github.com/cloudflare/cloudflare-os)
- Tags: internals
- Published: 2026-09-04

---

**In Cloudflare OS, the `workshop-backend` package functions as the system kernel, mediating access between users, gadgets (applications), and gatekeepers (external-service connectors) while enforcing security through capability-based sandboxing.**

The open-source `cloudflare/cloudflare-os` repository implements a novel architectural pattern that treats the backend infrastructure as an operating system kernel. This design positions the TypeScript-based `workshop-backend` as the trusted computational core, analogous to how a traditional OS kernel arbitrates access between hardware resources and user-space processes.

## What Is the Kernel Metaphor?

According to the project documentation, the backend "connects users to programs and devices (Gadgets and Gatekeepers) while implementing security by sandboxing applications and enforcing access control" — a direct parallel to kernel responsibilities in conventional operating systems 【README.md line 99‑108】. Rather than a low-level C component, Cloudflare OS implements its kernel as a hardened TypeScript/Node.js backend that upholds OS-grade invariants: strict isolation, controlled resource access, and a minimal attack surface.

### Core Responsibilities of the Workshop Backend

The `workshop-backend` package serves three primary kernel functions:

- **Security boundary enforcement** – Establishes hard boundaries between untrusted user code (Gadgets) and sensitive system resources
- **Capability-based sandboxing** – Manages fine-grained permissions through capability tokens rather than ambient authority
- **RPC routing** – Handles all inter-process communication via Cap'n Web, the system's Remote Procedure Call protocol

### The Kernel Bar Review Process

Because the kernel is security-critical, the project maintains a "kernel bar" — a higher standard of code review than standard packages. According to the contributor guidelines, every line of `workshop-backend` and any public API changes in `workshop-shared` must be read by human reviewers, with mandatory doc-comments required on every exported member 【AGENTS.md line 16】.

## Architectural Parallels: Traditional OS vs Cloudflare OS

The following mapping illustrates how Cloudflare OS translates traditional kernel concepts into its distributed architecture:

| Traditional OS Concept | Cloudflare OS Implementation |
|------------------------|------------------------------|
| Processes & threads | **Gadgets** – user-owned programmable agents that execute application logic |
| Device drivers | **Gatekeepers** – sandboxed connectors to external services (APIs, databases) |
| System calls | **Cap'n Web RPC** – capability-checked remote procedure calls handled by the backend |
| Memory management | **Durable Objects** and **KV storage** – scoped per-user/per-gatekeeper persistence layers |

## Working with Kernel Capabilities in Code

### Defining RPC Interfaces in the Kernel

Kernel capabilities are defined as TypeScript interfaces in [`packages/workshop-backend/src/overseer.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/overseer.ts). These interfaces establish the contract for what untrusted Gadgets can request from the trusted kernel:

```typescript
// packages/workshop-backend/src/overseer.ts
export interface GadgetClient {
  /** Execute code for a gadget */
  executeCode(
    code: string,
    args: Record<string, unknown>,
  ): Promise<GadgetExecutionResult>;
}

```

*All exported members in `workshop-shared` (the public RPC API surface) require doc-comments to satisfy the kernel bar review policy* 【AGENTS.md line 16】.

### Consuming Kernel Services from Gadgets

Gadgets (frontend applications) obtain capability stubs from the kernel through the RPC connection. The following React component demonstrates proper stub acquisition and mandatory cleanup:

```typescript
import { useEffect, useState } from "react";
import { GadgetClient } from "workshop-shared";

export function MyGadget() {
  const [result, setResult] = useState<{ output: string } | null>(null);

  useEffect(() => {
    // Obtain a stub from the RPC connection (provided by the kernel)
    const stub: GadgetClient = rpc.getCapability("gadget");
    // Wrap the stub to avoid React’s setState function confusion
    const wrapped = { stub };
    stub.executeCode("return 42;", {}).then(setResult);
    // Clean up the stub when the component unmounts
    return () => wrapped.stub[Symbol.dispose]();
  }, []);

  return <div>{result ? result.output : "Running…"}</div>;
}

```

*The wrapper around the stub and explicit disposal via `Symbol.dispose` are both required by the kernel's RPC conventions to prevent capability leaks*.

### Implementing Gatekeepers as Device Drivers

Gatekeepers function as kernel modules or device drivers. They are defined in [`packages/gatekeeper-context/src/index.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-context/src/index.ts) using the `defineGatekeeper` helper, which registers a new external-service connector with the kernel:

```typescript
// packages/gatekeeper-context/src/index.ts
export const GATEKEEPER_CONTEXT = defineGatekeeper({
  vendorId: "context",
  autoProvisionsAccount: true,
  createAccount() {
    return new ContextAccount(); // Persistent state stored in Durable Objects
  },
});

```

*Gatekeepers represent the kernel's "device driver" layer, defined with the same rigor as backend capabilities* 【AGENTS.md line 16】.

## Summary

- The **`workshop-backend`** package serves as the Cloudflare OS kernel, written in TypeScript rather than systems-level languages like C or Rust
- A **"kernel bar"** review process mandates human review of every line change and documentation for all public API exports in `workshop-shared`
- **Gadgets** act as user-space processes, while **Gatekeepers** serve as sandboxed device drivers for external services
- **Cap'n Web RPC** provides the system call interface, with capability-based security checks enforced by the kernel
- All capability stubs must follow strict lifecycle management patterns, including explicit disposal to prevent resource leaks

## Frequently Asked Questions

### What exactly is the "kernel" in Cloudflare OS architecture?

The kernel refers specifically to the **`workshop-backend`** package, which functions as the trusted computing base of the platform. Unlike traditional monolithic kernels, it is implemented as a TypeScript application that runs on Cloudflare's edge infrastructure, managing security boundaries and routing RPC calls between untrusted user code (Gadgets) and external service connectors (Gatekeepers).

### What is the "kernel bar" review requirement?

The kernel bar is a mandatory security review process documented in [`AGENTS.md`](https://github.com/cloudflare/cloudflare-os/blob/main/AGENTS.md) that requires human reviewers to read every line of code changed in `workshop-backend` and any public API modifications in `workshop-shared`. Additionally, every exported member must include a doc-comment explaining its security implications and usage contract 【AGENTS.md line 16】.

### How do Gadgets and Gatekeepers relate to traditional OS concepts?

**Gadgets** are analogous to user processes or threads — they represent programmable agents owned by users that execute arbitrary logic in a sandboxed environment. **Gatekeepers** correspond to device drivers; they provide controlled access to external resources like databases or third-party APIs, with each Gatekeeper running in its own isolated security context mediated by the kernel.

### What RPC protocol does the Cloudflare OS kernel use?

The system uses **Cap'n Web**, a capability-based RPC protocol derived from Cap'n Proto. All communication between Gadgets (frontend applications) and the kernel, as well as between the kernel and Gatekeepers, occurs over this protocol. The kernel validates capabilities on each call to ensure principals can only access resources they have been explicitly granted.