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

Make alchemy the recommended way to deploy Cloudflare OS: a new public package, cloudflare-os (packages/alchemy), whose OperatingSystem resource provisions the whole system.

// alchemy.run.ts
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 } from "cloudflare-os";
import { GitHub } from "cloudflare-os/gatekeepers";

export default Alchemy.Stack(
  "AcmeOS",
  { providers: Cloudflare.providers(), state: Cloudflare.state() },
  Effect.gen(function* () {
    const os = yield* OperatingSystem("OS", {
      domain: "os.acme.com",
      admins: ["sam@acme.com"],
      auth: { gatekeepers: ["github"], disablePasswordAuth: true },
      gatekeepers: [
        GitHub({
          clientId: Config.string("GITHUB_CLIENT_ID"),
          clientSecret: Config.redacted("GITHUB_CLIENT_SECRET"),
        }),
      ],
      ai: { providers: { anthropic: Config.redacted("ANTHROPIC_API_KEY") } },
    });

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

pnpm --dir packages/alchemy run deploy    # up
pnpm --dir packages/alchemy run destroy   # gone

Every prop is optional — OperatingSystem("OS") alone deploys a working OS at the router's workers.dev URL. Gatekeepers are configured with plugin functions; context, scheduler, and mcp deploy by default:

gatekeepers: [
  GitHub({ clientId, clientSecret }),        // credentialed: configuring = installing
  Context({ sharingDomain: "production" }),  // reconfigure a default
  Mcp({ enabled: false }),                   // opt out of a default
  HomeAssistant(),                           // opt in to a non-default
]

A custom gatekeeper is any Worker (or any package following the standard capnweb layout):

// inside the Stack's Effect.gen
const acme = yield* Cloudflare.Worker("AcmeWorker", {
  main: "./src/worker.ts",   // exports GatekeeperVendor + capability classes
  env: {
    CACHE: Cloudflare.KV.Namespace("Cache"),
    ACME_API_TOKEN: Config.redacted("ACME_API_TOKEN"),
    AcmeThing: Cloudflare.DurableObject("AcmeThing"),
  },
});

gatekeepers: [Gatekeeper({ name: "acme", worker: acme })]
// or: Gatekeeper({ name: "acme", package: "my-acme-gatekeeper" })

The ai prop provisions the AI Gateway, its access token, and Secrets-Store-backed provider keys — nothing to create in the dashboard:

ai: {
  gateway: { cacheTtl: 60 },
  providers: {
    anthropic: Config.redacted("ANTHROPIC_API_KEY"),
    openai: Config.redacted("OPENAI_API_KEY"),
  },
  workersAi: true,
  limits: { dailyLlmCallLimit: 200 },
}

Live e2e coverage deploys a full OS, verifies it over HTTP, and destroys it:

pnpm --dir packages/alchemy run test:e2e

Draft until an alchemy release including Cloudflare.WorkerEntrypoint (alchemy#1097) ships to npm — until then pnpm-workspace.yaml carries local-tarball overrides that only resolve in the authoring checkout.

🤖 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.

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

Navigation Menu

Uh oh!

feat: alchemy deployment — the cloudflare-os package with the OperatingSystem resource - #24

feat: alchemy deployment — the cloudflare-os package with the OperatingSystem resource#24
sam-goodwin wants to merge 1 commit into
cloudflare:mainfrom
sam-goodwin:sam/alchemy-deploy

sam-goodwin commented Aug 5, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 5, 2026

Uh oh!

sam-goodwin Aug 5, 2026

Uh oh!

ndisidore Aug 7, 2026

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!

ndisidore Aug 7, 2026

Uh oh!

ndisidore Aug 7, 2026

Uh oh!

ndisidore Aug 7, 2026

Uh oh!

ndisidore Aug 7, 2026 •

edited

Loading

Uh oh!

ndisidore Aug 7, 2026

Uh oh!

ndisidore Aug 7, 2026

Uh oh!

ndisidore Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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!

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!

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

ndisidore Aug 7, 2026 •

edited

Loading