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

> Discover the role of the workshop-backend in Cloudflare OS. This core package handles user authentication, policy enforcement, and AI gadget management for the operating system.

- Repository: [Cloudflare/cloudflare-os](https://github.com/cloudflare/cloudflare-os)
- Tags: architecture
- Published: 2026-09-04

---

**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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/user.ts) | Implements user management utilities, including `getGatekeeperClassFor()` for gatekeeper resolution. |
| [`packages/workshop-backend/src/overseer.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/overseer.ts) | Orchestrates workspace creation, gadget instantiation, and runtime binding of capabilities. |
| [`packages/workshop-backend/src/api.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/admin-config.ts).
- Gatekeeper discovery and validation occur through `getGatekeeperClassFor()` in [`packages/workshop-backend/src/user.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/packages/workshop-backend/src/user.ts).
- Gadget lifecycle management happens in [`packages/workshop-backend/src/overseer.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/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`](https://github.com/cloudflare/cloudflare-os/blob/main/overseer.ts) instantiates each gadget as a Dynamic Worker facet with isolated bindings, while [`gateway.ts`](https://github.com/cloudflare/cloudflare-os/blob/main/gateway.ts) routes HTTP requests to the appropriate RPC handlers. All communication requires valid capability tokens issued by the user management system.