How the Cloudflare OS Blueprint System Enables Template Sharing

The Cloudflare OS Blueprint system converts a gadget's source code into a versioned, shareable template stored across KV and R2, allowing anyone with a URL to copy and instantiate it as a new gadget without exposing sensitive data.

The Blueprint system in Cloudflare OS serves as the foundation for template sharing in the Cloudflare Workers ecosystem. It transforms interactive gadgets into reusable, portable templates that preserve code structure and binding configurations while excluding user-specific data.

How Blueprint Creation Works

When a user creates a blueprint from the gadget editor, the backend orchestrates a multi-layer storage process.

Generating the Blueprint Archive

The core logic resides in packages/workshop-backend/src/blueprint-archive.ts. The system generates a random 128-bit hex ID using randomBlueprintId(), collects the gadget's binding annotations, and snapshots the current Yjs document (the collaborative editing state) into a compressed archive.

// packages/workshop-backend/src/blueprint-archive.ts
const id = randomBlueprintId();  // 128-bit hex identifier
await env.BLUEPRINTS.put(id, JSON.stringify(kvRecord));
await env.BLUEPRINT_CONTENT.put(`${id}/${version}`, snapshotStream);

Dual Storage Architecture

The blueprint persists across two distinct storage systems:

• BLUEPRINTS KV namespace — stores BlueprintKvRecord metadata including title, description, required bindings, and output specifications
• BLUEPRINT_CONTENT R2 bucket — stores the compressed code snapshot

This separation enables fast metadata lookups while keeping larger binary payloads in object storage.

Public Access Without Authentication

The blueprint metadata is intentionally publicly readable. Anyone can fetch blueprint details via the PublicApi.getBlueprint() endpoint, typically accessed through the frontend route /blueprint/<id>.

// Frontend retrieval of public blueprint metadata
const res = await fetch(`/api/blueprint/${blueprintId}`);
const meta = await res.json();  // No authentication required

The readBlueprintKvRecord function in blueprint-archive.ts handles the KV lookup, returning metadata that the UI renders into a landing page with instantiation controls.

Instantiating Gadgets From Blueprints

Authenticated users—or AI agents acting on their behalf—convert blueprints into runnable gadgets through the AuthenticatedApi.newGadgetFromBlueprint() flow.

The Instantiation Pipeline

The process involves four distinct operations as documented in docs/blueprints.md:

1. Metadata retrieval — fetches the BlueprintKvRecord from KV
2. Snapshot retrieval — streams the code archive from R2 via readBlueprintContent
3. Durable Object creation — provisions a fresh Overseer Durable Object for the new gadget
4. Binding initialization — creates required infrastructure (gatekeepers, AI models, agent spawners) based on the blueprint's BlueprintBinding list

// Authenticated instantiation with binding configuration
await api.newGadgetFromBlueprint({
  blueprintId,
  bindings: {
    myDrive: { accountId: "...", resource: "gdrive://my-folder" },
    myModel: { modelId: "gpt-4o" },
  },
});

The new gadget initializes with the exact file structure captured in the original snapshot, ensuring behavioral fidelity across instantiations.

Versioning and Race Condition Safety

Blueprints implement immutable versioning to prevent corruption during concurrent access. Each update creates a new version in R2 while retaining older versions. This design ensures that if two users instantiate the same blueprint simultaneously, each receives a complete, consistent snapshot without partial-write corruption.

Discovery and Curation

Administrators can designate blueprints as featured by adding them to a BlueprintPublicInfo list in KV. These featured blueprints surface on:

• The Explore page
• The homepage "Blueprints" tab

This curation mechanism transforms individual templates into a discoverable marketplace.

Security: What Blueprints Exclude

Critical to the sharing model is what blueprints deliberately omit:

Excluded Data	Rationale
User credentials	Prevents credential leakage across trust boundaries
Chat history	Protects conversation privacy
SQLite data	Excludes runtime state and proprietary datasets

Blueprints contain only code and binding shape—the structural schema of required integrations without instantiated values. This limitation enables safe cross-deployment portability: a .gadget binary can be exported from one Cloudflare OS deployment and imported into another without data contamination risks.

Key Implementation Files

Understanding the Blueprint system requires familiarity with these source locations:

• packages/workshop-backend/src/blueprint-archive.ts — Archive encoding/decoding, KV/R2 read/write utilities, ID generation
• docs/blueprints.md — High-level lifecycle documentation and storage layout specifications
• packages/workshop-frontend/src/routes/blueprint.$id.tsx — UI route handling public blueprint display and instantiation flows
• packages/workshop-backend/src/public-api.ts — Unauthenticated getBlueprint endpoint implementation
• packages/workshop-backend/src/authenticated-api.ts — newGadgetFromBlueprint authenticated instantiation logic

Summary

The Cloudflare OS Blueprint system enables template sharing through:

• Dual-layer storage separating metadata (KV) from code snapshots (R2)
• Public metadata access allowing anyone to discover and preview templates
• Authenticated instantiation with fresh Durable Objects and binding configuration
• Immutable versioning preventing race conditions during concurrent use
• Data-minimal archives excluding credentials, history, and state for safe cross-deployment sharing

Frequently Asked Questions

What data does a Cloudflare OS blueprint actually contain?

A blueprint contains the gadget's source code files, Yjs document snapshot, binding annotations (required integration types), and metadata (title, description, output specifications). It explicitly excludes user credentials, chat history, and SQLite database contents—only the shape of bindings is preserved, not their instantiated values.

Can I use a blueprint created in one Cloudflare OS deployment in another deployment?

Yes. Because blueprints exclude deployment-specific data and credentials, the .gadget binary format supports cross-deployment portability. Export the blueprint archive and import it into any other Cloudflare OS Workshop instance without security risks.

How does the Blueprint system prevent version conflicts when multiple users instantiate simultaneously?

Each blueprint update creates a new immutable version in R2. During instantiation, the system reads a specific versioned snapshot rather than a mutable reference. This ensures concurrent instantiations receive complete, consistent code archives without interference from concurrent writes.

What authentication is required to use a Cloudflare OS blueprint?

No authentication is required to view blueprint metadata—landing pages are public. However, instantiating a gadget from a blueprint requires an authenticated session or AI agent delegation, as this operation provisions infrastructure resources and creates new Durable Objects in your account.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}