# cloudflare/cloudflare-os architecture

> Architecture diagram of the GitHub repository cloudflare/cloudflare-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloudflare/cloudflare-os
- Repository: https://github.com/cloudflare/cloudflare-os

## Overview

#### Purpose and entry points
Cloudflare OS is a multi-tenant AI productivity platform: users chat with agents, create/share isolated “Gadget” applications, and grant narrowly scoped external-service access through Gatekeepers. Local full-stack entry is `pnpm run-local` (served via Wrangler/workerd); development separates server and client. Primary runtime entry points are `packages/workshop-backend/src/server.ts` and `packages/workshop-frontend/src/main.tsx`.

#### Control plane: Workshop backend
The backend is the OS “kernel”: it authenticates users, opens/manages workspaces, applies sharing and access policy, provisions gadgets/gatekeepers, and exposes the RPC/API surface used by the frontend. It owns core deployment and provisioning decisions.
- `packages/workshop-backend/src/server.ts`
- `packages/workshop-backend/src/access.ts`
- `packages/workshop-backend/src/provisioning-policy.ts`

#### Agent execution and AI boundary
Agents are accountable to a user but operate with restricted capabilities. The backend selects/invokes configured AI models, manages agent lifecycle/context compaction, and mediates tool/action execution rather than granting ambient service access. AI Gateway billing and usage limits are a separate policy boundary.
- `packages/workshop-backend/src/agent.ts`
- `packages/workshop-backend/src/ai-invoke.ts`
- `packages/workshop-backend/src/ai-gateway-billing/limits/usage-checker.ts`

#### Gadgets, code state, and collaboration
Each user-facing gadget is an isolated application instance, backed by stateful Worker infrastructure. Gadget source/version state is stored and manipulated through a Git-oriented layer; worktree sessions support agent-driven edits. Clients communicate with gadget servers through Cap’n Web RPC, enabling agent-accessible application APIs. Sharing controls who can open or collaborate on an instance.
- `packages/workshop-backend/src/git-store.ts`
- `packages/workshop-backend/src/worktree-session.ts`
- `packages/workshop-backend/src/sharing.ts`

#### Blueprints and application generation
Blueprints are portable application-code templates used to create independent gadget instances, rather than shared SaaS instances. The bundled-blueprints package scans manifests/files and generates distributable blueprint assets; it includes reusable UI and real-time sync libraries plus built-in document, sheet, and slide applications.
- `packages/bundled-blueprints/src/index.ts`
- `packages/bundled-blueprints/src/generate.ts`
- `packages/bundled-blueprints/blueprints/workspace-slides/blueprint.json`

#### Gatekeepers: capability-secured integrations
Gatekeepers are separately deployed Worker packages that wrap third-party APIs, authorize users (often OAuth), expose constrained resources/actions, record observations/actions, and support simulated deferred approvals. `gatekeeper-kit` supplies shared primitives for credentials, endpoint handling, action journals, observers, simulations, and serialized execution; provider packages implement service-specific adapters and configurators.
- `packages/gatekeeper-kit/src/actions.ts`
- `packages/gatekeeper-kit/src/credential-stage.ts`
- `packages/gatekeeper-google/src/google.ts`
- `packages/gatekeeper-github/src/github.ts`
- `packages/gatekeeper-mcp/src/mcp.ts`

#### Frontend shell and sandbox boundary
The React/Vite frontend is the interactive shell for authentication, workspace/gadget navigation, chat, code editing/diffs, connection configuration, approvals, and sharing. It calls backend RPC through a central context. Gadget clients execute in sandboxed iframes and receive their server RPC session via `postMessage`, separating untrusted generated UI from the host shell.
- `packages/workshop-frontend/src/App.tsx`
- `packages/workshop-frontend/src/RpcContext.tsx`
- `packages/workshop-frontend/src/SandboxedGatekeeperApp.tsx`
- `packages/workshop-frontend/src/ChatInterface.tsx`

#### Runtime and external infrastructure
The system targets Cloudflare Workers and can run locally atop open-source workerd. Durable Objects provide per-workspace and per-gadget state; Dynamic Workers/Facets provide isolated gadget and gatekeeper execution/bindings. Integrations include Cloudflare, Google, GitHub, Slack, Notion, Confluence, Supabase, Home Assistant, Spotify, ZoomInfo, email, and MCP servers. Shared protocol/client abstractions live in:
- `packages/mcp-shared/src/session.ts`
- `packages/workshop-shared/src/api.ts`
- `wrangler.jsonc`

Main entry points: [`packages/workshop-backend/src/server.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/server.ts) (Workshop backend), [`packages/workshop-backend/src/agent.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/agent.ts) (Agent lifecycle), [`packages/gatekeeper-google/src/google.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-google/src/google.ts) (Provider gatekeepers), [`packages/workshop-backend/src/ai-invoke.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/ai-invoke.ts) (AI model invocation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend shell"]
  node_frontend_app["React workspace shell<br/>frontend<br/>[App.tsx]"]
  node_rpc_context["Backend RPC context<br/>client RPC<br/>[RpcContext.tsx]"]
  node_chat["Agent chat<br/>UI feature<br/>[ChatInterface.tsx]"]
  node_sandbox{{"Sandboxed gadget client<br/>iframe boundary"}}
end

subgraph group_control["Workshop control plane"]
  node_server["Workshop backend<br/>Workers RPC server<br/>[server.ts]"]
  node_access["Access &amp; sharing policy<br/>authorization<br/>[access.ts]"]
  node_provisioning["Provisioning policy<br/>deployment policy"]
  node_agent["Agent lifecycle<br/>agent orchestration<br/>[agent.ts]"]
  node_ai_invoke["AI model invocation<br/>AI boundary<br/>[ai-invoke.ts]"]
  node_usage_limits["AI usage limits<br/>billing policy<br/>[usage-checker.ts]"]
end

subgraph group_gadgets["Gadget generation &amp; state"]
  node_blueprint_build["Blueprint asset builder<br/>build pipeline<br/>[generate.ts]"]
  node_blueprints["Bundled blueprints<br/>application templates<br/>[index.ts]"]
  node_gadget_state[("Gadget Git state<br/>source/version store<br/>[git-store.ts]")]
  node_worktree["Agent worktree session<br/>editing session"]
end

subgraph group_gatekeepers["Gatekeeper integrations"]
  node_gatekeeper_kit["Gatekeeper kit<br/>capability primitives<br/>[actions.ts]"]
  node_gatekeepers["Provider gatekeepers<br/>integration Workers<br/>[google.ts]"]
end

subgraph group_runtime["Runtime &amp; external services"]
  node_gadget_runtime["Isolated gadget runtime<br/>Dynamic Worker / Facet"]
  node_external(("External APIs &amp; MCP servers<br/>third-party services"))
  node_workers{{"Cloudflare Workers platform<br/>execution platform<br/>[wrangler.jsonc]"}}
  node_ai_gateway(("AI Gateway<br/>model gateway"))
end

node_frontend_app -->|"uses"| node_rpc_context
node_chat -->|"sends agent requests"| node_rpc_context
node_rpc_context -->|"RPC"| node_server
node_frontend_app -->|"hosts"| node_sandbox
node_sandbox -->|"postMessage RPC session"| node_gadget_runtime
node_server -->|"enforces"| node_access
node_server -->|"applies"| node_provisioning
node_server -->|"manages"| node_agent
node_agent -->|"invokes models"| node_ai_invoke
node_ai_invoke -->|"checks"| node_usage_limits
node_ai_invoke -->|"model requests"| node_ai_gateway
node_server -->|"creates gadgets from"| node_blueprints
node_blueprint_build -->|"generates"| node_blueprints
node_server -->|"stores source state"| node_gadget_state
node_agent -->|"edits through"| node_worktree
node_worktree -->|"updates"| node_gadget_state
node_server -->|"provisions"| node_gadget_runtime
node_agent -->|"mediated actions"| node_gatekeepers
node_gatekeepers -->|"implements with"| node_gatekeeper_kit
node_gatekeepers -->|"authorized API calls"| node_external
node_gadget_runtime -->|"runs on"| node_workers
node_server -->|"runs on"| node_workers
node_gatekeepers -->|"deployed as"| node_workers

click node_frontend_app "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/App.tsx"
click node_rpc_context "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/RpcContext.tsx"
click node_chat "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/ChatInterface.tsx"
click node_sandbox "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/SandboxedGatekeeperApp.tsx"
click node_server "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/server.ts"
click node_access "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/access.ts"
click node_provisioning "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/provisioning-policy.ts"
click node_agent "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/agent.ts"
click node_ai_invoke "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/ai-invoke.ts"
click node_usage_limits "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/ai-gateway-billing/limits/usage-checker.ts"
click node_blueprint_build "https://github.com/cloudflare/cloudflare-os/blob/main/packages/bundled-blueprints/src/generate.ts"
click node_blueprints "https://github.com/cloudflare/cloudflare-os/blob/main/packages/bundled-blueprints/src/index.ts"
click node_gadget_state "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/git-store.ts"
click node_worktree "https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/worktree-session.ts"
click node_gatekeeper_kit "https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-kit/src/actions.ts"
click node_gatekeepers "https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-google/src/google.ts"
click node_workers "https://github.com/cloudflare/cloudflare-os/blob/main/wrangler.jsonc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_rpc_context,node_chat,node_sandbox toneBlue
class node_server,node_access,node_provisioning,node_agent,node_ai_invoke,node_usage_limits toneAmber
class node_blueprint_build,node_blueprints,node_gadget_state,node_worktree toneMint
class node_gatekeeper_kit,node_gatekeepers toneRose
class node_gadget_runtime,node_external,node_workers,node_ai_gateway toneIndigo
```

## Components

### Frontend shell

- [React workspace shell](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/App.tsx): frontend · Authentication, navigation, chat, editing, approvals, and sharing UI. · `packages/workshop-frontend/src/App.tsx`
- [Backend RPC context](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/RpcContext.tsx): client RPC · `packages/workshop-frontend/src/RpcContext.tsx`
- [Agent chat](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/ChatInterface.tsx): UI feature · `packages/workshop-frontend/src/ChatInterface.tsx`
- [Sandboxed gadget client](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-frontend/src/SandboxedGatekeeperApp.tsx): iframe boundary · Passes gadget RPC sessions through postMessage. · `packages/workshop-frontend/src/SandboxedGatekeeperApp.tsx`

### Workshop control plane

- [Workshop backend](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/server.ts): Workers RPC server · OS kernel and primary API surface. · `packages/workshop-backend/src/server.ts`
- [Access & sharing policy](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/access.ts): authorization · `packages/workshop-backend/src/access.ts`
- [Provisioning policy](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/provisioning-policy.ts): deployment policy · `packages/workshop-backend/src/provisioning-policy.ts`
- [Agent lifecycle](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/agent.ts): agent orchestration · Maintains accountable agent context and mediates tools. · `packages/workshop-backend/src/agent.ts`
- [AI model invocation](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/ai-invoke.ts): AI boundary · `packages/workshop-backend/src/ai-invoke.ts`
- [AI usage limits](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/ai-gateway-billing/limits/usage-checker.ts): billing policy · `packages/workshop-backend/src/ai-gateway-billing/limits/usage-checker.ts`

### Gadget generation & state

- [Blueprint asset builder](https://github.com/cloudflare/cloudflare-os/blob/main/packages/bundled-blueprints/src/generate.ts): build pipeline · Scans templates and generates distributable blueprint assets. · `packages/bundled-blueprints/src/generate.ts`
- [Bundled blueprints](https://github.com/cloudflare/cloudflare-os/blob/main/packages/bundled-blueprints/src/index.ts): application templates · Portable templates for independent gadget applications. · `packages/bundled-blueprints/src/index.ts`
- [Gadget Git state](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/git-store.ts): source/version store · `packages/workshop-backend/src/git-store.ts`
- [Agent worktree session](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/worktree-session.ts): editing session · `packages/workshop-backend/src/worktree-session.ts`

### Gatekeeper integrations

- [Gatekeeper kit](https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-kit/src/actions.ts): capability primitives · Credentials, actions, journals, observers, simulations, and serialized execution. · `packages/gatekeeper-kit/src/actions.ts`
- [Provider gatekeepers](https://github.com/cloudflare/cloudflare-os/blob/main/packages/gatekeeper-google/src/google.ts): integration Workers · Constrained third-party service adapters. · `packages/gatekeeper-google/src/google.ts`

### Runtime & external services

- **Isolated gadget runtime**: Dynamic Worker / Facet · Per-gadget stateful application server with Cap’n Web RPC.
- **External APIs & MCP servers**: third-party services · Google, GitHub, Slack, Notion, and other connected services.
- [Cloudflare Workers platform](https://github.com/cloudflare/cloudflare-os/blob/main/wrangler.jsonc): execution platform · Workers, Durable Objects, Dynamic Workers, and Facets. · `wrangler.jsonc`
- **AI Gateway**: model gateway · Model access, billing, and usage enforcement boundary.

## Connections

- React workspace shell → Backend RPC context: uses
- Agent chat → Backend RPC context: sends agent requests
- Backend RPC context → Workshop backend: RPC
- React workspace shell → Sandboxed gadget client: hosts
- Sandboxed gadget client → Isolated gadget runtime: postMessage RPC session
- Workshop backend → Access & sharing policy: enforces
- Workshop backend → Provisioning policy: applies
- Workshop backend → Agent lifecycle: manages
- Agent lifecycle → AI model invocation: invokes models
- AI model invocation → AI usage limits: checks
- AI model invocation → AI Gateway: model requests
- Workshop backend → Bundled blueprints: creates gadgets from
- Blueprint asset builder → Bundled blueprints: generates
- Workshop backend → Gadget Git state: stores source state
- Agent lifecycle → Agent worktree session: edits through
- Agent worktree session → Gadget Git state: updates
- Workshop backend → Isolated gadget runtime: provisions
- Agent lifecycle → Provider gatekeepers: mediated actions
- Provider gatekeepers → Gatekeeper kit: implements with
- Provider gatekeepers → External APIs & MCP servers: authorized API calls
- Isolated gadget runtime → Cloudflare Workers platform: runs on
- Workshop backend → Cloudflare Workers platform: runs on
- Provider gatekeepers → Cloudflare Workers platform: deployed as