The Problem

Enterprises need a single, secure workspace where AI agents can read internal knowledge, build lightweight “gadgets”, and act on company‑specific systems without exposing secrets or creating uncontrolled SaaS dependencies.

What This Does

cloudflare-os delivers a self‑hosted AI productivity platform built on Cloudflare Workers. The UI lives in packages/configurator-ui/src/index.ts and the backend utilities in packages/backend-utils/src/*. Each integration (GitHub, Google, Confluence, etc.) is a separate gatekeeper package under packages/gatekeeper‑*, exposing a sandboxed API that agents call. The core data model and shared client code sit in packages/mcp-shared/src/*, which is imported by virtually every gatekeeper and the workshop front‑end.

How It Is Wired

  1. Startup – pnpm run-local (see README) launches wrangler which reads the entry point packages/configurator-ui/src/index.ts. This imports the workshop‑frontend UI (packages/workshop-frontend/src/*) and registers the client SDK from packages/mcp-shared/src/client.ts.
  1. Agent request flow – UI component ChatInterface (packages/workshop-frontend/src/ChatInterface.tsx) captures a user prompt and calls client.sendMessage. client.ts (most‑connected module, 33 inbound imports) routes the request to the appropriate gatekeeper via HTTP calls defined in each gatekeeper’s src/*.ts (e.g., gatekeeper-github/src/github-api.ts).
  1. Gatekeeper processing – Each gatekeeper package exports a handler used by the Cloudflare Worker (wrangler.jsonc). For example, gatekeeper-github/src/github.ts validates the request, invokes the GitHub API, and returns a typed response.
  1. Observability & error handling – Centralised in packages/backend-utils/src/error-reporting.ts and packages/backend-utils/src/logger.ts. All gatekeepers import these utilities, so any exception bubbles to error-reporting.test.ts for verification.
  1. Data persistence – KV interactions are abstracted in gatekeeper-context/src/collection‑kv.ts and registry-do.ts. These modules are the only points that touch Cloudflare KV/DO, limiting external side‑effects.

Blast‑radius hotspots –

  • packages/mcp-shared/src/client.ts (33 dependents) – any change propagates widely.
  • Large files such as gatekeeper-confluence/src/confluence-api.ts (1,249 lines) and workshop-backend/src/overseer.ts (high instability) are hard to reason about and appear in import cycles.

Circular dependencies – 19 modules form cycles, notably workshop-backend/src/ai-gateway.ts, workshop-backend/src/user.ts, and mcp-shared/src/fetch.ts. These increase cognitive load and risk of runtime errors.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/cloudflare-os
cd cloudflare-os

# Install pnpm (if not present) and project deps
npm i -g pnpm
pnpm install

# Run the full stack locally (wrangler + workerd)
pnpm run-local

Configuration – Environment variables required by gatekeepers are documented in each package’s README (e.g., CF_AI_GATEWAY_TOKEN for the AI gateway). They are read via process.env in the respective src/*.ts files. No .env template is provided; create one matching the variables referenced in the source.

Running a specific gatekeeper – Deploy with Wrangler using the package’s wrangler.jsonc, e.g.:

cd packages/gatekeeper-github
pnpm wrangler publish

Real‑World Use

A product team wants to auto‑generate release notes from GitHub issues. They enable the GitHub gatekeeper, then in the chat UI type “Summarize all closed issues for the last sprint”. ChatInterface sends the prompt to client.sendMessage, which forwards it to gatekeeper-github/src/github.ts. The gatekeeper fetches issues via the GitHub API, runs the LLM prompt, and returns a markdown summary that the UI renders instantly.

Code Health & Issues

  • Critical – Secrets (CF_AI_GATEWAY_ACCOUNT_ID, CF_AI_GATEWAY_TOKEN) are exposed in .github/workflows/bonk.yml. Fix: move secret‑using steps to workflow_run jobs or gate on a protected environment.
  • High – GitHub Actions pins are version tags (contributor-assistant/github-action@v2.6.1). Fix: replace with exact commit SHA and let Dependabot update.
  • Medium – No Dependabot/Renovate config; 27 manifests lack automated updates. Fix: add .github/dependabot.yml.
  • Medium – No dependency‑vulnerability scan in CI. Fix: integrate dependency-review-action or osv-scanner.
  • Low – Workflow jobs lack timeout-minutes. Fix: set reasonable timeouts.
  • Low – Repository missing convention files (.editorconfig, .gitattributes, formatter config). Fix: add them to enforce consistent style.

Additional findings from static analysis:

  • Hub module packages/mcp-shared/src/client.ts (33 dependents) – keep stable, extract volatile logic.
  • Oversized files (packages/workshop-backend/src/user.ts, gatekeeper-confluence/src/confluence-api.ts) – split by responsibility.
  • Import cycles involving ai-gateway.ts, user.ts, fetch.ts – break by extracting shared types or using dynamic imports.
  • Deep nesting (max depth 9) in overseer.ts and UI components – refactor to early returns/guard clauses.
  • Repeated 6‑line code blocks across 118 files – DRY into shared helpers.

The Bottom Line

cloudflare-os provides a comprehensive, modular framework for AI‑augmented workflows on Cloudflare Workers, with clear separation of UI, backend utilities, and per‑system gatekeepers. The codebase is functional but concentrates risk in a few large, highly connected modules and contains several security‑process gaps that must be addressed before production use. Teams comfortable with TypeScript and Cloudflare’s edge platform can adopt it, provided they remediate the critical secret exposure and refactor the identified hotspots.