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,
localhostis the container's own loopback interface. Even withdocker 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:
- Base image: the official pnpm image, set to Node 22.
- Fresh source: it clones
cloudflare/cloudflare-osat build time withgit clone --depth 1, so you get the latest upstream code without the full history. - Automatic binding patch: it inserts
"dev": { "ip": "0.0.0.0" }intowrangler.jsoncduring the build, and fails the build if the patch didn't apply. - Pre-baked layers: the project's install and build run during the image build, so
node_modulesand the compiled assets are already inside the image. - 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
- Docker Hub image: ratnayake/cloudflare-os
- Docker setup on GitHub: ratnayake/cloudflare-os
- Upstream project: cloudflare/cloudflare-os
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.
