Cloudflare OS Architecture: A Capability-Based Operating System Built on Workers

Cloudflare OS is a capability-based, sandboxed operating system that runs entirely on Cloudflare Workers (or the open-source workerd runtime), mapping traditional OS concepts like kernels, drivers, and processes to serverless primitives including gatekeepers, gadgets, and Dynamic Worker facets.

Cloudflare OS reimagines operating system architecture for the edge computing era. Available in the cloudflare/cloudflare-os repository, this platform implements a complete OS stack—from kernel to shell—using Cloudflare Workers, Durable Objects, and Cap'n Web RPC. The architecture employs capability-based security where agents, gadgets, and gatekeepers start with zero permissions and receive explicit grants only when users introduce capabilities.

Mapping Traditional OS Concepts to Cloudflare OS

Cloudflare OS mirrors conventional operating system architecture but substitutes hardware abstractions with cloud-native primitives. The platform organizes functionality into distinct layers that correspond to familiar OS components.

The Kernel: Workshop Backend

The kernel resides in packages/workshop-backend, serving as the central orchestrator for the entire system. This component manages users, gadgets, and gatekeepers while exposing the RPC API and handling security, state, and scheduling concerns.

At the heart of the kernel, packages/workshop-backend/src/overseer.ts implements the central orchestration logic for workspaces, gadgets, and gatekeepers. Administrative configuration and feature flags live in packages/workshop-backend/src/admin-config.ts, allowing operators to control system-wide behavior without modifying core logic.

Device Drivers: Gatekeepers

Gatekeepers function as device drivers for external services. Located in packages/gatekeeper-* directories, these tiny Workers mediate access to third-party APIs such as GitHub, Google, and Slack. Each gatekeeper handles OAuth flows, enforces capability restrictions, and maintains audit logs.

For example, packages/gatekeeper-github/src/index.ts implements the Cap'n Web RPC surface for GitHub API access. When users add a resource, the kernel provisions a new gatekeeper instance that installs its own facet into the workspace to mediate external calls.

Processes: Gadgets and Blueprints

Gadgets serve as user processes—per-user, AI-generated applications running inside isolated Dynamic Worker facets. Each gadget executes with network access disabled by default, ensuring sandboxed execution. Blueprints act as executable templates describing an entire gadget's code and metadata, stored and validated in packages/workshop-backend/src/blueprint-archive.ts.

When instantiated, blueprints spawn new Dynamic Worker facets through the kernel's provisioning system, creating isolated execution environments for user applications.

The Shell: Frontend Interface

The shell resides in packages/workshop-frontend, implemented as a React SPA in packages/workshop-frontend/src/App.tsx. This interactive interface provides the chat UI for agent communication, gadget exploration, and resource management. The frontend communicates with the kernel via Cap'n Web RPC, calling server methods as if they were local functions.

Security and Communication Architecture

Capability-Based Security Model

Every component starts with no permissions by default. Access to external services requires explicit capability grants—when a user adds a GitHub repository, the system creates a capability token that authorizes specific actions. This model replaces traditional ACLs and prevents broad, unchecked access patterns.

Gatekeepers enforce these capabilities at the boundary, ensuring that gadgets can only access resources explicitly granted by the user. The kernel maintains the capability registry in Durable Objects, providing low-latency, real-time collaboration and persistent state management.

Cap'n Web RPC Protocol

Front-end and back-end components communicate over Cap'n Web, a low-boilerplate, type-safe RPC protocol defined in packages/workshop-shared/src/api.ts. This protocol enables AI agents to invoke kernel methods directly, with support for promise pipelining that allows clients to use return values before the server completes processing.

The AI coding agent, implemented in packages/workshop-backend/src/agent.ts, leverages this RPC layer to generate and deploy code without awaiting full round-trips, significantly accelerating the development workflow.

Practical Implementation Examples

Local Development Setup

Spin up the complete stack including frontend, backend, and gatekeepers using the local workerd runtime:

pnpm run-local

This command initializes all kernel services and gatekeepers. Visit http://localhost:8787 to access the React shell interface.

Provisioning External Resources

Adding a gatekeeper requires explicit user authorization through the OAuth flow:

// Admin UI triggers kernel API to establish capability
await gatekeeperGitHub.createAccount();   // Provisions GitHub capability
await gatekeeperGitHub.authorizeOAuth();  // Handles OAuth handshake

The gatekeeper subsequently mediates all GitHub API calls, enforcing the principle of least privilege.

Deploying Applications from Blueprints

Instantiate new gadgets using the blueprint system:

import { createGadgetFromBlueprint } from '@gadgets/workshop-shared';

const blueprintId = 'slide-deck';
const gadget = await createGadgetFromBlueprint(blueprintId, {
  name: 'My Presentation',
  owner: currentUserId,
});

The kernel validates the blueprint against packages/workshop-backend/src/blueprint-archive.ts and provisions an isolated Dynamic Worker facet for execution.

AI Agent Code Generation

Invoke the built-in coding agent to generate applications:

await aiAgent.invoke(`
  Create a new gadget that fetches weather data from OpenWeatherMap.
  Use the existing "weather" blueprint as a base.
`);

The agent communicates via Cap'n Web RPC stubs defined in the shared API package, enabling direct kernel manipulation without intermediate abstraction layers.

Summary

• Capability-based security ensures zero-trust execution where gadgets and gatekeepers possess no default permissions
• Kernel architecture centers on packages/workshop-backend/src/overseer.ts as the central orchestrator for workspaces and resources
• Gatekeepers act as sandboxed drivers for external services, implemented as independent packages under packages/gatekeeper-*
• Dynamic Worker facets provide process isolation for gadgets, with network access disabled by default
• Cap'n Web RPC enables type-safe communication between the React frontend, kernel, and AI agents
• Durable Objects back all persistent state, enabling real-time collaboration and low-latency access

Frequently Asked Questions

How does Cloudflare OS handle security compared to traditional operating systems?

Cloudflare OS replaces traditional ACLs with capability-based security where every agent, gadget, and gatekeeper starts with no permissions. Access to external services requires explicit user authorization through capability grants managed by gatekeepers. Each gadget runs in a sandboxed Dynamic Worker facet with network disabled by default, and gatekeepers mediate all external API calls, enforcing strict principle-of-least-privilege access controls.

What programming model do developers use to build applications on Cloudflare OS?

Developers create Blueprints—templates describing complete applications including code and metadata—which the kernel instantiates as Gadgets. These gadgets run as isolated processes (Dynamic Worker facets) and communicate via Cap'n Web RPC. The system supports AI-assisted development through agents that invoke kernel methods directly, allowing programmatic generation and deployment of new gadgets without manual infrastructure configuration.

Where is state stored in Cloudflare OS?

All persistent state resides in Durable Objects, with each workspace representing a collection of gadgets, user data, and bindings stored within a single Durable Object instance. This architecture provides low-latency access, real-time collaboration capabilities, and strong consistency guarantees. The kernel manages state distribution through packages/workshop-backend/src/overseer.ts, while gatekeepers maintain isolated state facets for their respective external service connections.

Can Cloudflare OS run outside of Cloudflare's infrastructure?

Yes. While designed for Cloudflare Workers, Cloudflare OS runs entirely on the open-source workerd runtime. Execute pnpm run-local to spin up the complete stack—including the kernel, gatekeepers, and React frontend—on a local development machine. This capability allows developers to build and test capability-based applications locally before deploying to Cloudflare's global edge network.

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