What Is the Role of the Workshop-Backend in Cloudflare OS?

The workshop-backend package serves as the kernel of Cloudflare OS, implementing the core server-side logic that authenticates users, enforces administrative policies, orchestrates gatekeeper drivers, and manages the lifecycle of AI-generated gadgets.

The workshop-backend is the central security-critical service within the cloudflare/cloudflare-os repository. It functions as the operating system kernel for an AI-centric, capability-based SaaS platform, connecting users, agents, and external services through a unified RPC layer.

Core Responsibilities of the Workshop-Backend

The backend operates across six critical architectural layers, handling everything from session state to gadget execution.

User and Session Management

The workshop-backend authenticates users and provisions per-user Durable Objects that persist workspace state across sessions. It issues short-lived capability tokens that enforce least-privilege access patterns. When a user initiates a session, the backend validates credentials and instantiates the corresponding user object in packages/workshop-backend/src/user.ts.

Admin Configuration and Policy Enforcement

The backend exposes an AdminApi capability through AuthenticatedApi.getAdminApi() that allows deployment administrators to read and modify the immutable AdminConfig object. According to the source code in packages/workshop-backend/src/admin-config.ts, admin changes are persisted in a reserved KV key and mirrored to a Durable Object for consistency. This ensures that security policies and system-wide settings remain tamper-proof and auditABLE.

Gatekeeper Integration and Capability Boundaries

Gatekeeper workers act as device drivers for external services. The workshop-backend discovers installed gatekeepers via binding names prefixed with GATEKEEPER_* and validates their status before minting capabilities. The getGatekeeperClassFor() function in packages/workshop-backend/src/user.ts enforces that a gatekeeper is enabled before injecting its binding into a workspace's RPC environment. This mechanism prevents unauthorized access to third-party APIs.

RPC API Definition and Validation

All client-to-server communication flows through the Cap'n Web RPC layer defined in packages/workshop-shared/src/api.ts. The backend validates inbound calls using the @validateRpc() decorator, ensuring type safety and capability verification. The frontend connects to this layer via persistent WebSocket connections managed in packages/workshop-backend/src/api.ts.

Blueprint and Gadget Lifecycle Management

The backend transforms declarative blueprints into executable gadgets. The packages/workshop-backend/src/format-blueprints.ts file generates TypeScript representations from JSON blueprint definitions. When a user requests a new gadget—such as a slide deck or whiteboard—the packages/workshop-backend/src/overseer.ts orchestrates the instantiation of a Dynamic Worker facet, effectively launching the gadget as an isolated process.

Observability and Structured Logging

Every administrative action, gatekeeper provisioning event, and workspace mutation emits structured logs via @gadgets/backend-utils/logger. This logging infrastructure, integrated throughout the backend, creates immutable audit trails for security analysis and debugging.

Key Implementation Files

Understanding the workshop-backend requires familiarity with these specific source files:

File	Purpose
packages/workshop-backend/src/admin-config.ts	Defines the immutable AdminConfig object and the API for administrative configuration management.
packages/workshop-backend/src/user.ts	Implements user management utilities, including getGatekeeperClassFor() for gatekeeper resolution.
packages/workshop-backend/src/overseer.ts	Orchestrates workspace creation, gadget instantiation, and runtime binding of capabilities.
packages/workshop-backend/src/api.ts	Implements the server-side Cap'n Web RPC handlers exposed to the frontend.
packages/workshop-backend/src/gateway.ts	Handles HTTP endpoints at /api/*, forwarding requests to the RPC layer and exposing administrative actions.
packages/workshop-backend/src/format-blueprints.ts	Generates TypeScript code from declarative Blueprint JSON files used for gadget instantiation.

Working with the Workshop-Backend API

The following examples demonstrate how to interact with the workshop-backend's core capabilities from within the Cloudflare OS environment.

Reading Administrative Configuration

This example retrieves the current AdminConfig using the authenticated admin capability:

import { AuthenticatedApi } from "@gadgets/workshop-shared/api";

async function readAdminConfig(env) {
  const api = await AuthenticatedApi.getAdminApi(env);
  if (!api) throw new Error("Not an admin");
  
  // The AdminConfig is stored in a reserved KV key
  return await api.readConfig();
}

Instantiating Gadgets from Blueprints

To create a new workspace gadget from a blueprint definition:

import { WorkshopApi } from "@gadgets/workshop-shared/api";

async function createGadgetFromBlueprint(env, blueprintId) {
  const api = await WorkshopApi.get(env);
  
  // `instantiateBlueprint` validates the blueprint and spins up a Dynamic Worker facet
  const gadget = await api.instantiateBlueprint({ blueprintId });
  
  // Returns an RpcStub; wrap before storing in React state
  return gadget;
}

Resolving Gatekeeper Bindings

This pattern demonstrates how to obtain a gatekeeper session for external service integration:

import { getGatekeeperClassFor } from "packages/workshop-backend/src/user";

async function getGitHubGatekeeper(env, userId) {
  const Gatekeeper = await getGatekeeperClassFor(env, "github");
  
  // Returns a class that creates an account-scoped Durable Object
  const account = await Gatekeeper.createAccount(env, userId);
  return account.getSession(); // RPC session the gadget can use
}

Important: All RPC stubs must be wrapped before storage in React state and disposed using stub[Symbol.dispose]() when no longer needed to prevent memory leaks.

Summary

• The workshop-backend functions as the cloudflare/cloudflare-os kernel, managing authentication, authorization, and execution environments.
• It enforces security through capability-based access control, validating all requests via AuthenticatedApi and @validateRpc().
• Administrative configuration persists in KV storage with Durable Object mirroring through packages/workshop-backend/src/admin-config.ts.
• Gatekeeper discovery and validation occur through getGatekeeperClassFor() in packages/workshop-backend/src/user.ts.
• Gadget lifecycle management happens in packages/workshop-backend/src/overseer.ts, which orchestrates Dynamic Worker facets for isolated execution.

Frequently Asked Questions

What is the workshop-backend in Cloudflare OS?

The workshop-backend is the kernel-level package in cloudflare/cloudflare-os that implements core OS services including user management, admin configuration, session handling, and gatekeeper orchestration. It mediates all interactions between the frontend, AI agents, and external services through a secure RPC layer.

How does the workshop-backend handle admin configuration?

The backend exposes an AdminApi capability via AuthenticatedApi.getAdminApi() that reads and patches the immutable AdminConfig object. Changes are stored in a reserved KV namespace and synchronized to a Durable Object, ensuring atomic updates and audit trails for all administrative actions.

What is the relationship between workshop-backend and gatekeepers?

The workshop-backend treats gatekeepers as device drivers for external services. It discovers gatekeepers through environment bindings, validates their enabled status using getGatekeeperClassFor(), and injects appropriate capabilities into workspace RPC environments before allowing gadget access to third-party APIs.

How do gadgets communicate with the workshop-backend?

Gadgets communicate through Cap'n Web RPC over persistent WebSockets. The backend's overseer.ts instantiates each gadget as a Dynamic Worker facet with isolated bindings, while gateway.ts routes HTTP requests to the appropriate RPC handlers. All communication requires valid capability tokens issued by the user management system.

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