cloudflare/cloudflare-os-starter

cloudflare/cloudflare-os-starter

Description: A guide for customizing your Cloudflare OS deployment

Language: JavaScript

License: Apache-2.0

Stars: 83

Forks: 17

Open issues: 1

Created: 2026-08-03T21:36:32Z

Pushed: 2026-08-05T12:35:13Z

Default branch: main

Fork: no

Archived: no

README:

Customized for your Company

Deploy a pinned Cloudflare OS release with branding, sign-in, integrations, routes, and upgrades under your control.

> [!IMPORTANT] > Cloudflare OS is early-access software. Pin upstream releases, review changes, and verify the trust boundary before every production upgrade.

Four steps

1. Install the dependencies and run pnpm exec wrangler login. 2. Fill in deployment.jsonc: account ID, Worker names, hostname, Access audience, admin emails. 3. Run pnpm check, then pnpm deploy. 4. Open /admin and set the site name, logo, and accent color; branding needs no redeploy.

[Deploy](#deploy) and [Customization](#customization) expand each step. Everything else on this page is optional reading.

Overview

This repository adds deployment controls around a pinned Cloudflare OS release without modifying the upstream source.

| Control | What you own | | --- | --- | | Branding | Site name, logo, and accent color, changed in [/admin](docs/customization.md#branding) without a deploy | | Identity | The sign-in method and administrator allowlist; this starter deploys Cloudflare Access mode | | Routing | A production Custom Domain or a workers.dev evaluation route | | Data | Existing KV/R2 resources or automatic provisioning | | Integrations | Wrapper-owned Gatekeepers and service bindings without patching upstream | | AI | No platform model by default; opt into Workers AI and AI Gateway when needed | | Operations | [Structured logs, traces, explicit error reports](docs/observability.md), validation, deployment order, and upgrades |

Architecture

The deploy command derives temporary Wrangler files from upstream base configs, builds the frontend in Cloudflare Access mode, deploys the private Error Reporter and Gatekeepers before the Workshop, and removes generated files even on failure. Secrets never enter tracked configuration.

If you only want branding

A hosted flow deploys the same upstream release to your Cloudflare account without this repository. It builds nothing locally, configures sign-in and your admin emails for you, and leaves the whole /admin surface intact: site name, logo, accent color, announcements, agent instructions, featured blueprints, and which connectors your users can reach. Built-in Gatekeepers such as GitHub and Google are still yours to connect with your own OAuth credentials.

Anything past that needs your own code or settings, which is what this repository is for: custom Gatekeepers, customized error reporting, your own Worker names, reusing storage you already have, choosing how much logging to keep, and a pinned version you upgrade when you decide. Hosted deployments also run on a workers.dev address, so deploy from here if you want the app on your own domain, or the email Gatekeeper, which needs a zone. Come back when branding stops being enough.

Deploy

1. Prepare the workspace

Install Node.js 24, pnpm 11, and authenticate Wrangler:

git submodule update --init
pnpm install
pnpm --dir cloudflare-os install
pnpm exec wrangler login

Your account needs Workers, KV, R2, Browser Rendering, and Dynamic Worker Loaders. AI products are optional.

2. Configure sign-in

Cloudflare OS supports several sign-in methods. This starter deploys Cloudflare Access mode, which verifies identity before a request reaches the Worker. See [Sign-in methods](docs/customization.md#sign-in-methods) for the alternatives and what switching involves.

1. Choose a Workshop hostname in an active Cloudflare zone, such as os.example.com. 2. Create a self-hosted Access application for that hostname. 3. Copy its application audience tag. 4. Open [deployment.jsonc](deployment.jsonc) and replace the active placeholders. Every control is annotated in place.

Wrangler creates DNS and TLS for the custom domain at deploy time. For an evaluation without a zone, switch the annotated route to { "workersDev": true }.

3. Validate and deploy

pnpm check
pnpm deploy

With resource values left as null, Wrangler creates the three KV namespaces and R2 bucket automatically and reconnects them on later deploys. Set explicit IDs or a bucket name when the deployment must reuse existing resources.

AI is disabled by default. The application can deploy without an AI Gateway or token; see [AI models](docs/customization.md#ai-models) to enable deployment-funded models.

Backend error reporting is enabled without a vendor account. Explicit upstream issue events become structured logs in the private Error Reporter Worker; see [Observability and error reporting](docs/observability.md).

4. Verify the deployment

• Open the Workshop hostname and confirm Access signs in with the expected identity.
• Open /admin, confirm the email is an administrator, and set Context and Custom Gatekeepers to disabled, optional, or enabled.
• Enable the Custom Gatekeeper, ask for deployment...