Cloudflare OS: technische tutorial

Cloudflare OS: Review Installeren & instellen Nieuws

Stand september 2026, samengesteld uit onze eigen notities en nieuwsarchief; tekst machinaal opgesteld en redactioneel gecontroleerd. Controleer versies en commando's in de officiële documentatie.

Deze tutorial gaat onder de motorkap van Cloudflare OS: de architectuur (gadgets, gatekeepers, blueprints), het beveiligingsmodel op basis van capabilities, de ontwikkelopzet, en het draaien als publieke dienst voor meerdere gebruikers met inloggen via OAuth en afrekenen via AI Gateway. De basis is de documentatie in de officiële repository cloudflare/cloudflare-os (stand september 2026, v2 early access).

De architectuur als besturingssysteem

Cloudflare OS gebruikt de term "besturingssysteem" niet alleen als marketing. De onderdelen lijken technisch op die van een OS:

Kernel: packages/workshop-backend verbindt gebruikers met programma's en diensten en dwingt sandboxing en toegangsrechten af.
Stuurprogramma's: packages/gatekeeper-* koppelen externe diensten.
Shell: packages/workshop-frontend, de webinterface.
Processen: gadgets, de draaiende apps.
Programma's: blueprints, de code waaruit gadgets ontstaan.
Rechten: gedeelde permissies in plaats van ACL's.
Iets wat een gewoon OS niet heeft: AI-agents, die verantwoording afleggen aan een mens maar eigen, beperkte rechten hebben.

Technisch leunt alles op Cloudflare Workers: elke workspace is een Durable Object, elke gadget draait in een Dynamic Worker Facet, en gatekeepers installeren eigen facets in een workspace om de toegang tot externe diensten te regelen.

Gadgets: elke gebruiker een eigen kopie

Het uitgangspunt is anders dan bij gewone SaaS. Maak je een presentatie, dan roep je geen centrale software aan. Cloudflare OS start een privé-instantie van de presentatie-app, alleen voor jou, in een eigen sandbox. Dat heeft twee gevolgen:

Een bug in de app kan jouw gegevens niet naar een aanvaller lekken, want de sandbox bepaalt alle toegang.
Je kunt de code van jouw kopie gewoon laten aanpassen door de agent, zonder anderen te raken.

De communicatie tussen de client en de server van een gadget verloopt verplicht via Cap'n Web RPC. Daardoor heeft elke gadget automatisch een nette API die een agent direct kan aanroepen. Je kunt de agent dus ook *binnen* een app laten meewerken, zonder dat je daar een aparte MCP-server voor bouwt.

Omdat elke gadget op een Durable Object draait, is samenwerken in real time (zoals in een online kantoorpakket) er standaard in ingebouwd.

De sandbox

Een gadget kan niets met het internet zonder jouw toestemming:

Server: draait in een Dynamic Worker waarvan de internettoegang uitgeschakeld is. Hij kan alleen praten met externe bronnen die jij expliciet aanwijst, via Workers-bindings.
Client: draait in een afgeschermd iframe. Het iframe praat alleen via Cap'n Web over postMessage() met het hoofdvenster, en wordt verder zo veel als browsers toelaten afgesloten, via Content-Security-Policy en de iframe-sandbox-instellingen.

Gatekeepers en capabilities

Een gatekeeper is een soort uitgebreide MCP-server, als losse Worker per externe dienst. Hij:

biedt een schone Cap'n Web-API voor de dienst;
regelt de autorisatie, bijvoorbeeld via OAuth;
beperkt de toegang tot precies de bron die jij bedoelde;
logt elke actie van een gadget of agent, zodat je die kunt nalezen;
legt elke actie met gevolgen aan jou voor.

Toegang op basis van capabilities. Een agent of gadget heeft standaard toegang tot niets, ook als jij de dienst wel gekoppeld hebt. Je moet een bron expliciet voorstellen, bijvoorbeeld door een link naar een GitHub-repository te plakken of een bron te kiezen via "add resource". Een agent kan zelf om een introductie vragen, die jij toekent of weigert. Dat is het omgekeerde van de meeste agent-omgevingen, waar MCP-servers vooraf breed beschikbaar zijn in elke chat.

Asynchrone goedkeuring. Wil een agent iets doen dat goedkeuring vereist, dan simuleert de gatekeeper de uitkomst en werkt de agent door. De echte acties staan in een wachtrij die jij later in één keer of per actie goedkeurt of afwijst. Zo blijft een agent niet de hele nacht op de eerste vraag hangen, en hoef je ook geen "alles automatisch goedkeuren" aan te zetten.

Blueprints: code delen in plaats van data

Een blueprint is de code van een gadget, zonder chatgeschiedenis, opslag of inloggegevens. Wie een gadget uit een blueprint maakt, krijgt een eigen kopie met eigen bindings, eigen opslag en eigen gesprekken.

Eén gadget kan meerdere blueprints hebben, ook op verschillende codeversies (bijvoorbeeld "stabiel" en "nieuwste").
Je deelt een blueprint via een link. Iedereen met de link ziet de metadata; een gadget ervan maken vereist inloggen.
De eigenaar kan een blueprint bijwerken, waarbij oude versies bewaard blijven.
Blueprints kun je exporteren als .gadget-bestand en in een andere installatie importeren.

Ontwikkelen aan Cloudflare OS zelf

Voor het ontwikkelen draai je frontend en backend los, in twee terminals:

pnpm dev-server
pnpm dev-client

Open daarna http://localhost:3000. Instellingen voor lokaal ontwikkelen zet je in een .dev.vars-bestand in de root van de repository, met één KEY=VALUE per regel. Dat bestand staat in .gitignore en wordt door pnpm run dev-server automatisch geladen.

Het project neemt op dit moment geen grote externe bijdragen aan: kleine, eenvoudig te controleren fixes wel, grotere ideeën via GitHub Discussions.

Als publieke dienst voor meerdere gebruikers

Standaard gebruikt de Workshop gebruikersnaam en wachtwoord (of Cloudflare Access) en krijgt elke gebruiker onbeperkt AI-gebruik: ideaal voor zelfhosting in een team. Je kunt het ook als openbare dienst inrichten. Die onderdelen zet je los van elkaar aan:

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=...

Inloggen. Elke gatekeeper die inloggen ondersteunt (Google, GitHub, Cloudflare), gebruikt één OAuth-app voor zowel het inloggen als het koppelen van de dienst. De account-sleutel is altijd het geverifieerde e-mailadres: wie met Google en GitHub op hetzelfde geverifieerde adres inlogt, komt in hetzelfde account. Bij het inloggen worden alleen de minimale rechten gevraagd om dat adres te lezen, en die tijdelijke toegang vervalt meteen daarna. Ruimere rechten (repositories, Gmail en Docs, billing) worden pas gevraagd als de gebruiker de dienst expliciet koppelt.

Afrekenen. Met ENABLE_CLOUDFLARE_LIMITS krijgt elke gebruiker een gratis dagtegoed (standaard 100 LLM-aanroepen per UTC-dag). Een gebruiker die zijn eigen Cloudflare-account koppelt en minstens $2 aan AI Gateway-credits heeft, wordt altijd via dat eigen account afgerekend. Is het gratis tegoed op en zijn er geen of te weinig credits, dan wordt het verzoek geblokkeerd met een melding om te koppelen of bij te storten. Het platform beheert zelf nooit geld: opwaarderen gebeurt in het Cloudflare-dashboard.

Draai je het gratis tegoed via Workers AI, dan gebruikt dat standaard dezelfde gateway. Met CF_AI_GATEWAY_WAI_DIRECT=true gaat het rechtstreeks naar het REST-endpoint van Workers AI, en met CF_AI_GATEWAY_WAI kies je een andere gateway.

Waar je op moet letten

Early access. Versie 2 is een volledige herschrijving en nog volop in ontwikkeling. Verwacht veranderingen die je bestaande opzet raken, en maak back-ups van je gegevens.
Lokaal is geen productie. pnpm run-local via wrangler is om te proberen. Voor productie gebruik je het uitrolproces of de starter-repository; zelfhosten op kale workerd is nog niet gedocumenteerd.
Het OAuth-werk. Voor elke gatekeeper maak je zelf een OAuth-app aan bij de dienst, met de juiste redirect-URI's. Plan daar tijd voor in.
Geheimen. .dev.vars hoort nooit in git; in productie zet je geheimen als Worker-secrets.

Bron: github.com/cloudflare/cloudflare-os en de docs/-map in die repository.