Blueprints: Shareable App Templates for Cloudflare OS

A Blueprint is a shareable snapshot of a Gadget’s source code, packaged as a reusable template. When you publish a Blueprint, you are not sharing your Gadget — you are sharing the code for a Gadget, so that anyone with the link can create their own independent copy. Each new instance gets its own private SQLite storage, its own chat history, and its own connections to external services. Nothing from the original Gadget is shared. This is a meaningful departure from how cloud software has traditionally worked. Rather than hosting one app that all users connect to, Blueprints let you distribute the code for an app so that every user runs their own instance — more like distributing a mobile app than running a web service.

What a Blueprint captures — and what it does not

A Blueprint captures:

Source code — a point-in-time snapshot of the Gadget’s Yjs document, with all edit history stripped. Only the final file contents are included, encoded as a minimal set of insert operations.
Binding requirements — the name, type, and configuration shape of each connection the Gadget needs (a GitHub repository, an AI model, an agent spawner). Credentials are never included — only the shape of what is needed.
Metadata — title, description, optional screenshot, author info, version number, and timestamps.

A Blueprint does not capture:

The Gadget’s SQLite storage contents.
AI chat history or Yjs edit history.
Live credentials or OAuth tokens.
The specific resource connected to a binding — only the type and URL pattern of what is expected.

A collaborator who creates a Gadget from a Blueprint starts with a clean slate. The code is theirs to modify, and their data is theirs alone.

Blueprint IDs

Every Blueprint has a 128-bit random hex ID generated server-side. This ID is used as the key in Workers KV, the R2 path prefix for stored code, and the path segment in share links.

Bundled Blueprints — Blueprints shipped with a deployment as data files — use stable, readable IDs instead of random hex. For example, the built-in document format uses the ID format.document and the slides format uses format.slides. These IDs must never be changed after deploy: renaming one orphans the old entry in KV rather than migrating it.

Blueprints are shared by URL:

https://<host>/blueprint/<blueprint-id>

The Blueprint Landing Page at this URL is publicly accessible without authentication — knowing the ID is considered sufficient authorization to view the Blueprint’s metadata, just as knowing a share link URL is sufficient to view what it describes. Fetching metadata calls PublicApi.getBlueprint(), which reads from Workers KV. Creating a Gadget from a Blueprint requires authentication. Only after signing in does the user enter configure mode to assign bindings.

Binding types in Blueprints

Blueprints support three binding types, matching the three kinds of connections a Gadget can hold:

Gatekeeper
AI Model
Agent Spawner

An external resource connection (e.g., a Google Drive document, a GitHub repository, a REST API). The Blueprint records the Gatekeeper adapter name and a URL pattern describing what kind of resource is expected. When instantiating, the user picks a connected account and selects a matching resource.

{
  "type": "gatekeeper",
  "gatekeeperName": "google",
  "typeUrlPattern": "https://docs.google.com/document/:id"
}

A language model binding. The Blueprint may suggest a specific provider and model name, but the user picks from their own configured models when instantiating.

{
  "type": "aiModel",
  "suggestedModel": { "provider": "anthropic", "modelName": "claude-sonnet-5" }
}

An agent spawner configuration. The Blueprint records the spawner’s symbolic environment bindings and an optional suggested model. The user only needs to choose which model the spawner should use (or none).

{
  "type": "agentSpawner",
  "suggestedModel": { "provider": "anthropic", "modelName": "claude-sonnet-5" },
  "env": { "MAILBOX": { "type": "binding", "name": "mailboxGatekeeper" } }
}

Before publishing, Blueprint authors can add annotations to each binding: a friendly display name, a description shown to the installer, and an optional suggested resource URL. Annotations are stored on the GatekeeperRecord as blueprintAnnotation and are surfaced on the Blueprint Landing Page.

Storage architecture

Blueprint data flows one-way through three storage layers:

Gadget DO  ──►  User DO  ──►  Workers KV
(authoritative)  (listing)    (public reads)
                    │
                    └──► R2 (code content)

Layer	What is stored
Gadget Durable Object (`blueprints` collection)	Authoritative record including full metadata, code version reference, and a `dirty` propagation flag
User Durable Object (`blueprints` collection)	Denormalized copy for listing and audit; survives source Gadget deletion
Workers KV (`BLUEPRINTS` namespace)	Public-facing record keyed by Blueprint hex ID; what `PublicApi.getBlueprint()` reads
R2 (`BLUEPRINT_CONTENT` bucket)	Code content at key `<blueprintId>/<version>`; old versions are retained until deletion

The dirty flag is set before propagation begins and cleared only after all writes succeed. If propagation fails mid-way, the UI surfaces a Retry button.

Export and import format

Blueprints can be downloaded as .gadget archive files and imported into any other Cloudflare OS instance. The format is a compact binary container:

Field	Size	Content
Magic number	8 bytes	`0xec2e2d3a2300e317`
Format version	4 bytes	`1`
Metadata length	4 bytes	Length of following JSON
Content length	8 bytes	Length of following raw bytes
Metadata	variable	JSON-encoded `BlueprintMetadata`
Content	variable	Gzip-compressed Yjs V2 snapshot (same bytes as R2)

Metadata is capped at 64 KiB; the code snapshot is capped at 32 MiB. The archive does not include ownerId, gadgetId, or screenshot bytes. Import/export streams the content bytes directly to and from R2 using pipeTo() rather than buffering in memory.

Output formats and bundled Blueprints

A format is a Blueprint the deployment has promoted via admin curation, causing it to appear in the “New …” menu (e.g., New Doc, New Slides) and in the list the agent is told to prefer. Promotion is a separate decision from what the Blueprint declares about itself. A Blueprint may declare a BlueprintOutput field describing what it produces:

{
  id: "document",     // stable grouping slug
  noun: "Doc",
  plural: "Docs",
  icon: "fileText"    // one of the OUTPUT_ICONS closed set
}

Gadgets instantiated from the Blueprint inherit this output field, which drives how they appear on the Outputs page and in workspace tabs.

Instantiating a Blueprint

Open the Blueprint link

Navigate to https://<host>/blueprint/<id>. The page fetches metadata from Workers KV via PublicApi.getBlueprint() (no authentication required) and displays the title, description, optional screenshot, author, and required bindings summary.

If you are not logged in, sign in to proceed. Unauthenticated users see a “Log in to create a Gadget” prompt.

Configure bindings

Enter configure mode. For each required binding, assign a connected account and resource (for Gatekeeper bindings), pick from your configured models (for AI model bindings), or choose a model for the spawner (for agent spawner bindings).

Create the Gadget

Click Create Gadget. This calls AuthenticatedApi.newGadgetFromBlueprint(), which reads the Blueprint from KV, downloads the code snapshot from R2, creates a new Overseer Durable Object, initializes it with the Blueprint’s code, and creates Gatekeepers from your binding assignments. The UI redirects to your new Gadget.

The agent can also instantiate Blueprints programmatically. It uses listBlueprints to find available templates and passes a blueprintId to createGadget. Bindings are not auto-assigned on this path — the agent wires them up via setGadgetBinding or asks the user to add them from the Connections panel.

The Explore page

The /explore page surfaces featured Blueprints curated by deployment admins. Admins can mark any published Blueprint as featured via AdminApi.setBlueprintFeatured(). Featured state is stored in the owning User DO and mirrored to the AdminSettings Durable Object, which writes a KV snapshot for fast reads. Users can also build a personal library of Blueprints: save any Blueprint by reference from the home page Blueprints tab, or upload a .gadget archive to import it as a local copy. Pinning a Blueprint keeps it at the top of the tab for quick reuse.

Get Started

Core Concepts

Deployment

Gatekeepers

Guides

Blueprints: Shareable App Templates for Cloudflare OS

What a Blueprint captures — and what it does not

Blueprint IDs

Binding types in Blueprints

Storage architecture

Export and import format

Output formats and bundled Blueprints

Instantiating a Blueprint

The Explore page

Build docs developers (and LLMs) love

Get Started

Core Concepts

Deployment

Gatekeepers

Guides

Documentation Index

​What a Blueprint captures — and what it does not

​Blueprint IDs

​Sharing via link

​Binding types in Blueprints

​Storage architecture

​Export and import format

​Output formats and bundled Blueprints

​Instantiating a Blueprint

​The Explore page

Build docs developers (and LLMs) love

What a Blueprint captures — and what it does not

Blueprint IDs

Sharing via link

Binding types in Blueprints

Storage architecture

Export and import format

Output formats and bundled Blueprints

Instantiating a Blueprint

The Explore page