IRIsuru Ratnayake

Run Cloudflare's cloudflare-os in Docker with One Command

Skip the Node 22, pnpm and Wrangler setup. Run Cloudflare's open-source cloudflare-os locally with one docker run command, plus the wrangler dev fix.

Isuru Ratnayake

Isuru Ratnayake

· 3 min read

Cloudflare recently open-sourced cloudflare-os, a new project that adds an "operating system" layer for developers building on Cloudflare Workers. It gives teams an AI workspace to build personal micro-apps (which it calls Gadgets), automate workflows and run agents with enterprise-grade Zero Trust guardrails.

It's an exciting step for edge computing. But like most brand-new developer tools, trying it locally takes some setup: you need Node 22, pnpm, a clone of the repository and a working local environment.

While setting it up I also hit a hidden networking trap that took a while to debug. So I built a zero-configuration Docker image: you can skip the setup entirely and be experimenting in under 60 seconds.

Quick start: one command

You don't need Node, pnpm or Wrangler on your machine. Only Docker:

docker run -p 8787:8787 ratnayake/cloudflare-os:latest

Then open http://localhost:8787 in your browser.

For a reproducible environment, use the pinned tag instead of latest:

docker run -p 8787:8787 ratnayake/cloudflare-os:1.0.1

If port 8787 is already taken on your machine, map a different host port, for example -p 8788:8787, and open http://localhost:8788.

The hidden bug: why wrangler dev doesn't work in Docker out of the box

If you put a Workers project in a container as-is, you'll probably hit a frustrating wall: the container starts and the logs say the server is ready, but the browser can't connect.

The reason is that wrangler dev binds to localhost (127.0.0.1) by default.

  • On your own machine, that's fine: your browser and the dev server share the same localhost.
  • Inside a Docker container, localhost is the container's own loopback interface. Even with docker run -p 8787:8787, requests from your host arrive on the container's network interface, where nothing is listening. They silently fail.

It looks like a Docker networking problem, but it's just Wrangler's default. The fix is to make Wrangler listen on 0.0.0.0, meaning all interfaces, inside the container.

For your own Workers projects in Docker, you can do this with the command-line flag:

wrangler dev --ip 0.0.0.0

or permanently in wrangler.jsonc:

"dev": { "ip": "0.0.0.0" }

How the image is built

The Dockerfile handles setup, patching and building end to end:

  1. Base image: the official pnpm image, set to Node 22.
  2. Fresh source: it clones cloudflare/cloudflare-os at build time with git clone --depth 1, so you get the latest upstream code without the full history.
  3. Automatic binding patch: it inserts "dev": { "ip": "0.0.0.0" } into wrangler.jsonc during the build, and fails the build if the patch didn't apply.
  4. Pre-baked layers: the project's install and build run during the image build, so node_modules and the compiled assets are already inside the image.
  5. Instant start-up: the container's start command launches the dev server straight away, with no dependency downloads when you run it.

Step 4 needed a small trick. The project's pnpm run-local command installs, builds and then keeps running the dev server, and it has no "build only" mode. The Dockerfile runs it under timeout, checks the log for the "Starting local server" line to confirm the build really finished, then stops it. The result is cached in the image layer, so docker run skips straight to serving.

Build the image yourself

Prefer to read the source or build locally? Clone the setup repository and build:

git clone https://github.com/ratnayake/cloudflare-os.git
cd cloudflare-os
docker build -t cloudflare-os .
docker run -p 8787:8787 cloudflare-os

To pick up the latest commits from Cloudflare's repository, rebuild without the cache:

docker build --no-cache -t cloudflare-os .

Important notes

  • Community maintained: this is an unofficial wrapper for fast local testing. It isn't affiliated with or endorsed by Cloudflare, and all credit for cloudflare-os goes to the Cloudflare team.
  • For local development: the image runs the Wrangler dev server. It's meant for experimenting and testing, not for production hosting.

Resources

If the image saves you time, a star on the GitHub repo is appreciated. And if you need help containerising an app, setting up Docker-based development or moving a project to Cloudflare or AWS, get in touch. I reply within a few hours.

  • Cloudflare
  • Docker
  • Open Source
  • DevOps
Isuru Ratnayake

Isuru Ratnayake

Senior WordPress & PHP Developer. Top Rated on Upwork with 250+ completed jobs and 15+ years of PHP & WordPress experience.