Forem: Ashab Hussan

How I Use Cloudflare Tunnel for Local Webhooks

Ashab Hussan — Sat, 03 Jan 2026 00:00:00 +0000

While working with third-party services like Stripe, Paddle, or Qstash, I constantly deal with webhooks hitting my local machine during development.

For a long time, I used tools like ngrok. They work — but the problem is always the same:

Restart the tunnel → get a new URL → update webhook configs in every service dashboard again.

That gets old fast, especially when multiple services depend on the same endpoint.

I switched to Cloudflare Tunnel, and it completely solved this problem. Now I have stable, HTTPS webhook URLs pointing to my local machine — no restarts, no reconfiguration, no URL rotation.

This post explains exactly how I set it up.

Why Cloudflare Tunnel Over ngrok?

Both tools create a tunnel from the internet to your local machine. The difference:

Feature	ngrok (free tier)	Cloudflare Tunnel
Stable URLs	No — new URL on every restart	Yes — permanent subdomains
Custom domains	Paid plans only	Free (if domain is on Cloudflare)
HTTPS	Yes	Yes (auto-provisioned)
Multiple services	One tunnel per agent	Multiple hostnames in one tunnel
Cost	Free tier is limited	Free

The killer feature for me: stable URLs. I set stripe-webhook.example.com once in the Stripe dashboard, and it works forever. No matter how many times I restart the tunnel or reboot my machine, the URL stays the same.

Prerequisites

Before starting, make sure:

You have a Cloudflare account (free)
You own a domain with its DNS managed by Cloudflare

If your domain isn't on Cloudflare yet, you can add it for free — Cloudflare's free plan includes DNS management and tunnel support.

Installing cloudflared

Install the cloudflared CLI for your platform:

macOS

brew install cloudflared

Linux (Debian/Ubuntu)

curl -LO https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Windows

winget install --id Cloudflare.cloudflared

Verify the installation:

cloudflared --version
# cloudflared version 2024.12.x (I'm using whatever Homebrew installs)

Authenticating with Cloudflare

Link cloudflared to your Cloudflare account:

cloudflared tunnel login

This opens a browser where you log in and select the domain you want to use. After success, credentials are saved under:

macOS/Linux: ~/.cloudflared/
Windows: %USERPROFILE%\.cloudflared\

Creating a Named Tunnel

cloudflared tunnel create webhook-dev

This creates a persistent tunnel and outputs a tunnel ID (a UUID). You'll need this ID for the config file.

A named tunnel is the key to stable URLs — the tunnel ID stays the same across restarts.

Configuring Ingress Rules

Create the config file at ~/.cloudflared/config.yml:

tunnel: webhook-dev
credentials-file: /Users/you/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: stripe-webhook.example.com
    service: http://127.0.0.1:3000
    originRequest:
      httpHostHeader: localhost

  - hostname: qstash-webhook.example.com
    service: http://127.0.0.1:8080

  - service: http_status:404

This setup:

Routes stripe-webhook.example.com to your local app on port 3000
Routes qstash-webhook.example.com to a different local service on port 8080
Returns 404 for any other hostname (safety catch-all)

The originRequest.httpHostHeader setting is only needed if your local app checks the Host header for routing (common with Express virtual hosts or Nginx). If you're not sure, include it — it doesn't hurt.

You can add as many hostname entries as you need. I have 3-4 running at any time during development.

Routing DNS to the Tunnel

Tell Cloudflare to point your subdomains to the tunnel:

cloudflared tunnel route dns webhook-dev stripe-webhook.example.com
cloudflared tunnel route dns webhook-dev qstash-webhook.example.com

Cloudflare automatically creates CNAME DNS records for these subdomains. No manual DNS editing needed. HTTPS certificates are provisioned automatically too.

You only need to run these commands once per hostname. After that, the DNS records persist even if the tunnel is stopped.

Running the Tunnel

Start the tunnel for local development:

cloudflared tunnel run webhook-dev

At this point, https://stripe-webhook.example.com forwards traffic directly to http://127.0.0.1:3000 on your machine. Configure this URL once in your Stripe (or any other service) webhook settings, and never touch it again.

To stop: Ctrl+C. Your webhook URLs will return errors while the tunnel is down, but the DNS records stay in place. Next time you run the tunnel, everything reconnects instantly.

My Daily Workflow

My typical development session:

# Terminal 1: Start the tunnel
cloudflared tunnel run webhook-dev

# Terminal 2: Start my app
npm run dev

# Terminal 3: Trigger webhooks from service dashboards or CLI tools
# Stripe: stripe trigger payment_intent.succeeded
# Everything hits my local machine through the stable URL

When I'm done for the day, I stop the tunnel and my app. Next morning, I start them again — same URLs, no reconfiguration.

Common Issues I Ran Into

502 or 523 errors: Your tunnel is running but the local app isn't, or it's running on a different port. Double-check the port in config.yml matches your actual app.

DNS not resolving: You created the tunnel but forgot to route the hostname. Run:

cloudflared tunnel route dns webhook-dev your-hostname.example.com

Host header mismatch: Some frameworks (Express with virtual hosts, Nginx) reject requests where the Host header doesn't match expectations. Fix with:

originRequest:
  httpHostHeader: localhost

Permission errors on Linux: If running as a non-root user, make sure the credentials file is readable:

chmod 600 ~/.cloudflared/<tunnel-id>.json

Debugging tunnel issues: Run with verbose logging to see exactly what's happening:

cloudflared tunnel run webhook-dev --loglevel debug

Other useful commands:

cloudflared tunnel list # see all your tunnels
cloudflared tunnel info webhook-dev # details about a specific tunnel

Final Thoughts

Cloudflare Tunnel gave me stable, secure webhook URLs without the constant URL rotation of ngrok's free tier. Once it's set up, it just works — and it's completely free if your domain is already on Cloudflare.

The official Cloudflare Tunnel docs cover advanced setups like running the tunnel as a system service, load balancing, and access policies if you need to go further.

I use this alongside Colima for a lightweight Docker setup — if you're still on Docker Desktop, here's my experience switching to Colima on macOS.

Thanks for reading — and stay tuned.

Switching from Docker Desktop to Colima on macOS

Ashab Hussan — Thu, 20 Nov 2025 00:00:00 +0000

I recently switched to Colima as my Docker Desktop alternative on macOS — and I'm not going back. It's lightweight, starts in seconds, and plugs straight into the existing Docker CLI and docker-compose. If you want a faster local container setup with no new learning curve, Colima is worth trying.

Why I Switched from Docker Desktop to Colima

Docker Desktop worked fine for a long time, but a few things started bothering me:

Resource usage — Docker Desktop was eating 2-4GB of RAM even when idle. On a 16GB MacBook, that's noticeable.
Slow startup — launching Docker Desktop and waiting for the engine to be "ready" took 20-30 seconds. Colima starts in under 5 seconds.
The UI I never use — I do everything from the terminal. The Docker Desktop dashboard was just sitting there consuming resources.
License concerns — Docker Desktop requires a paid subscription for companies with 250+ employees or $10M+ revenue. Colima is free and open source.

I wanted something that runs containers, works with my existing docker and docker-compose commands, and stays out of the way. That's exactly what Colima does.

What Is Colima?

Colima is a container runtime for macOS (and Linux). It creates a lightweight Linux VM using Lima, and runs Docker (or containerd) inside it. The key point: it exposes the standard Docker socket, so all your existing Docker commands, Compose files, and workflows work unchanged.

It's not a Docker replacement — it's a Docker Desktop replacement. The docker CLI stays the same. Only the engine running behind it changes.

Setting Up Colima on macOS

Here's the full setup:

1. Install Colima and Docker CLI

brew install colima docker docker-compose

This installs Colima (the VM manager), the Docker CLI (the commands), and the Docker Compose plugin. You don't need Docker Desktop installed at all — if it's still installed, you can remove it.

2. Start Colima

colima start --cpu 4 --memory 4 --disk 60

This creates a VM with 4 CPU cores, 4GB RAM, and 60GB disk. Adjust based on your machine. On my M1, this starts in about 3-5 seconds.

If you need to change these later:

colima stop
colima start --cpu 2 --memory 8 --disk 100

3. Verify everything works

colima status
docker info
docker run hello-world

If docker run hello-world prints the success message, you're good. Every Docker command you already know works from this point.

4. Use Docker like before

docker-compose up -d
docker build -t myapp .
docker ps

Nothing changes in your day-to-day commands. That's the whole point.

Docker Commands Quick Reference

Colima doesn't replace Docker commands — it just replaces the engine running behind them:

Task	Command
View all containers	`docker ps -a`
Stop all containers	`docker stop $(docker ps -aq)`
Remove all containers	`docker rm $(docker ps -aq)`
Remove all images	`docker rmi $(docker images -aq)`
Clean everything	`docker system prune -a`
Shell into a container	`docker exec -it <container> sh`

Colima-Specific Commands

These are the only new commands you need to learn:

colima start # start the VM
colima stop # stop the VM (containers pause)
colima delete # delete the VM entirely (careful — you lose containers)
colima status # check if VM is running
colima list # list all VMs
colima start --kubernetes # start with K8s enabled

My daily workflow: colima start when I begin work, colima stop when I'm done. That's it.

Resource Comparison

Here's the rough difference I noticed on my M1 MacBook Pro with 16GB RAM:

Metric	Docker Desktop	Colima
Idle RAM usage	2-4 GB	~600 MB
Startup time	20-30 seconds	3-5 seconds
Background processes	Multiple (Docker Desktop, Docker Engine, etc.)	Single `colima` process
GUI	Full dashboard app	None (CLI only)
Cost	Free for personal, paid for business	Free and open source

These aren't scientific benchmarks — just what I observed on my machine during normal development. The RAM difference alone made the switch worth it.

Common Issues and Gotchas

A few things I ran into during the switch:

Colima VM not starting after macOS update: After a macOS system update, Colima occasionally fails to start with a cryptic error. The fix is usually:

colima delete
colima start --cpu 4 --memory 4 --disk 60

You lose running containers, but your images rebuild from Dockerfiles and Compose files anyway. It's a minor inconvenience.

Volume mounts only cover your home directory: By default, Colima mounts ~ into the VM. If your project lives outside your home directory, containers can't access the files. I keep everything under ~/projects so this wasn't an issue, but it's worth knowing. You can configure additional mounts in ~/.colima/default/colima.yaml.

Docker socket path: Some tools expect the Docker socket at /var/run/docker.sock. Colima creates it at ~/.colima/default/docker.sock. If a tool complains it can't find Docker, add this to your shell profile:

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

Port conflicts with AirPlay on macOS: macOS Sonoma uses port 5000 and 7000 for AirPlay Receiver. If you're mapping containers to these ports, you'll get a "port already in use" error. Either change the port mapping or disable AirPlay Receiver in System Settings → General → AirDrop & Handoff.

Docker Compose v1 vs v2: If you install docker-compose via Homebrew, you get v2 (invoked as docker compose with a space). If your scripts use docker-compose with a hyphen, either update them or create an alias:

alias docker-compose='docker compose'

Final Thoughts

Switching to Colima took about 5 minutes and I haven't opened Docker Desktop since. My machine runs cooler, containers start just as fast, and I didn't change a single Dockerfile or Compose file.

If you're a CLI-first developer who doesn't need Docker Desktop's GUI, give Colima a try. The official README covers advanced configuration like Kubernetes, custom VM profiles, and containerd mode.

If you're also streamlining your local dev setup, check out how I use Cloudflare Tunnel for stable local webhook URLs — another tool that removed a lot of friction from my workflow.

Thanks for reading — and stay tuned.