What Is Cloudflare OS? An AI-First Productivity Platform Built on Cloudflare Workers

Cloudflare OS is an AI-first productivity platform that treats the user's workflow like an operating system, running on Cloudflare Workers (or the open-source workerd runtime) to provide a sandboxed environment where AI agents build and execute personal apps called gadgets.

Cloudflare OS reimagines computing as an AI-native stack within the cloudflare/cloudflare-os repository. Unlike conventional web apps, it implements traditional operating system primitives—kernels, shells, device drivers, and processes—using Cloudflare's edge infrastructure to deliver a secure, collaborative workspace for AI-enhanced productivity.

Core Architecture: Mapping Traditional OS to Cloudflare OS

Cloudflare OS mirrors conventional operating system architecture by mapping each hardware abstraction to a cloud-native equivalent running on Cloudflare Workers.

Traditional OS Component	Cloudflare OS Counterpart
Kernel	packages/workshop-backend – the backend kernel managing users, gadgets, gatekeepers, and real-time collaboration
Device Drivers	Gatekeepers – capability-based security modules mediating access to external services like GitHub or Google
Shell	packages/workshop-frontend – a single-page React UI providing the agent chat, gadget editor, and sharing interface
Processes / Executables	Gadgets – sandboxed personal apps built by the AI coding agent, each isolated in its own Durable Object facet
Templates	Blueprints – versioned code templates that describe a full gadget, allowing users to instantiate private copies

All components remain stateless except for Durable Objects that persist user data, gadget code, and gatekeeper accounts. The system leverages Dynamic Workers, Facets, and Durable Object bindings to isolate execution contexts.

The Frontend Shell: React and Cap'n Web RPC

The user interface functions as the operating system shell. Located in packages/workshop-frontend, this Vite-powered React application communicates with the backend kernel over Cap'n Web RPC via a persistent WebSocket connection.

The frontend hosts three primary interfaces: the agent chat for natural language programming, a gadget editor with real-time collaboration powered by Yjs (import * as Y from "yjs"), and sharing dialogs for distributing blueprints. This architecture ensures that UI interactions translate directly into capability-based RPC calls rather than RESTful HTTP requests.

The following client-side stub demonstrates how the frontend communicates with a gadget's exposed services using Cap'n Web's pipelining capabilities:

import { createRpcStub } from "capnweb";
import type { EchoService } from "@gadgets/workshop-shared/api";

// Obtain a stub to the server‑side EchoService (exposed by a gadget)
const echoStub = createRpcStub<EchoService>(window.parent, "echo");

// Use the stub – Cap’n Web allows pipelining, so we can call without `await`
echoStub.say("Hello from the client!").then((reply) => {
  console.log("Server replied:", reply);
});

The Backend Kernel: Overseer and Agent Orchestration

At the heart of Cloudflare OS lies the kernel implemented in packages/workshop-backend/src/overseer.ts. This central orchestrator wires together users, gadgets, gatekeepers, and the AI coding agent.

Subsystems Managed by the Overseer

The overseer coordinates four critical services defined in the backend package:

1. User management and authentication – handled in src/user.ts
2. Gadget lifecycle – each gadget runs inside a Dynamic Worker facet backed by a Durable Object defined in src/git-store.ts, which persists source files and enables real-time collaboration
3. Agent orchestration – the AI coding agent in src/agent.ts generates code, compiles it on-the-fly, and executes it within the sandboxed gadget environment
4. Real-time collaboration – Yjs synchronizes document state across multiple participants editing the same gadget

By isolating each gadget within its own Durable Object facet, the kernel ensures that user applications cannot interfere with each other or access unauthorized resources.

Gatekeepers: Capability-Based Device Drivers

Gatekeepers serve as device drivers for external services, replacing traditional OS hardware abstraction layers with security-focused integration modules. Each gatekeeper resides in its own package, such as packages/gatekeeper-github or packages/gatekeeper-google.

Core Gatekeeper Functions

Every gatekeeper performs three distinct operations:

• OAuth flow management – handling authentication with services like GitHub as documented in packages/gatekeeper-github/README.md
• Capability-based RPC – exposing typed interfaces through @gadgets/workshop-shared/gatekeeper that restrict API access to explicitly granted permissions
• Human-in-the-loop approval – simulating actions locally and queuing sensitive operations for explicit user confirmation before execution, detailed in docs/observers.md

The following example shows how a gadget accesses GitHub repositories through a granted gatekeeper capability:

import { Gatekeeper } from "@gadgets/workshop-shared/gatekeeper";

// In a gadget’s backend code:
async function listRepos(gk: Gatekeeper) {
  // `gk` is a capability granted by the user to this gadget
  const repos = await gk.github.repos.list();
  return repos.map((r) => r.name);
}

No service holds ambient authority; every gatekeeper capability must be explicitly introduced to a gadget by the user.

Blueprints: Versioned Templates for Gadgets

Blueprints function as the template system for Cloudflare OS, stored under packages/workshop-backend/format-blueprints/. Unlike traditional application hosting where users share a single deployed service, blueprints contain the complete source code of a gadget plus metadata, enabling a copy-on-instantiate model.

When a user instantiates a blueprint, they receive a private copy of the application that runs in its own isolated Durable Object. This approach, documented in packages/workshop-backend/format-blueprints/README.md, ensures that modifications to one instance never affect others while allowing the community to share and iterate on application templates safely.

Capability-Based Security Model

Cloudflare OS abandons ambient authority in favor of explicit capability-based security. The platform uses Cap'n Web for all RPC communication, ensuring that every gatekeeper, gadget, or agent capability requires explicit user grant before activation.

As implemented in packages/workshop-shared/api.ts, the type system enforces these constraints at the protocol level. The observer subsystem (docs/observers.md) logs all capability invocations and enforces human-in-the-loop approvals for sensitive operations, preventing accidental over-privilege while maintaining audit trails of AI and user actions.

Summary

• Cloudflare OS is an AI-first productivity platform running on Cloudflare Workers that treats user workflows as an operating system.
• The architecture maps traditional OS components to cloud-native equivalents: the kernel (packages/workshop-backend), shell (packages/workshop-frontend), device drivers (Gatekeepers), processes (Gadgets), and templates (Blueprints).
• Cap'n Web RPC enables secure, pipelined communication between the React frontend and sandboxed backend services.
• Gatekeepers provide capability-based access to external APIs like GitHub, requiring explicit user authorization and supporting human-in-the-loop approval workflows.
• All persistent state resides in Durable Objects, with each gadget isolated in its own facet to prevent cross-application interference.

Frequently Asked Questions

What runtime does Cloudflare OS use?

Cloudflare OS runs on Cloudflare Workers or the open-source workerd runtime. This serverless edge environment enables the platform to execute Dynamic Workers and Durable Objects close to users while maintaining stateful persistence through Cloudflare's infrastructure.

How does Cloudflare OS isolate user applications from each other?

Each gadget runs inside its own Dynamic Worker facet backed by a separate Durable Object instance. According to the source code in packages/workshop-backend/src/git-store.ts, this architecture ensures that gadget code, state, and capabilities remain isolated, preventing one user's application from accessing another's data or execution context.

What is the difference between a gadget and a blueprint?

A blueprint is a versioned template stored in packages/workshop-backend/format-blueprints/ that contains the complete source code for an application. A gadget is a running instance of a blueprint—a sandboxed, executable copy that operates within its own Durable Object. Users instantiate blueprints to create private gadget copies, enabling safe experimentation without affecting shared templates.

How does Cloudflare OS handle security for external API access?

The platform implements capability-based security through Gatekeepers. Rather than providing ambient credentials, each gatekeeper (such as packages/gatekeeper-github) exposes scoped capabilities via typed RPC interfaces. Users must explicitly grant these capabilities to gadgets, and the observer subsystem documented in docs/observers.md enforces human-in-the-loop approval for sensitive actions before execution.

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