Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/cloudflare-os/llms.txt

Use this file to discover all available pages before exploring further.

Cloudflare OS supports two local run modes. Use pnpm run-local when you just want to try it out — it starts the entire stack as a single command in under a minute. Use the two-terminal dev mode when you’re actively developing, because it keeps the frontend hot-reload server running separately from the backend so UI changes appear instantly without a full rebuild.

​
Prerequisites

Before running locally you need:
  • Node.js v18 or later
  • pnpm — install with npm install -g pnpm or via the pnpm docs
  • No Cloudflare account required for local runs — everything uses the local workerd runtime

​
Quick local run

pnpm run-local builds the frontend bundle, generates the format blueprints module, and starts all Workers (router, backend, and every discovered gatekeeper) under wrangler in a single process.
1

Clone the repository

git clone https://github.com/cloudflare/cloudflare-os
cd cloudflare-os
2

Install dependencies

pnpm install
3

Start the stack

pnpm run-local
4

Open the app

Visit http://localhost:8787 in your browser and create your first account.
All persistent data (Durable Objects, KV, R2) is stored in a local .wrangler subdirectory. Delete it to wipe state and start fresh.
pnpm run-local is not intended for production use. It runs the Workers runtime in development mode, which disables some platform-level security boundaries that production deployments rely on.

​
Development mode (two terminals)

When you’re making changes to the frontend or backend, run the frontend Vite dev server and the wrangler backend server separately so that edits to React components and styles reload instantly.
1

Terminal 1 — start the backend

pnpm dev-server
This runs run-dev-server.js, which generates wrangler.dev.jsonc files for all discovered gatekeeper packages and starts wrangler dev with every config in a single multi-worker process.
2

Terminal 2 — start the frontend

pnpm dev-client
This starts the Vite dev server on port 3000.
3

Open the app

Visit http://localhost:3000. The frontend proxies API requests to the wrangler process on port 8787 automatically.
Use pnpm dev-client (port 3000) for all frontend development — Vite’s hot module replacement means changes to React components and CSS take effect in the browser without reloading the page or restarting the backend. Use pnpm run-local (port 8787) when you only care about the backend behavior and don’t need fast frontend iteration.

​
Configuring environment variables

Local configuration lives in a root-level .dev.vars file. This file is gitignored and is loaded automatically by pnpm dev-server — any KEY=VALUE line in it is injected into the wrangler process as an environment variable. Create .dev.vars at the root of the repo (next to package.json): 
# .dev.vars — gitignored, never commit this file

PUBLIC_BASE_URL=http://localhost:8787
AUTH_GATEKEEPERS=github,google

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
The variables GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET and GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (and their equivalents for other providers) are “shared” credentials — run-dev-server.js automatically seeds them into each matching gatekeeper Worker so you only need to set them once. For the full list of supported variables, including AI Gateway billing options, see Configuration.

​
Gatekeeper credentials in local dev

Each gatekeeper Worker reads its CLIENT_ID and CLIENT_SECRET from one of two places (in priority order):
  1. Per-package .env file — create packages/gatekeeper-github/.env, packages/gatekeeper-google/.env, etc. with CLIENT_ID= and CLIENT_SECRET= lines. These files are gitignored.
  2. Root .dev.vars shared credentials — run-dev-server.js reads the shared vars (e.g. GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET) and injects them into each gatekeeper’s generated wrangler.dev.jsonc. The per-package .env takes precedence if both are set.
CLIENT_ID=your-github-client-id
CLIENT_SECRET=your-github-client-secret
For a full OAuth app setup guide — including where to register redirect URIs and which scopes each provider requires — see Authentication.

Build docs developers (and LLMs) love

Get started for freeTalk to us