Additional info for running cloudflare-os on Windows 11 VM

[realdeal-not-ai]

DISCLAIMER: After the user (me, a human - rank: amateur) spent a little while troubleshooting an attempt to install and run cloudflare-os for testing, the article below was created by the LLM that assisted me to get it working (partial edits by me).

I figured it might be helpful to others who are attempting to run the current build (as at 2026-08-09).

Nonetheless, USE THIS GUIDE WITH CAUTION. Maybe backup your VM in the first instance, and always backup any files that you edit.

Additional info for running cloudflare-os on a Windows 11 VM

Target Audience: Anyone who has attempted to install and run cloudflare-os on a Windows 11 VM using an Intel CPU, for testing purposes, and has encountered errors as outlined below in Common Issues & Fixes.

Platforms: Windows 11 VM (x64), Node.js, pnpm

---

Overview

Setting up Unix-first monorepos like cloudflare-os on a native Windows 11 VM can encounter pathing, process-spawning, and binary runtime compatibility issues. This guide outlines the key fixes required to get the local development stack up and running on http://localhost:8787.

---

Prerequisites

Before starting, ensure your system has the following installed:

• Node.js 22 LTS
  Use Node 22 LTS. Avoid non-LTS versions like Node 24, which have Windows process bugs.
• pnpm (v11 or newer)
  Required package manager for workspace management.
• Microsoft Visual C++ 2015–2022 Redistributable (x64)
  Required to run Cloudflare's background workerd.exe runtime.
• PowerShell or Git Bash
  Administrator access is needed during setup.

---

Common Issues & Fixes

1. Fix: Error: spawnSync pnpm ENOENT

• Symptom: Running pnpm run-local crashes immediately with an ENOENT error referencing pnpm.
• Cause: On Windows, pnpm is a batch script (pnpm.cmd). Calling Node's execFileSync without { shell: true } causes Windows to look for pnpm.exe, which fails.
• Fix: Add { shell: true } to the options object in execFileSync across the project's build scripts.

// Example modification in Node scripts:
execFileSync("pnpm", ["exec", "vite", "build"], { 
  stdio: "inherit", 
  cwd: ROOT, 
  shell: true // <-- Required for Windows
});

Files that require this edit:

• scripts/run-local.mjs
• run-dev-server.js
• packages/gatekeeper-context/build-app.mjs
• packages/gatekeeper-scheduler/build-app.mjs

---

2. Fix: Node 24 Assertion Crash (0xC0000005)

• Symptom: The server crashes during process spawning with:
  Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c
• Cause: Node 24 (non-LTS) has low-level pipe bugs on Windows when communicating with child processes.
• Fix: Switch to Node 22 LTS using nvm-windows.

# Install nvm and switch to Node 22
winget install CoreyButler.NVMforWindows
nvm install 22
nvm use 22

# Verify active version
node -v

---

3. Fix: Wrangler ✘ [ERROR] write EOF

• Symptom: The frontend builds successfully, but Wrangler fails when starting the local server with write EOF.
• Cause: Cloudflare's C++ runtime binary (workerd.exe) crashes on startup due to missing C++ runtime DLLs (VCRUNTIME140.dll / MSVCP140.dll) on fresh Windows VMs.
• Fix: Install the Microsoft Visual C++ 2015–2022 Redistributable.

# Run in PowerShell as Administrator
winget install Microsoft.VCRedist.2015+.x64

---

Quick Setup Steps

Follow these steps to set up a fresh Windows 11 VM for cloudflare-os:

1. Install Runtime Dependencies:

winget install Microsoft.VCRedist.2015+.x64
winget install CoreyButler.NVMforWindows

2. Set Node Version:

nvm install 22
nvm use 22

3. Verify workerd.exe Binary:

Get-ChildItem -Recurse -Filter "workerd.exe" | Select-Object -First 1 | ForEach-Object { & $_.FullName --version }

If a version string prints without error, the environment is ready.
4. Install & Run:

pnpm install
pnpm run-local

---

Verification

When successfully launched, your terminal will confirm that Vite has bundled the client assets, gatekeepers have generated their definitions, and Wrangler is running on http://localhost:8787