cloudflare/cloudflare-os

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