Cloudflare OS: technical tutorial

By Ivo Donker · October 28, 2026 — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash)

Cloudflare OS: Review Install & set up News

As of September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation.

This tutorial goes under the bonnet of Cloudflare OS: the architecture (gadgets, gatekeepers, blueprints), the capabilities-based security model, the development setup, and running it as a public multi-user service with sign-in via OAuth and billing via AI Gateway. It is based on the documentation in the official repository cloudflare/cloudflare-os (as of September 2026, v2 early access).

The architecture as an operating system

Cloudflare OS does not use the term "operating system" merely as marketing. Technically, the components resemble those of an OS:

Kernel: packages/workshop-backend connects users with programs and services and enforces sandboxing and access rights.
Drivers: packages/gatekeeper-* connect external services.
Shell: packages/workshop-frontend, the web interface.
Processes: gadgets, the running apps.
Programs: blueprints, the code from which gadgets are created.
Permissions: shared permissions instead of ACLs.
Something an ordinary OS does not have: AI agents, which are accountable to a human but have their own limited permissions.

Technically, everything relies on Cloudflare Workers: every workspace is a Durable Object, every gadget runs in a Dynamic Worker Facet, and gatekeepers install their own facets in a workspace to manage access to external services.

Gadgets: every user gets their own copy

The starting point is different from ordinary SaaS. When you create a presentation, you do not call on central software. Cloudflare OS starts a private instance of the presentation app, just for you, in its own sandbox. This has two consequences:

A bug in the app cannot leak your data to an attacker, because the sandbox controls all access.
You can simply have the agent modify the code of your copy without affecting anyone else.

Communication between a gadget's client and server must go through Cap'n Web RPC. As a result, every gadget automatically has a clean API that an agent can call directly. So you can also have the agent collaborate *inside* an app, without building a separate MCP server for it.

Because every gadget runs on a Durable Object, real-time collaboration (as in an online office suite) is built in by default.

The sandbox

A gadget cannot do anything with the internet without your permission:

Server: runs in a Dynamic Worker whose internet access is disabled. It can only talk to external resources that you explicitly specify, via Workers bindings.
Client: runs in an isolated iframe. The iframe communicates with the main window only via Cap'n Web over postMessage(), and is otherwise locked down as far as browsers allow, via Content-Security-Policy and the iframe sandbox settings.

Gatekeepers and capabilities

A gatekeeper is a kind of extended MCP server, as a separate Worker per external service. It:

provides a clean Cap'n Web API for the service;
handles authorisation, for example via OAuth;
limits access to exactly the resource you intended;
logs every action of a gadget or agent so that you can review it;
submits every action with consequences to you.

Capability-based access. By default, an agent or gadget has access to nothing, even if you have connected the service. You must explicitly introduce a resource, for example by pasting a link to a GitHub repository or choosing a resource via "add resource". An agent can itself ask for an introduction, which you grant or deny. This is the opposite of most agent environments, where MCP servers are broadly available in every chat in advance.

Asynchronous approval. If an agent wants to do something that requires approval, the gatekeeper simulates the outcome and the agent continues. The real actions are placed in a queue that you later approve or reject all at once or per action. This way, an agent does not get stuck on the first question all night, and you do not have to turn on "approve everything automatically".

Blueprints: sharing code instead of data

A blueprint is the code of a gadget, without chat history, storage or login credentials. Anyone who creates a gadget from a blueprint gets their own copy with their own bindings, their own storage and their own conversations.

A single gadget can have multiple blueprints, including on different code versions (for example "stable" and "latest").
You share a blueprint via a link. Everyone with the link sees the metadata; making a gadget from it requires logging in.
The owner can update a blueprint, with old versions preserved.
You can export blueprints as a .gadget file and import them into another installation.

Developing Cloudflare OS itself

To develop, you run frontend and backend separately, in two terminals:

pnpm dev-server
pnpm dev-client

Then open http://localhost:3000. You put settings for local development in a .dev.vars file in the root of the repository, with one KEY=VALUE per line. That file is in .gitignore and is loaded automatically by pnpm run dev-server.

The project is not currently taking large external contributions: small, easy-to-review fixes yes, larger ideas via GitHub Discussions.

As a public service for multiple users

By default, the Workshop uses username and password (or Cloudflare Access) and every user gets unlimited AI usage: ideal for self-hosting in a team. You can also set it up as a public service. You enable those parts separately:

AUTH_GATEKEEPERS=cloudflare,google,github   # met deze diensten mag je inloggen
DISABLE_PASSWORD_AUTH=true                  # alleen OAuth-login (werkt alleen als de lijst hierboven niet leeg is)
ENABLE_CLOUDFLARE_LIMITS=true               # gratis dagtegoed + betalen via eigen Cloudflare-credits
PUBLIC_BASE_URL=https://jouw-domein
CF_AI_GATEWAY=jouw-gateway                  # AI Gateway voor het gratis tegoed
CF_AI_GATEWAY_PROVIDERS=anthropic,openai,google
CF_AI_GATEWAY_ACCOUNT_ID=...
CF_AI_GATEWAY_API_TOKEN=...

Logging in. Every gatekeeper that supports logging in (Google, GitHub, Cloudflare) uses one OAuth app for both logging in and linking the service. The account key is always the verified email address: anyone who logs in with Google and GitHub using the same verified address ends up in the same account. When logging in, only the minimum permissions needed to read that address are requested, and that temporary access expires immediately afterwards. Broader permissions (repositories, Gmail and Docs, billing) are only requested when the user explicitly links the service.

Billing. With ENABLE_CLOUDFLARE_LIMITS, every user gets a free daily allowance (100 LLM calls per UTC day by default). A user who links their own Cloudflare account and has at least $2 in AI Gateway credits is always billed through that own account. If the free allowance is used up and there are no credits or too few, the request is blocked with a message to link an account or top up. The platform itself never handles money: topping up happens in the Cloudflare dashboard.

If you run the free allowance via Workers AI, that uses the same gateway by default. With CF_AI_GATEWAY_WAI_DIRECT=true it goes straight to the REST endpoint of Workers AI, and with CF_AI_GATEWAY_WAI you choose a different gateway.

What to watch out for

Early access. Version 2 is a complete rewrite and still very much in development. Expect changes that affect your existing setup, and make backups of your data.
Local is not production. pnpm run-local via wrangler is for trying things out. For production you use the deployment process or the starter repository; self-hosting on bare workerd is not yet documented.
The OAuth work. For each gatekeeper you create an OAuth app yourself with the service, with the correct redirect URIs. Allow time for that.
Secrets. .dev.vars should never be in git; in production you set secrets as Worker secrets.

Source: github.com/cloudflare/cloudflare-os and the docs/ folder in that repository.