# Cloudflare OS Documentation

> Reference and operations documentation for Cloudflare OS, a Cloudflare Workers monorepo that runs sandboxed AI-built "gadgets", a Cap'n Web RPC kernel, and capability-scoped "gatekeeper" connectors. Written for operators deploying an instance, developers extending the kernel or connectors, and agents reading the RPC and configuration surface.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd)
- [GitHub repository](https://github.com/cloudflare/cloudflare-os)

## Repository

- Repository: cloudflare/cloudflare-os

- Generated: 2026-08-05T16:44:47.795Z
- Updated: 2026-08-05T16:45:21.765Z
- Runtime: Claude Code · claude-opus-5
- Format: Documentation
- Pages: 23

## Pages

- [Overview](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/01-overview.md): What Cloudflare OS exposes: a router origin, a Workers kernel, gadget sandboxes, and gatekeeper connectors. Covers the package layout, the OS-analogy mapping to real directories, runtime assumptions (Workers, Durable Objects, Worker Loader, Cap'n Web), and the first routes to read.
- [Installation](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/02-installation.md): Prerequisites (pnpm, pinned Node 22.14.0) and the three install paths: `pnpm run-local` for a single-command local stack, the hosted deploy wizard, and the starter repository. Documents what run-local builds, its source-hash stamp caching, and where local data is written.
- [Quickstart](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/03-quickstart.md): Run the full stack on workerd with `pnpm run-local`, reach http://localhost:8787, and confirm success. Includes the first prompts that exercise bundled format blueprints versus from-scratch gadget creation, and which prompts require a configured gatekeeper.
- [Local development](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/04-local-development.md): The two-terminal workflow: `pnpm dev-server` (router plus workers on wrangler) and `pnpm dev-client` (Vite on port 3000). Covers `.dev.vars` loading, generated dev wrangler files, dynamic gatekeeper service-binding discovery, the `--use-workers-ai-binding` and `--serve-frontend-assets` flags, and `VITE_BACKEND_HOST` port selection.
- [Gadgets and sandboxing](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/05-gadgets-and-sandboxing.md): How a gadget is isolated: a Dynamic Worker loaded through the `LOADER` binding with internet access disabled, a sandboxed client iframe restricted by Content-Security-Policy, and a Cap'n Web session bridged over postMessage. Covers per-gadget Durable Object storage, code versions, and the `global_fetch_strictly_public` SSRF posture.
- [Gatekeeper protocol](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/06-gatekeeper-protocol.md): The interfaces every connector implements: `GatekeeperVendor`, `GatekeeperConnectCallback`, `GatekeeperUser`, `GatekeeperUserVerifier`, and `Gatekeeper<Session>`. Documents `VendorDescription`, `AccountDescription` (`singleton`, `providesUi`, `providesAuth`), `ResourceDescription` and URL-pattern matching, agent catalog limits, and the `autoProvisionsAccount` disabled/optional/enabled mode resolution.
- [Observations, actions, and approval queues](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/07-observations-actions-and-approval-queues.md): The read/write split that makes asynchronous human-in-the-loop work: `ObservationDescription` (including `prohibitAllSharing`), `ActionDescription` and `ActionKind`, the `ObservationAuthorizer` and `ApprovalQueue` interfaces, simulated results while an action is pending, and `ActionState` transitions. Includes the MCP trust boundary where `readOnlyHint` decides observation versus queued action.
- [Blueprints](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/08-blueprints.md): What a blueprint captures and omits, the three binding types (`gatekeeper`, `aiModel`, `agentSpawner`), blueprint annotations stored on `GatekeeperRecord`, 128-bit hex IDs versus stable bundled IDs, and the one-way Gadget DO to User DO to Workers KV propagation with its `dirty` flag. Includes `.gadget` export/import and share-link semantics.
- [Sharing, roles, and observer re-verification](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/09-sharing-roles-and-observer-re-verification.md): Collaborator roles (`build` > `use`), the `use` allowlist enforced by `UseOverseerInterface` with its default-deny compile-time check, the two inert telemetry subscriptions, and share-link keys stored only as HMAC-SHA-256 hashes. Documents observer registration through `Gatekeeper.addObserver()`, verifier minting, and how a failing re-check blocks new observations.
- [Agent runtime and tools](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/10-agent-runtime-and-tools.md): The Code Mode agent loop: the tool set (`readFile`, `writeFile`, `editFile`, `executeCode`, `describeBinding`, `setGadgetBinding`, `createGadget`, `listBlueprints`, `listConnectableResources`, `requestConnection`, `webFetch`, `observeUserChanges`, `giveUp`), how `prepareChatBindings` folds ambient gatekeepers into `env` under `suggestedBindingName`, slash-command collection, and chat compaction checkpoints.
- [Configure gatekeeper credentials](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/11-configure-gatekeeper-credentials.md): Register a third-party OAuth app and wire its credentials into a connector. Covers the `${PUBLIC_BASE_URL}/gatekeeper/<name>/oauth` redirect-URI contract, the per-connector `CLIENT_ID`/`CLIENT_SECRET` secrets, `deploy-inputs.json` overrides with `setupSteps` and `consoleUrl`, dev seeding from shell variables, and connectors that need no OAuth app.
- [Build a gatekeeper](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/12-build-a-gatekeeper.md): Add a connector package: implement `GatekeeperVendor`, declare vendor/account/resource descriptions, own your Durable Object classes and migrations, and expose a session. Covers the configurator UI build into `src/generated`, the type-only `@gadgets/configurator-ui` helpers, `storage-schema.md`, structured logging with a `component`/`vendorId` logger, and installing by adding a `GATEKEEPER_*` binding.
- [Configure sign-in and AI Gateway billing](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/13-configure-sign-in-and-ai-gateway-billing.md): Turn on the optional public-service posture: `AUTH_GATEKEEPERS` allowlisting, `DISABLE_PASSWORD_AUTH`, email-keyed identity via `idFromName(email)`, incremental auth-versus-full scopes with transient login grants, and `ENABLE_CLOUDFLARE_LIMITS` free-tier plus credit top-up with the `$2` balance threshold and 5-minute balance cache.
- [Manage bundled format blueprints](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/14-manage-bundled-format-blueprints.md): Ship output formats as committed data. Covers the `.gadget` archive plus `.json` sidecar split, `FORMAT_BLUEPRINTS_DIR` for forks, generation into the gitignored `src/generated/format-blueprints.ts`, first-request installation into KV and R2, `pnpm import:format-blueprint` with `--new`, and why a deployed `blueprintId` must never be renamed.
- [RPC API reference](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/15-rpc-api-reference.md): The Cap'n Web interfaces shared between client and backend: `PublicApi`, `LoginAttempt`, `AuthenticatedApi`, `AdminApi`, and `Overseer`, plus supporting types (`GadgetMetadata`, `UiBundle`, `CodeUpdate`, `ActionLogEntry`, `AgentSpawnerConfig`, `AiModelConfig`, `ServerConfig`). Documents `OPEN_GADGET_ERROR_CODES`, `validateBindingName`, observer-config callbacks, and stub-disposal and promise-pipelining constraints.
- [Environment variables](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/16-environment-variables.md): Every backend environment variable and its default: `ADMINS`, `PUBLIC_BASE_URL`, the `CF_AI_GATEWAY*` family and its required account/token pair, `CF_ACCESS_AUD`/`CF_ACCESS_ISS`, `AUTH_GATEKEEPERS`, `DISABLE_PASSWORD_AUTH`, `ENABLE_CLOUDFLARE_LIMITS`, `DAILY_LLM_CALL_LIMIT`, `MINIMUM_CLOUDFLARE_BALANCE`, plus `VITE_FRONTEND_ERROR_REPORTING`, `MCP_PORTAL_URL`, and `MCP_PORTAL_TRUST_ANNOTATIONS`.
- [Admin configuration reference](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/17-admin-configuration-reference.md): The `AdminConfig` schema and its defaults: `signupsEnabled`, `siteName`, `instanceInstructions`, `announcement`, `banner`, `accentColor`, `disabledResources`, `disabledGatekeepers`, `ambientGatekeeperModes`, and `formats`. Covers length limits, the `AdminSettings` DO as sole writer mirroring to the reserved `.adminConfig` KV key, `readAdminConfig` hot-path reads, and why auth config is deliberately excluded.
- [Routing and worker bindings](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/18-routing-and-worker-bindings.md): How the router resolves requests: `/api/*` and `/blueprint-screenshot/*` to the backend, `/gatekeeper/<name>/*` derived by lowercasing `GATEKEEPER_*` env keys, everything else to `ASSETS` or the dev fallback, and inbound email dispatch to `GATEKEEPER_EMAIL`. Lists backend bindings (`BLUEPRINTS`, `BLUEPRINT_CONTENT`, `AVATARS`, `LOADER`, `BROWSER`, optional reporter and rate limiter) and DO migration tags.
- [Build, lint, and test](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/19-build-lint-and-test.md): The commands CI enforces and their ordering: `pnpm build` (recursive), `pnpm lint` composed of `lint:check` (oxlint) and `types:check` (recursive `tsc --noEmit`), and `pnpm test` (`node --test scripts/*.test.js` plus per-package suites). Documents generator prerequisites, the oxlint rule posture, and why type-aware rules are disabled in this monorepo.
- [Release pipeline](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/20-release-pipeline.md): Building and publishing a release: `build-release.mjs` byte-identical worker bundles and manifest generation, the placeholder contract (`$ACCOUNT_ID`, `$WORKER_NAME(...)`, `$SECRET(...)`, `$PUBLIC_BASE_URL`), `upload-release.mjs --candidate` staging, and the all-or-nothing manifest copy in `promote-release.mjs`. Covers required R2 variables, `NO_DEFAULT_CRED_INPUTS`, promote serialization, and golden-file regeneration with `UPDATE_GOLDEN=1`.
- [Integration testing](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/21-integration-testing.md): How `packages/integration-tests` boots the backend and gatekeepers as real workers in workerd via `createTestHarness()` and speaks Cap'n Web over the same `/api` WebSocket the browser uses. Documents why fake timers cannot work out-of-process, why a fixture gatekeeper covers overseer logic, the ~3s `server.reset()` cost and convention-based isolation, and the pluggable network interceptor.
- [Troubleshooting](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/22-troubleshooting.md): Known failure modes and their fixes: `OPEN_GADGET_ERROR_CODES` and observer binding failures, GitHub App versus OAuth App scope errors, missing generated modules on a clean checkout, gadget lockdown from `prohibitAllSharing`, free-tier and balance blocks, missing `WORKERS_AI` binding in gateway mode, no-op error reporting without its bindings, and RPC stub leaks or `useState` misuse.
- [Developer conventions and contributing](https://grok-wiki.com/public/docs/cloudflare-cloudflare-os-838773bb92dd/pages/23-developer-conventions-and-contributing.md): The rules a change must satisfy: pnpm only, kernel review standards for `workshop-backend` and `workshop-shared`, doc-comment every exported member, no hand-written RPC mirror interfaces with `as unknown as`, promise pipelining and stub disposal, structured logging field vocabularies and the never-log-secrets rule, opt-in frontend error reporting boundaries, and the narrow external-PR policy.

## Source Files

- `.gitlab-ci.yml`
- `.oxlintrc.json`
- `AGENTS.md`
- `CONTRIBUTING.md`
- `docs/ai-gateway-billing.md`
- `docs/blueprints.md`
- `docs/integration-testing.md`
- `docs/oauth-signin.md`
- `docs/observers.md`
- `docs/public-server.md`
- `docs/sharing.md`
- `package.json`
- `packages/backend-utils/src/error-reporting.ts`
- `packages/backend-utils/src/logger-core.ts`
- `packages/backend-utils/src/logger.ts`
- `packages/backend-utils/src/observability-context.ts`
- `packages/configurator-ui/src/index.ts`
- `packages/error-reporting/src/index.ts`
- `packages/gatekeeper-context/src/context-api.ts`
- `packages/gatekeeper-email/README.md`
- `packages/gatekeeper-github/deploy-inputs.json`
- `packages/gatekeeper-github/README.md`
- `packages/gatekeeper-github/src/github-configurators.ts`
- `packages/gatekeeper-github/src/github.ts`
- `packages/gatekeeper-google/README.md`
- `packages/gatekeeper-mcp-portal/README.md`
- `packages/gatekeeper-mcp/README.md`
- `packages/gatekeeper-scheduler/README.md`
- `packages/integration-tests/__tests__/observer-reverification.test.ts`
- `packages/integration-tests/fixtures/gatekeeper-test/src/test-gatekeeper.ts`
- `packages/integration-tests/src/harness.ts`
- `packages/integration-tests/src/network-interceptor.ts`
- `packages/integration-tests/src/rpc-client.ts`
- `packages/mcp-shared/README.md`
- `packages/mcp-shared/src/action-store.ts`
- `packages/mcp-shared/src/tools.ts`
- `packages/router/src/index.ts`
- `packages/workshop-backend/format-blueprints/README.md`
- `packages/workshop-backend/package.json`
- `packages/workshop-backend/scripts/build-format-blueprints.mjs`
- `packages/workshop-backend/scripts/import-format-blueprint.mjs`
- `packages/workshop-backend/src/admin-config.ts`
- `packages/workshop-backend/src/admin-settings.ts`
- `packages/workshop-backend/src/agent-catalog.ts`
- `packages/workshop-backend/src/agent-compaction.ts`
- `packages/workshop-backend/src/agent.ts`
- `packages/workshop-backend/src/ai-gateway.ts`
- `packages/workshop-backend/src/auth/config.ts`
- `packages/workshop-backend/src/auth/login-flow.ts`
- `packages/workshop-backend/src/auto-approval.ts`
- `packages/workshop-backend/src/blueprint-archive.ts`
- `packages/workshop-backend/src/client-errors.ts`
- `packages/workshop-backend/src/env.d.ts`
- `packages/workshop-backend/src/format-blueprints.ts`
- `packages/workshop-backend/src/overseer.ts`
- `packages/workshop-backend/src/provisioning-policy.ts`
- `packages/workshop-backend/src/server.ts`
- `packages/workshop-backend/src/sharing.ts`
- `packages/workshop-backend/src/slash-commands.ts`
- `packages/workshop-backend/src/user.ts`
- `packages/workshop-backend/src/web-fetch.ts`
- `packages/workshop-backend/wrangler.jsonc`
- `packages/workshop-shared/src/api.ts`
- `packages/workshop-shared/src/external-message-gateway.ts`
- `packages/workshop-shared/src/feature-flags.ts`
- `packages/workshop-shared/src/gatekeeper.ts`
- `packages/workshop-shared/src/limits.ts`
- `pnpm-workspace.yaml`
- `README.md`
- `run-dev-server.js`
- `scripts/build-gatekeeper-configurator.mjs`
- `scripts/dev-server-config.js`
- `scripts/dev-server-config.test.js`
- `scripts/release-manifest.test.js`
- `scripts/release-promote.test.js`
- `scripts/release/build-release.mjs`
- `scripts/release/manifest-lib.mjs`
- `scripts/release/promote-release.mjs`
- `scripts/release/upload-release.mjs`
- `scripts/run-local.mjs`
- `tsconfig.json`
- `wrangler.jsonc`