From 00c08ccc4b438f2fba695ecbba03c336e609f3b7 Mon Sep 17 00:00:00 2001
From: Declan Carroll <declan@n8n.io>
Date: Thu, 26 Feb 2026 19:45:44 +0000
Subject: [PATCH] Update tunnel docs from localtunnel to cloudflared (#4288)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Kartik Balasubramanian <22399046+HumanistSerif@users.noreply.github.com>
---
 _snippets/self-hosting/installation/tunnel.md |  8 +++-
 docs/hosting/installation/docker.md           | 40 +++++++++++++------
 docs/hosting/installation/npm.md              | 22 +++++++++-
 3 files changed, 55 insertions(+), 15 deletions(-)

diff --git a/_snippets/self-hosting/installation/tunnel.md b/_snippets/self-hosting/installation/tunnel.md
index fa0d83b54..8ecf57278 100644
--- a/_snippets/self-hosting/installation/tunnel.md
+++ b/_snippets/self-hosting/installation/tunnel.md
@@ -4,4 +4,10 @@
 Use this for local development and testing. It isn't safe to use it in production.
 ///
 
-To use webhooks for trigger nodes of external services like GitHub, n8n has to be reachable from the web. n8n runs a [tunnel service](https://github.com/localtunnel/localtunnel) that can redirect requests from n8n's servers to your local n8n instance.
+/// warning | Development tooling
+The tunnel feature is a convenience tool for local development. The underlying implementation may change between n8n versions.
+///
+
+To use webhooks for trigger nodes of external services like GitHub, n8n has to be reachable from the web. n8n provides a tunnel service using [cloudflared](https://github.com/cloudflare/cloudflared) that redirects requests from the web to your local n8n instance. Docker must be installed for the tunnel to work.
+
+There are two ways to use the tunnel, depending on how you run n8n:
diff --git a/docs/hosting/installation/docker.md b/docs/hosting/installation/docker.md
index 1e0c2e218..c73c76aae 100644
--- a/docs/hosting/installation/docker.md
+++ b/docs/hosting/installation/docker.md
@@ -130,21 +130,37 @@ docker run --name=<container_name> [options] -d docker.n8n.io/n8nio/n8n
 
 --8<-- "_snippets/self-hosting/installation/tunnel.md"
 
-Start n8n with `--tunnel` by running:
+### Full stack
+
+This runs n8n and cloudflared together in containers. The tunnel URL prints on startup and everything is wired automatically:
 
 ```shell
-docker volume create n8n_data
+pnpm stack --tunnel
+```
 
-docker run -it --rm \
- --name n8n \
- -p 5678:5678 \
- -e GENERIC_TIMEZONE="<YOUR_TIMEZONE>" \
- -e TZ="<YOUR_TIMEZONE>" \
- -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
- -e N8N_RUNNERS_ENABLED=true \
- -v n8n_data:/home/node/.n8n \
- docker.n8n.io/n8nio/n8n \
- start --tunnel
+### Services only
+
+If you prefer to run n8n locally with `pnpm dev` or `pnpm start`, you can start cloudflared as a standalone service:
+
+```shell
+# Terminal 1: Start the cloudflared tunnel service
+pnpm --filter n8n-containers services --services cloudflared
+
+# Terminal 2: Start n8n locally
+pnpm dev
+```
+
+The `services` command:
+
+1. Starts cloudflared pointing at `host.docker.internal:5678` (your local n8n).
+2. Fetches the public tunnel URL from cloudflared's metrics endpoint.
+3. Writes a `.env` file to `packages/cli/bin/.env` with `WEBHOOK_URL` and `N8N_PROXY_HOPS=1`.
+4. `pnpm dev` and `pnpm start` pick up that `.env` automatically via dotenv.
+
+Clean up when done:
+
+```shell
+pnpm --filter n8n-containers services:clean
 ```
 
 ## Next steps
diff --git a/docs/hosting/installation/npm.md b/docs/hosting/installation/npm.md
index ce72073d3..8b2826b90 100644
--- a/docs/hosting/installation/npm.md
+++ b/docs/hosting/installation/npm.md
@@ -70,12 +70,30 @@ npm install -g n8n@next
 
 --8<-- "_snippets/self-hosting/installation/tunnel.md"
 
-Start n8n with `--tunnel` by running:
+/// note | Docker required
+The tunnel uses cloudflared, which runs as a Docker container. Make sure [Docker](https://docs.docker.com/get-docker/) is installed on your machine, even when running n8n via npm.
+///
+
+For npm installations, use the **services only** approach. Start cloudflared as a standalone service, then run n8n locally:
 
 ```bash
-n8n start --tunnel
+# Terminal 1: Start the cloudflared tunnel service
+pnpm --filter n8n-containers services --services cloudflared
+
+# Terminal 2: Start n8n locally
+pnpm dev
 ```
 
+The `services` command starts cloudflared, fetches the public tunnel URL, and writes a `.env` file to `packages/cli/bin/.env` with `WEBHOOK_URL` and `N8N_PROXY_HOPS=1`. n8n picks up this `.env` automatically on startup.
+
+Clean up when done:
+
+```bash
+pnpm --filter n8n-containers services:clean
+```
+
+For the full stack approach (n8n and cloudflared both in containers), refer to the [Docker tunnel setup](/hosting/installation/docker.md#n8n-with-tunnel).
+
 ## Reverting an upgrade
 
 Install the older version that you want to go back to.