Cloudflare OS Deep Dive: Redefining the Productivity Operating System for the AI Era

Cloudflare OS is Cloudflare's open-source AI productivity environment that redefines how software is distributed and used. This comprehensive analysis covers the project's architecture, design philosophy, practical tutorials, and core insights for the AI era.

1. Project Overview

1.1 What is Cloudflare OS?

Cloudflare OS is an AI productivity environment originally developed for internal use at Cloudflare. A large portion of Cloudflare's workforce — from engineering to sales — uses Cloudflare OS every day to help them do their jobs.

This is not a traditional computer operating system. The term "operating system" is used in two senses:

• An operating system for the company to be productive with AI, in a way that is safe
• An operating system for AI workloads, analogous to how a traditional OS manages compute workloads

Cloudflare OS provides three core capabilities:

1. Agent Chat UI — Ask agents to do tasks, preloaded with knowledge about how your company operates
2. Sandboxed App Development — Build "Gadgets" (small personal apps) with AI and safely share them
3. Security Framework (Gatekeepers) — Guardrails that let non-technical users safely "go nuts"

1.2 Core Features

1.3 Key Concepts

Gadgets — A New Way of Thinking About Software

Cloudflare OS is more than just another chatbox with connectors. The system revolves around a new approach to software, where every user runs their own copy of the productivity apps they use.

When you create a slide deck in Cloudflare OS, you are not calling out to some SaaS software running in the cloud. The system creates a private instance of the slide deck software just for you. We call this a "Gadget". This instance runs in a separate sandbox from everyone else's slide decks.

This has two profound effects:

1. Security — It's impossible for the slide deck app to have a security bug that leaks your slides to an attacker. The Cloudflare OS sandbox controls all access to your private instance.
2. Modifiability — If you want, you can freely modify the code. If the slide deck app is missing a feature you need, you can just ask your agent to add it. And because of point 1, it's totally safe to do so.

This is a big departure from the last 25 years of cloud architecture and "Software as a Service", but we think AI has changed the equation. When any user is capable of prompting an agent to add the features they need, the centralized model of software stops making sense.

Gatekeepers — A Capability-Based Security Layer

Gatekeepers are like supercharged MCP servers.

When you introduce an agent or Gadget to an external resource, a Gatekeeper is created to manage that access. The Gatekeeper is a piece of software specific to each external service which moderates a Gadget's connection to that service. It:

• Provides a clean Cap'n Web API to the service (wrapping whatever API the service provides natively)
• Handles authorization (e.g. via OAuth)
• Enforces narrow access to only the specific resource the user intended
• Logs every action the Gadget (or agent) performs, for your review
• For any action which has side effects, provides the human user an opportunity to approve or deny the action ("human in the loop")

Async Human-in-the-Loop is Gatekeeper's major innovation. Traditionally, human-in-the-loop setups require the human to approve actions synchronously. When the agent wants to do something, it has to stop and wait for said approval before it can continue. This is annoying: you give your agent a task, then walk away and get a coffee, only to come back and find the agent got stuck on an approval on the first step and has made no progress. As a result, people often give in and set their agents to "auto-approve", or --dangerously-skip-permissions, which is, obviously, unsafe.

Gatekeepers provide a better way: When the agent (or Gadget) performs an action that requires approval, the Gatekeeper will simulate the outcome locally, allowing the agent to proceed and queue up more actions. The Gatekeeper tells the agent that the action completed, and if the agent tries to read back the results, the Gatekeeper gives it simulated results. Once the agent is done, the user may approve or reject the actions in bulk, or one-by-one, but either way, they can do it later, when it is convenient.

Blueprints — Share Your Code

If you've created a Gadget that might be useful to others, but you don't want to share the Gadget itself, you can instead share a Blueprint, allowing other people to create their own copy of the Gadget. A Blueprint is essentially a copy of the code.

Blueprints are a major change from cloud software tradition. Traditionally, if you create a web app that you want to share with other users, you host the app on your server, and the users connect to that. Blueprints are much more like mobile apps and traditional PC apps: every user runs their own copy of the software.

In the age of AI, this change is critically important. On one hand, AI empowers an individual developer to build more than ever, but it is still difficult for an individual developer to maintain an online service; this eliminates the need. On the other hand — and even more importantly — allowing each user to run their own copy of the software empowers the user to change the software to meet their needs, using AI. No need to file a feature request, no need to beg the developer to prioritize it. The end user can solve their own problems.

2. Detailed Tutorial

2.1 Quick Start: Run Locally

The fastest way to use Cloudflare OS is to run it locally.

Prerequisites:

• Install pnpm

# Install pnpm (if not already installed)
npm install -g pnpm

# Clone the repository
git clone https://github.com/cloudflare/cloudflare-os.git
cd cloudflare-os

# Run the full stack
pnpm run-local

Then visit: http://localhost:8787

This runs Cloudflare OS locally using wrangler, the Workers developer tooling CLI. This is not the right way to run the OS on a production server, but it works fine for trying it out on your local machine.

Your data will be stored in a subdirectory named .wrangler.

2.2 Development Mode

When developing, you'll want to run the front-end and back-end as two separate commands in two terminals:

# Terminal 1: Backend
pnpm dev-server

# Terminal 2: Frontend
pnpm dev-client

Then visit: http://localhost:3000

2.3 Deploy to Your Cloudflare Account

One-Click Deploy

Cloudflare has built an online flow that helps you deploy to your own Cloudflare account:

Visit https://os.cloudflare.app/deploy

Advanced Deployment

For more sophisticated deployment, with your gatekeepers and potentially code changes, check out the deployment starter repo:

Visit https://github.com/cloudflare/cloudflare-os-starter

2.4 Try These Prompts

After running locally, try these prompts:

• "Make slides for my upcoming meeting with a customer." (Uses the built-in slides blueprint)
• "Make a collaborative whiteboard app." (Creates a new app from scratch)
• "Make a tic tac toe game." Then "I'll be X and you be O. I've made my first move. Your turn."
• "Make an issue dashboard for this GitHub repo." (Attach a repo; requires GitHub integration)
• "Fix the typos in this Google Doc." (Attach a doc; requires Google integration)

2.5 Configuring External Services

Many Gatekeepers require configuration to connect to third-party services, including obtaining OAuth client credentials for each service.

Each gatekeeper package contains setup instructions:

Gatekeeper OAuth Callback URL:

http://localhost:8787/gatekeeper/<provider>/oauth

GitHub Integration Configuration Example:

# packages/gatekeeper-github/.env
CLIENT_ID=your-client-id-here
CLIENT_SECRET=your-client-secret-here

# Add to root .dev.vars for sign-in
AUTH_GATEKEEPERS=cloudflare,google,github

2.6 Authentication Modes

Cloudflare OS supports two authentication modes:

1. Password mode (default) — Username/password signup
2. Cloudflare Access mode — Set VITE_CF_ACCESS_MODE=true

3. Core Architecture Deep Dive

3.1 Operating System Analogy

Cloudflare OS is actually analogous to an operating system on a technical level:

Our "kernel" is in the workshop-backend package. The backend legitimately does a lot of things similar to real OS kernels: it connects users to programs and devices (Gadgets and Gatekeepers) while implementing security by sandboxing applications and enforcing access control.

In this analogy, Gatekeepers — which connect users and agents to external services — are like drivers — which connect users and programs to external devices.

There is one thing that traditional OSes don't really manage today, but Cloudflare OS does: AI agents. If you think about it, this is really a missing feature in traditional OSes. We believe that AI agents cannot simply be treated as users. They must be accountable to a human user, while at the same time having their own restricted permissions. Agents do work by writing snippets of code and executing them on the fly. The ideal security model for all of this is capability-based security, not access control lists.

3.2 Technology Stack

• Runtime: Cloudflare Workers (Durable Objects, Dynamic Workers, Facets)
• Local Dev: workerd (open-source Workers runtime)
• Frontend: Vite-based dev server
• Key Libraries:
  • Pi — LLM provider abstraction
  • Monaco Editor — Code editor
  • Yjs — Real-time collaboration
  • Cap'n Web RPC — Low-boilerplate RPC

3.3 Project Structure

cloudflare-os/
├── packages/
│   ├── workshop-backend/      # Core kernel - connects users to gadgets/gatekeepers
│   ├── workshop-frontend/     # Shell UI (chat, workspace)
│   ├── workshop-shared/       # Shared types between frontend/backend
│   ├── router/                # HTTP routing
│   │
│   ├── gatekeeper-*/          # 14+ Gatekeeper packages
│   │   ├── gatekeeper-github/
│   │   ├── gatekeeper-google/
│   │   ├── gatekeeper-cloudflare/
│   │   ├── gatekeeper-notion/
│   │   ├── gatekeeper-slack/
│   │   ├── gatekeeper-supabase/
│   │   ├── gatekeeper-confluence/
│   │   ├── gatekeeper-email/
│   │   ├── gatekeeper-spotify/
│   │   ├── gatekeeper-homeassistant/
│   │   ├── gatekeeper-zoominfo/
│   │   ├── gatekeeper-mcp-portal/
│   │   ├── gatekeeper-mcp/
│   │   └── gatekeeper-scheduler/
│   │
│   ├── gatekeeper-context/    # Shared Gatekeeper utilities
│   ├── mcp-shared/            # MCP protocol shared code
│   │
│   ├── backend-utils/         # Backend utilities
│   ├── config-ui/             # Configuration UI
│   ├── error-reporting/       # Error handling
│   ├── typed-storage/         # Storage abstractions
│   └── integration-tests/     # Test suite
│
├── docs/                      # Documentation
├── plans/                     # Project plans
├── scripts/                   # Build/dev scripts
└── .github/workflows/         # CI/CD

3.4 Sandbox Security Model

Each Gadget runs in a secure sandbox that prevents it from talking to the internet at all without your explicit consent:

• Server-side: Runs in a Dynamic Worker with internet access disabled. Can only communicate with specific external resources that you have explicitly designated, via Workers Bindings.
• Client-side: Runs in a sandboxed iframe. Can only communicate with its server via a Cap'n Web RPC session provided over postMessage() to the parent frame. The iframe is otherwise blocked from accessing the internet (via Content-Security-Policy and iframe sandbox settings).

3.5 Capability-Based Access Control

Each agent, and each Gadget, by default has access to nothing. Even if you've configured the Gadget Workshop with access to external accounts, agents and Gadgets do NOT automatically get to use them.

Instead, you must introduce each agent (or Gadget) to any particular resources you want it to access. For instance, you may introduce a GitHub repository by pasting a link to it, or clicking "add resource" and selecting it via the UI. An agent can also request an introduction to a resource it thinks it needs, which you can then provide or deny.

This differs from most agent harnesses, where MCP servers are configured upfront, making broad access to all your services ambiently available to the agent in every chat. Capability-based introductions keep each agent restricted to only the access it actually needs for the job at hand.

4. Summary: Key Insights and Conclusions

4.1 The End of SaaS: From Hosted to Local Copies

Cloudflare OS represents a fundamental shift in software distribution:

Traditional Model: You create a web app, host it on your server, users connect to it.

New Model: You share code (Blueprint), each user runs their own copy.

Reasons for this shift:

1. AI Empowers Individuals — AI lets single developers build more than ever
2. Maintenance Burden — Single developers still struggle to maintain online services
3. Customization Needs — Users can modify their own copy with AI
4. No Requests Needed — No feature requests, users solve their own problems

Insight: The future of software may be "code as a service" rather than "software as a service".

4.2 Capability-Based Security: Beyond Access Control Lists

Traditional Access Control Lists (ACLs) assign fixed permissions to users/roles. Capability-based security assigns minimum permissions per operation.

Traditional ACLs:

user: admin
permissions:
  - read
  - write
  - delete

Capability-Based Security:

agent: code-reviewer
task: review-pr-123
capabilities:
  - read:repo/my-project
  - read:pr/123
  # No write, delete, or other permissions

Insight: In the AI Agent era, capability-based security is more appropriate than ACLs because:

• Agent tasks are dynamic
• Permissions should change with tasks
• Least privilege principle is easier to implement

4.3 Async Human-in-the-Loop: Solving Agent Stalling

Traditional human-in-the-loop setups require synchronous approval, causing agents to frequently stall.

Traditional Approach:

Agent tries action → Waits for user approval → User goes for coffee → Agent stalls → User returns → Agent continues

Cloudflare OS Approach:

Agent tries action → Gatekeeper simulates result → Agent continues → User approves later in bulk

Advantages:

• Agent doesn't stall
• User can batch-process when convenient
• Reduces temptation to "auto-approve"
• Maintains security while improving efficiency

Insight: Async human-in-the-loop is a necessary feature for AI tools.

4.4 Operating System Analogy: Platform Thinking for the AI Era

The analogy of Cloudflare OS to an operating system is not just marketing:

Traditional operating systems manage compute resources. Cloudflare OS manages AI workloads.

Insight: AI Agents need operating system-level management, not simple user-level permissions.

4.5 Strategic Value of Open Source

Cloudflare's choice to open-source Cloudflare OS:

1. Ecosystem Building — Encourages community to create new Gatekeepers and Blueprints
2. Standardization — Drives standardization of AI productivity tools
3. Trust Building — Open source code increases transparency and trust
4. Feedback Loop — Community usage feedback helps improve the product
5. Talent Attraction — Open source projects attract great developers

Insight: Open source is an effective strategy for building AI tool ecosystems.

5. Comparison with Traditional Solutions

5.1 Cloudflare OS vs Traditional SaaS

5.2 Cloudflare OS vs Other Agent Frameworks

6. Roadmap and Future Plans

6.1 Current Status

• Version: v2 (August 2026 early access)
• Status: Actively developing, complete rewrite from v1
• Maturity: Very capable, but still has many rough edges

6.2 Coming Soon

• workerd Self-Hosting: Documentation and tooling for running entirely on open-source workerd runtime
• More Gatekeepers: Continuous addition of new service integrations
• Community Contributions: May open up more contribution opportunities as project matures

6.3 Contributing Policy

At this time, we are not seeking outside contribution. External PRs are "donating" the easy part (writing code) while creating more work (reviewing). Only small, trivially-verified PRs (≤12 lines) accepted. Big ideas → discussions.

7. Conclusion

Cloudflare OS is not just an AI productivity tool — it represents a paradigm shift in how software is distributed and used. By turning every app into a private instance owned by the user (Gadget), by implementing a capability-based security framework (Gatekeeper), by enabling async human-in-the-loop mechanisms, Cloudflare OS sets a new standard for productivity in the AI era.

Core Value:

1. Security — Sandbox isolation + capability-based security
2. Control — Users own code and data
3. Customizable — AI can modify any app
4. Efficient — Async human-in-the-loop
5. Open — Apache-2.0 open source

Applicable Scenarios:

• Enterprises needing safe AI usage
• Organizations wanting user-customizable apps
• Teams valuing data privacy and control
• Developers wanting to build AI-native productivity tools

Cloudflare OS sets a new benchmark for productivity software in the AI era. Its design philosophy and practical experience are worth learning and referencing by all AI tool developers.

Reference Resources:

• GitHub Repository
• Official Deployment
• Deployment Starter Repo
• workerd Runtime
• Cap'n Web RPC