feat: alchemy deployment — the cloudflare-os package with the OperatingSystem resource by sam-goodwin · Pull Request #24 · cloudflare/cloudflare-os

sam-goodwin · 2026-08-05T21:38:16Z

Deploy Cloudflare OS to your own account with alchemy. Everything is alchemy code, owned by the package it deploys — the wrangler.jsonc files, the release-manifest machinery, and everything that parsed them are deleted; each package's src/alchemy.ts is the single source of truth for deploy, local dev, and tests.

// alchemy.run.ts — your company's repo
import * as Alchemy from "alchemy";
import * as Cloudflare from "alchemy/Cloudflare";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";
import { OperatingSystem, OperatingSystemData } from "cloudflare-os";
import Context from "cloudflare-os/context";
import GitHub from "cloudflare-os/github";
import Mcp from "cloudflare-os/mcp";

export default Alchemy.Stack(
  "AcmeOS",
  { providers: Cloudflare.providers(), state: Cloudflare.state() },
  Effect.gen(function* () {
    // User data is a separate, protected resource — retained on destroy.
    const data = yield* OperatingSystemData("Data");

    const github = GitHub({
      clientId: Config.string("GITHUB_CLIENT_ID"),
      clientSecret: Config.redacted("GITHUB_CLIENT_SECRET"),
    });

    const os = yield* OperatingSystem("OS", {
      domain: "os.acme.com",
      admins: ["sam@acme.com"],
      data,
      // sign-in providers are references — a typo can't lock you out
      auth: { providers: [github], disablePasswordAuth: true },
      gatekeepers: [
        github,
        Context({ sharingDomain: "production" }),
        Mcp({ enabled: false }),
      ],
      // presence of `ai` = gateway mode; the gateway, its token, and the
      // stored provider keys are provisioned, not referenced
      ai: { providers: { anthropic: Config.redacted("ANTHROPIC_API_KEY") } },
    });

    return { url: os.url };
  }),
);

alchemy deploy provisions the router (public origin + assets + domain), the workshop-backend, one Worker per enabled gatekeeper, the storage, and the AI gateway. alchemy destroy tears it all down — except the data.

Each package owns its deployment, as code

// packages/gatekeeper-github/src/alchemy.ts — the package's root export
export const workerConfig = {
  name: "gatekeeper-github",
  id: "GitHub",
  entry: "github.ts",
  prebuild: "build:configurator",
  compatibilityFlags: ["allow_irrevocable_stub_storage", "nodejs_als"],
  migrations: [
    { tag: "v0", newSqliteClasses: ["UserAccount", "GitHubGatekeeperImpl"] },
  ],
} as const satisfies WorkerConfig;

export const GitHub = (config: GitHubConfig): Gatekeeper =>
  Gatekeeper({
    name: "github",
    oauth: true, // usable as a sign-in provider
    worker: Gatekeeper.Worker(workerConfig, {
      dir: packageRoot(import.meta),
      env: {
        CLIENT_ID: Gatekeeper.secret(config.clientId),
        CLIENT_SECRET: Gatekeeper.secret(config.clientSecret),
      },
    }),
  });

export default GitHub;

The deploy contract (Gatekeeper, Gatekeeper.Worker, toWranglerConfig) lives in @gadgets/workshop-shared/alchemy; backend/router/frontend/typed-storage export <pkg>/alchemy the same way.
cloudflare-os/<name> re-exports each package's module — same file inside the monorepo and from npm.
run-dev-server.js (local dev, unchanged UX), the integration-test harness, and the pool-workers vitest configs all derive wrangler-shaped config in memory from the exported workerConfig — no config files, one source of truth. scripts/release/ and the golden manifest are deleted.

A custom gatekeeper is just a Worker

const worker = yield* Cloudflare.Worker("Acme", {
  main: "./src/worker.ts",
  compatibility: { date: "2026-02-02" },
  env: { AcmeThing: Cloudflare.DurableObject("AcmeThing") },
});

gatekeepers: [worker]; // GATEKEEPER_ACME derives from the id

Protected user data

const data = yield* OperatingSystemData("Data"); // retained on `alchemy destroy`
const data = yield* OperatingSystemData("Data", {
  blueprints: existingKv,     // adopt existing storage
  removalPolicy: "destroy",   // ephemeral stacks (tests, previews) only
});

Verified live end to end by packages/cloudflare-os/test/OperatingSystem.test.ts (deploy → HTTP probes → destroy), on alchemy's own test harness.

Status

Draft until an alchemy release ships Cloudflare.WorkerEntrypoint (alchemy-run/alchemy#1097, merged); this checkout consumes a local build via pnpm overrides. Intended end state, per review discussion: CI publishes this package as a prebuilt release (worker bundles, frontend variants, checksums), so npm install cloudflare-os needs no monorepo checkout — the per-package alchemy code here is the source of truth that pipeline drives.

🤖 Generated with Claude Code

…ngSystem resource Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-08-05T21:38:28Z

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

I have read the CLA Document and I hereby sign the CLA

_{You can retrigger this bot by commenting recheck in this Pull Request.}_{Posted by the CLA Assistant Lite bot.}

sam-goodwin · 2026-08-05T21:42:05Z

@@ -0,0 +1,69 @@
+{
+  "name": "cloudflare-os",


This name might be wrong. Should itbe @gadgets/alchemy or something else? Up to you guys how you want to distribute

Probably @cloudflare/cloudflare-os-alchemy or the like (I know its a mouthful)

sam-goodwin · 2026-08-05T21:46:52Z

This term gatekeepers doesn't make sense to me. An MCP is a gatekeeper?

Please provide feedback on the desired DX

oiwa-coder · 2026-08-06T22:41:26Z

would love this as well

ndisidore

I would love if CI could produce and publish whatever we call the npm package containing:

Prebuilt Worker module bundles.
Prebuilt frontend variants for password/OAuth and Access.
Static asset manifests and blobs.
The complete deployment manifest.
Full DO migration/lifecycle declarations.
Checksums and source commit metadata.
Supported configuration schema.

It seems like composable primitives would work well with a convenience facade, i.e.

const data = yield* OperatingSystemData("Data", {
  protect: true,
});

const github = yield* BuiltinGatekeeper("GitHub", {
  release: CloudflareOs.release.gatekeepers.github,
  credentials: { clientId, clientSecret },
});

const os = yield* OperatingSystem("OS", {
  release: CloudflareOs.release,
  data,
  auth: OAuthAuth({ providers: [github.auth] }),
  admins: ["admin"],
  gatekeepers: [
    github,
    BuiltinGatekeeper.Context(),
    BuiltinGatekeeper.Scheduler(),
  ],
});

ndisidore · 2026-08-07T19:43:59Z

+    | undefined;
+}
+
+interface RawWranglerConfig {


This looks like a second, incomplete deployment-config parser. It silently ignores several things the existing release manifest handles or explicitly rejects, so the two deployment paths can drift without anyone noticing.

Could this consume the existing release manifest instead? Otherwise, I think it needs to share the same strict parser and fail on anything it doesn’t understand.

If i was doing it my way, i would not have the deployment.jsonc/wrangler.json and just export typescript with the alchemy code in it. I did it this way conservatively because the repository is currently based on wrangler.

ndisidore · 2026-08-07T19:44:27Z

+      main: NodePath.join(dir, raw.main),
+      compatibilityDate: raw.compatibility_date,
+      compatibilityFlags: raw.compatibility_flags ?? [],
+      durableObjects: (raw.migrations ?? []).flatMap(


Possible 🐛
Flattening the migration history down to class names loses tags, ordering, renames, deletes, and transfers. That’s probably enough for a fresh deployment today, but not for upgrades or adoption.

I think we need to preserve the full DO lifecycle and test deploy → write data → upgrade.

ndisidore · 2026-08-07T19:49:00Z

+      );
+    }
+    // Durable Object classes are reached via `ctx.exports`
+    // (`enable_ctx_exports`); the bindings exist to declare the classes and


I don't think any services actually use this compat flag so this may require updates to all the gatekeepers

ndisidore · 2026-08-07T19:50:30Z

+  Effect.gen(function* () {
+    const gatekeeperSet = resolveGatekeepers(props.gatekeepers);
+
+    // ── Storage ────────────────────────────────────────────────────────


Does this mean that they’re owned internally by the convenience component?

I’d rather have a separate protected OperatingSystemData resource, with support for caller-owned existing storage and explicit destructive deletion.

This would own:

Blueprint KV

Avatar KV

Blueprint R2

Any long-lived shared storage

ndisidore · 2026-08-07T19:51:59Z

@@ -0,0 +1,69 @@
+{
+  "name": "cloudflare-os",


Probably @cloudflare/cloudflare-os-alchemy or the like (I know its a mouthful)

ndisidore · 2026-08-07T19:53:00Z

+    "alchemy": ">=2.0.0-beta.67",
+    "effect": ">=4.0.0-beta.100 || >=4.0.0"
+  },
+  "dependencies": {


This package depends on unpublished workspace packages and then runs their builds in the consumer’s environment. Those builds rely on dev dependencies and monorepo-root scripts that won’t be present after a normal npm install.

What are your thoughts on the npm package carrying prebuilt, checksummed Worker and frontend artifacts instead of rebuilding the monorepo in customer projects?

ndisidore · 2026-08-07T19:55:23Z

+    if (props.admins !== undefined) backendEnv.ADMINS = props.admins;
+    const auth = props.auth;
+    if (auth?.gatekeepers?.length) {
+      backendEnv.AUTH_GATEKEEPERS = auth.gatekeepers.join(",");


Can we make this typed against the current gatekeeper list? Or at least validated?

I'm worried Aatypo here can leave the whole installation without a login method: the list is non-empty, password auth gets disabled, but no usable auth gatekeeper appears

feat: alchemy deployment — the cloudflare-os package with the Operati…

9060f99

…ngSystem resource Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sam-goodwin commented Aug 5, 2026

View reviewed changes

ndisidore requested changes Aug 7, 2026

View reviewed changes

sam-goodwin mentioned this pull request Aug 10, 2026

feat: deploy with alchemy — typed alchemy.run.ts replacing deployment.jsonc + deploy.mjs cloudflare/cloudflare-os-starter#1

Draft

sam-goodwin force-pushed the sam/alchemy-deploy branch from d359436 to 9060f99 Compare August 10, 2026 10:48

Uh oh!

Conversation

sam-goodwin commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Each package owns its deployment, as code

A custom gatekeeper is just a Worker

Protected user data

Status

Uh oh!

github-actions Bot commented Aug 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sam-goodwin commented Aug 5, 2026

Uh oh!

oiwa-coder commented Aug 6, 2026

Uh oh!

ndisidore left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sam-goodwin Aug 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ndisidore Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sam-goodwin commented Aug 5, 2026 •

edited

Loading

ndisidore left a comment •

edited

Loading

sam-goodwin Aug 8, 2026 •

edited

Loading

ndisidore Aug 7, 2026 •

edited

Loading