Running Caddy on Cloudflare Workers via WebAssembly

Hi folks. This is my first post. Happy to join you here :)

I’ve been running Caddy in production long enough to know two things: the Caddyfile is a joy to work with, and everything around it tends to get way more complicated than it should.

For over a decade, the software engineering industry has been captivated by the containerization paradigm. You start with a clean Caddyfile on your laptop, then you add Docker for a $5 Virtual Private Server (VPS), then Helm charts, Terraform, or custom CI glue to get things into a Kubernetes cluster or edge platform. Suddenly, that elegant routing config is buried under YAML and infrastructure that mostly exists just to move the same HTTP rules between environments.

So, I asked a simple question: What if one Caddyfile could run on my laptop, on a cheap VPS, and on the infinitely scalable Cloudflare edge - without Docker, and without rewriting configs?

That question led to a profound architectural shift: compiling the Caddy web server directly to WebAssembly (WASM) and executing it natively on Cloudflare Workers.

Here is how bypassing the containerization trap entirely allows us to turn the edge into just another place Caddy lives.

Missed Shots

Initially all I had was a Coolify VDS from Hetzner - its wonderful solution if utilization is high, but in case of pet projects or low-usage services the cost of idling > value. Add here manual scaling management.

I tried to run my Caddy server natively in Cloudflare Containers - but the runtime is complex, cold starts are slow and pricing is not that free.

Then I tried AWS Lightsail and Google CloudRun - both are exellent solutions but still require separate DNS/Domain/TLS management to run in no-infra-config setups, also burning money at the unbelievable speeds.

V8 Isolates vs. Containers

To understand how a monolithic Go application like Caddy can run on a serverless edge network, we have to look at the execution environment. Cloudflare Workers do not use containers or micro-VMs. They are powered by workerd, an open-source runtime built on Google’s V8 JavaScript engine.

The fundamental unit of execution here is the V8 isolate. When a request arrives, the V8 engine does not boot a Linux kernel, allocate a network namespace, or spin up control groups (cgroups). It simply allocates a memory context and executes the code.

Because Caddy is written in Go, it cannot execute natively as JavaScript. However, V8 incorporates a highly optimized WebAssembly execution engine. By targeting WASM, we can stream Go-based routing logic into optimized machine code just-in-time, allowing Caddy to execute with near-native performance at the edge.

Ripping Out the TCP Listener

Compiling Caddy is only half the battle. Cloudflare Workers are not Linux environments; they do not give you raw TCP sockets. The primitive in a Worker is not a port binding - it is the fetch() API.

Therefore, to make Caddy run, we must intercept its initialization sequence and disable the standard net.Listener.

The request lifecycle becomes a complex orchestration of memory passing:

1. Ingress: Cloudflare terminates TLS at the edge.
2. JS Event Trigger: A lightweight JavaScript shim listens for the fetch event.
3. Memory Serialization: The shim serializes the request and writes it into the WebAssembly module's linear memory using the Foreign Function Interface (FFI).
4. The Translation: Inside the WASM boundary, a translation layer (like syumai/workers) deserializes the bytes and constructs a standard, idiomatic Go *http.Request.
5. Caddy Router Execution: Caddy’s core ServeHTTP function takes over, evaluating the Caddyfile rules exactly as if the request arrived via a TCP socket.

Because Caddy can no longer dial out via standard TCP, its reverse_proxy module must also be wired to route upstream requests through Cloudflare's fetch() mechanism.

A Universal Configuration

The technical friction required to port Caddy to workerd pays immense dividends in developer experience. The Caddyfile becomes the universal source of truth.

{  
    admin off  
    auto_https off  
}

:80 {  
    reverse_proxy https://api.my-upstream.com  
    header +X-Edge-Served "Caddy-WASM"  
}

With this setup, the deployment topology looks entirely different:

• Local Development: Run caddy run --config Caddyfile natively on your MacBook.
• Legacy VPS: Drop the same config into a $5/mo Linux box running systemd.
• The Edge: Bundle the Caddyfile into the WASM module and deploy via wrangler.

You no longer need a swarm of custom Nginx configs, Kubernetes Ingress manifests, and bespoke "edge routing" scripts just to manage environment parity.

Cost Model

Docker-based hosting prices workloads like a process: you pay for CPU, memory, disk, and idle capacity. That is reasonable when you need a persistent process.

Workers native WASM prices the workload based on requests and CPU time. By pushing the API gateway to the extreme perimeter of the internet via a lightweight V8 isolate, the concept of idle infrastructure is eliminated. When traffic drops to zero, the isolate is evicted from memory, and the cost drops to zero. You reap the benefits of an enterprise-grade API gateway without managing a single server or container.

Constraints and the Future

Being honest, this isn’t a silver bullet yet. Operating on the bleeding edge of WASM comes with strict constraints:

1. Memory Ceilings: Workers enforce strict memory limits (often 128 MB). You cannot buffer massive file uploads in memory; you must rely strictly on streaming architectures to keep the Go garbage collector happy.
2. Opaque Debugging: If the Go runtime panics, V8 terminates execution and returns a generic 500 error. Traditional tools like strace or delve don't exist here yet.

However, the future is incredibly bright. The standardization of WASI-HTTP will soon allow V8 isolates to pass network streams directly into WASM linear memory with zero-copy efficiency. Furthermore, the upcoming WebAssembly Component Model will allow us to distribute Caddy not as a monolithic 20MB+ binary, but as a mesh of strongly typed, dynamically linked components - achieving instantaneous cold starts.

I’m curious - how are you all handling the "proxy tax" in your current stacks? Have you experimented with WASM runtimes for infrastructure components yet, or currently sticking with containers?

The Era of the Ubiquitous Proxy

Infrastructure gets better when we remove unnecessary translations. I do not want to maintain one routing language for local development, another for a VPS, and another for the edge. I want to describe HTTP behavior once, then choose where it runs.

Deploying Caddy on Cloudflare Workers via WASM systematically strips away the operating system kernel, the container namespace, and the physical network socket, leaving us with pure, highly secure routing logic.

The era of the idle proxy server is ending. One Caddyfile. Many runtimes.

Full repo https://github.com/theuargb/caddy-on-cloudflare/tree/workerd.