docs/starter-reference.md

1# Cloudflare OS starter deployment reference
2
3Preserved from [cloudflare/cloudflare-os-starter](https://github.com/cloudflare/cloudflare-os-starter) at `3d21147` under Apache-2.0 (see [NOTICE](../NOTICE)), with Fork Horse corrections where the deploy differs. Fork Horse's own deployment steps are in the [README](../README.md#deploy-your-own-instance).
4
5The original starter instructions below are preserved. Apply deployment values to the ignored local overlay described in the README; the template remains public-safe. These instructions cover the OS base (the starter's sample custom gatekeeper is retired and no longer deployed), while core prerequisites and open gates are covered in the README.
6
7<p align="center">
8  <img src="assets/cloudflareOS.svg" alt="Cloudflare OS" width="480">
9</p>
10
11<h1 align="center">Customized for your Company</h1>
12
13<p align="center">
14  Deploy a pinned Cloudflare OS release with branding, sign-in, integrations, routes, and upgrades under your control.
15</p>
16
17<p align="center">
18  <a href="https://developers.cloudflare.com/workers/"><img alt="Cloudflare Workers" src="https://img.shields.io/badge/Cloudflare-Workers-F6821F?logo=cloudflare&logoColor=white"></a>
19  <a href="https://nodejs.org/"><img alt="Node.js 24.19+" src="https://img.shields.io/badge/Node.js-24.19+-5FA04E?logo=nodedotjs&logoColor=white"></a>
20  <a href="https://pnpm.io/"><img alt="pnpm 11.17" src="https://img.shields.io/badge/pnpm-11.17-F69220?logo=pnpm&logoColor=white"></a>
21  <a href="https://www.typescriptlang.org/"><img alt="TypeScript 7" src="https://img.shields.io/badge/TypeScript-7-3178C6?logo=typescript&logoColor=white"></a>
22  <a href="https://github.com/cloudflare/cloudflare-os"><img alt="Cloudflare OS upstream" src="https://img.shields.io/badge/upstream-Cloudflare_OS-24292F?logo=github"></a>
23</p>
24
25> [!IMPORTANT]
26> Cloudflare OS is early-access software. Pin upstream releases, review changes, and verify the trust boundary before every production upgrade.
27
28## Four steps
29
301. Install the dependencies and run `pnpm exec wrangler login`.
312. Copy `deployment.jsonc` to the gitignored `deployment.local.jsonc` and fill that in: account ID, Worker names, hostname, Access audience, admin emails.
323. Run `pnpm check`, then `pnpm deploy`.
334. Open `/admin` and set the site name, logo, and accent color; branding needs no redeploy.
34
35[Deploy](#deploy) and [Customization](#customization) expand each step. Everything else on this page is optional reading.
36
37## Overview
38
39This repository adds deployment controls around a pinned [Cloudflare OS](https://github.com/cloudflare/cloudflare-os) release without modifying the upstream source.
40
41| Control | What you own |
42| --- | --- |
43| Branding | Site name, logo, and accent color, changed in [`/admin`](customization.md#branding) without a deploy |
44| Identity | The sign-in method and administrator allowlist; this starter deploys [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/) mode |
45| Routing | A production [Custom Domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) or a `workers.dev` evaluation route |
46| Data | Existing KV/R2 resources or [automatic provisioning](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning) |
47| Integrations | Wrapper-owned Gatekeepers and service bindings without patching upstream |
48| AI | A [Workers AI](https://developers.cloudflare.com/workers-ai/) model catalog through [AI Gateway](https://developers.cloudflare.com/ai-gateway/) out of the box, with no API token; which providers and which gateway |
49| Operations | [Structured logs, traces, explicit error reports](observability.md), validation, deployment order, and upgrades |
50
51### Architecture
52
53<img src="assets/architecture.svg" alt="Cloudflare OS deployment architecture: users reach one public route, owned by the router Worker, which serves the frontend and proxies /api to the Workshop backend and /gatekeeper/&lt;name&gt; to the matching Gatekeeper. Behind it is the pinned Cloudflare OS release, holding the Workshop kernel, Gadgets, Blueprints, and the default Gatekeepers. Service bindings connect it to the Workers and resources this repository owns: AI Gateway with no API token, custom Gatekeepers, the Error Reporter, and KV and R2 storage.">
54
55The OS base is six Workers. A **router** owns the public route and serves the frontend, proxying `/api` to the Workshop backend and `/gatekeeper/<name>` to whichever Gatekeeper the binding name matches; the Workshop, the Context and Scheduler Gatekeepers, the MCP connector and the Error Reporter sit behind it with no route of their own, reachable only over service bindings. Fork Horse adds its core and gatekeeper Workers, described in the README.
56
57The deploy command derives temporary Wrangler files from upstream base configs, builds the frontend in Cloudflare Access mode, deploys the private Error Reporter, the Gatekeepers and the Workshop before the router that binds them, and removes generated files even on failure. Secrets never enter tracked configuration.
58
59### If you only want branding
60
61A 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.
62
63<a href="https://os.cloudflare.app/deploy"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare"></a>
64
65Anything 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.
66
67## Deploy
68
69### 1. Prepare the workspace
70
71Install [Node.js 24.19 or newer](https://nodejs.org/) (the deploy scripts are TypeScript run directly by `node`), [pnpm 11.17](https://pnpm.io/installation), and authenticate [Wrangler](https://developers.cloudflare.com/workers/wrangler/commands/#login):
72
73```sh
74git submodule update --init
75pnpm install
76pnpm --dir cloudflare-os install
77pnpm exec wrangler login
78```
79
80Your account needs [Workers](https://developers.cloudflare.com/workers/), [KV](https://developers.cloudflare.com/kv/), [R2](https://developers.cloudflare.com/r2/), [Browser Rendering](https://developers.cloudflare.com/browser-rendering/), and [Dynamic Worker Loaders](https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/). It also needs [Workers AI](https://developers.cloudflare.com/workers-ai/) and [AI Gateway](https://developers.cloudflare.com/ai-gateway/), which the default model catalog runs on; only turning that catalog off makes them dispensable. [Artifacts](https://developers.cloudflare.com/artifacts/) is optional.
81
82### 2. Configure sign-in
83
84Cloudflare OS supports several sign-in methods. This starter deploys [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/) mode, which verifies identity before a request reaches the Worker. See [Sign-in methods](customization.md#sign-in-methods) for the alternatives and what switching involves.
85
861. Choose a public hostname in an [active Cloudflare zone](https://developers.cloudflare.com/dns/zone-setups/), such as `os.example.com`.
872. Create a [self-hosted Access application](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/self-hosted-public-app/) for that hostname.
883. Copy its [application audience tag](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/#get-your-aud-tag).
894. Copy [`deployment.jsonc`](../deployment.jsonc) to the gitignored `deployment.local.jsonc` and replace the active placeholders there. Every control is annotated in place.
90
91The hostname belongs to the router, the only Worker here with a public route. Wrangler creates its DNS and TLS at deploy time. For an evaluation without a zone, switch the annotated route to `{ "workersDev": true }` and set `publicBaseUrl` to the resulting origin.
92
93### 3. Validate and deploy
94
95```sh
96pnpm check
97pnpm deploy
98```
99
100With 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.
101
102A Workers AI model catalog is enabled by default and needs no API token: the Workshop reaches AI Gateway over its `WORKERS_AI` binding, which is pre-authenticated inside your account. See [AI models](customization.md#ai-models) to add providers, change the gateway, or turn the catalog off.
103
104Git-backed Context collections are disabled by default. Accounts with Artifacts access can enable them in `context.artifacts`; see [Context Artifacts](customization.md#context-artifacts).
105
106Backend 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](observability.md).
107
108### 4. Verify the deployment
109
110- Open the router's hostname and confirm Access signs in with the expected identity, and that it is the only public route into the deployment.
111- Open `/admin`, confirm the email is an administrator, and set Context, Scheduler and Custom Gatekeepers to disabled, optional, or enabled.
112- If Context Artifacts is enabled, create a Git-backed collection and confirm its repository can be populated and refreshed.
113- In Admin → Gatekeepers, enable the Fork Horse gatekeeper, connect an enrolled agent, and confirm the Fork Horse app opens in the sidebar.
114- Open the Error Reporter Worker's [Workers Logs](https://developers.cloudflare.com/workers/observability/logs/workers-logs/) and verify its structured `error_report` query surface.
115- Ask an agent to schedule something a few minutes out, and confirm it runs — that exercises the Scheduler Gatekeeper end to end.
116- Review logs for the router, Workshop, Context, Scheduler, MCP connector, Fork Horse core and gatekeeper, and Error Reporter Workers.
117
118## Customization
119
120| Customize | Best place | Deploy required |
121| --- | --- | --- |
122| Site name, logo, color, announcements, instructions, connectors | `/admin` | No |
123| Sign-in, routes, AI, storage, observability, Worker identities | `deployment.local.jsonc` (copied from [`deployment.jsonc`](../deployment.jsonc)) | Yes |
124| Logs, traces, error destinations, browser reporting | [Observability guide](observability.md) | Sometimes |
125| Organization APIs and capabilities | [`packages/custom-gatekeeper`](../packages/custom-gatekeeper/README.md) (a source example; the deploy no longer ships it, so wire your own) | Yes |
126| Product behavior unavailable through Worker boundaries | Pinned upstream fork/commit | Yes |
127
128The complete control reference and recipes live in [Customization](customization.md). The upstream [`write-gatekeeper` skill](https://github.com/cloudflare/cloudflare-os/blob/main/.agents/skills/write-gatekeeper/SKILL.md) covers richer integrations.
129
130## Operations and upgrades
131
132- Stream production events with [`wrangler tail`](https://developers.cloudflare.com/workers/observability/logs/real-time-logs/).
133- Triage explicit failures and choose export destinations with the [observability guide](observability.md).
134- Roll a Worker back from its dashboard deployment history or with [`wrangler rollback`](https://developers.cloudflare.com/workers/versions-and-deployments/rollbacks/).
135- Follow the [upgrade checklist](customization.md#upgrade) before changing the pinned submodule.
136- Review the upstream Cloudflare OS documentation and release history before adopting behavior changes.
137
138### Moving here from the hosted deploy (os.cloudflare.app/deploy)
139
140Ejecting an instance created by the hosted flow means redeploying over Workers that already hold your data. Worker names, storage IDs, the public URL, and AI Gateway all have to be carried across by hand, and each one fails quietly if it is not: the deploy succeeds against empty storage. [Migrating from the hosted deploy](migrate-from-hosted.md) is the checklist.
141