Raspberry Pi tunnel setup
Cloudflare Tunnel on Raspberry Pi for an always-on home server
Use this guide when a Raspberry Pi or small mini PC should keep cloudflared online for a real hostname. It covers setup, systemd, safety checks, and when GhostlyShare or the ghs CLI is the lighter choice.
The goal is a stable outbound connector, not magic anonymity. Visitors do not need router access, but Cloudflare, your accounts, and your own operating habits still matter.
A Raspberry Pi is useful when a tunnel should survive laptop sleep, desktop logoff, and normal daily work. GhostlyShare can also fit long-running shares when you prefer the app or CLI workflow over manual service files.
Table of Content
Short answer: use a Raspberry Pi when the tunnel must stay online
A Raspberry Pi is a good Cloudflare Tunnel connector when the website, dashboard, webhook endpoint, or lab service should stay reachable without depending on your daily laptop. It is not the only long-running option; GhostlyShare can also be the simpler tunnel workflow.
| Need | Use | Why |
|---|---|---|
| Always-on hostname for a home service | Cloudflare Tunnel on Raspberry Pi | The Pi can stay online, reboot predictably, and run cloudflared as a Linux service. |
| Preview, webhook callback, or managed share | GhostlyShare | GhostlyShare keeps the tunnel workflow in the app or CLI, which can be simpler than hand-maintaining cloudflared config. |
| Production app with stronger isolation | VPS or managed hosting | A public server is usually easier to monitor, back up, and separate from a home network. |
The simple architecture: visitor, Cloudflare, Pi, local service
Cloudflare Tunnel keeps the origin side outbound. The Raspberry Pi opens connector connections to Cloudflare, and Cloudflare maps your public hostname to a local service such as localhost:3000 or a LAN address.
The visitor reaches your public hostname and Cloudflare's edge, not a router port on your home connection.
Cloudflare owns the public edge, DNS zone, tunnel mapping, and request path for the hostname.
cloudflared runs on the Pi and keeps outbound connector sessions open to Cloudflare.
The real app can stay on localhost, another port, or a LAN host that the Pi can reach.
Do not treat this as a privacy wall against every party. It mainly prevents visitors and random scans from reaching your home router or learning the origin directly.
Prepare the Raspberry Pi before installing cloudflared
Most broken tunnel setups are not caused by Cloudflare. They come from an unstable device, a changing local service address, or a config file that the service user cannot read.
Start with Raspberry Pi OS or Debian, apply updates, and prefer 64-bit when the device supports it.
Give the Pi a reliable network path, preferably wired Ethernet or a DHCP reservation if the service reaches LAN hosts.
Make sure the app works locally before involving Cloudflare, DNS, or systemd.
Do not expose admin panels by accident. Put private tools behind Cloudflare Access or keep them local.
Hardware pick: choose a Raspberry Pi 5 kit, not just the bare board
For a tunnel connector, a Raspberry Pi 5 kit is the safer default than a loose board. You want the board, a stable USB-C power supply, cooling or a case fan, and storage you trust before you blame Cloudflare for random disconnects.
Raspberry Pi 5 kit for a small Cloudflare Tunnel home server
Search for a Raspberry Pi 5 kit with a reliable USB-C power supply, cooling, a case, and storage. 4 GB is enough for cloudflared; 8 GB gives more room when the Pi also runs the app.
Prefer the official Raspberry Pi 27W USB-C power supply or an equivalent 5V/5A supply, and do not skip cooling. Weak power and heat can look like tunnel instability even when the cloudflared config is correct.
Cloudflare Tunnel Raspberry Pi setup runbook
Use the Cloudflare dashboard or official docs for the current package command for your Pi architecture. Keep the commands below as a safe order of work, not as a promise that package URLs never change.
Step 1: update the Pi and confirm the architecture
Install updates first, then check the architecture so you copy the right cloudflared package command from Cloudflare.
sudo apt update
sudo apt upgrade -y
dpkg --print-architectureStep 2: install cloudflared from the current official command
Use the Cloudflare dashboard or docs for the current Linux command that matches your architecture. Verify the binary after installation.
# Paste the current official Cloudflare install command for your Pi here.
cloudflared --versionStep 3: authenticate and create a named tunnel
Authorize the Cloudflare zone, create a named tunnel, and copy the tunnel UUID from the output.
cloudflared tunnel login
cloudflared tunnel create home-piStep 4: write an explicit config.yml
Replace the tunnel UUID, hostname, local service, and credentials path before you run it. The fallback rule should stay last.
mkdir -p ~/.cloudflared
nano ~/.cloudflared/config.ymltunnel: <tunnel-uuid>
credentials-file: /home/pi/.cloudflared/<tunnel-uuid>.json
ingress:
- hostname: app.example.com
service: http://localhost:3000
- service: http_status:404Step 5: validate, route DNS, and run in the foreground
Validate the ingress rules, create the DNS route, then keep the tunnel in the foreground while you test from another network.
cloudflared tunnel ingress validate
cloudflared tunnel route dns home-pi app.example.com
cloudflared tunnel run home-piRun cloudflared as a Linux service with the right config path
The important detail on Linux is the config path. If you install a service with sudo, the home directory can become root's home, so the service may not find the config you tested as the pi user.
Service step 1: install the service with an explicit config path
This avoids the common sudo home-directory mismatch between the tested pi user config and the service account.
sudo cloudflared --config /home/pi/.cloudflared/config.yml service installService step 2: enable the service and check status
Start cloudflared through systemd, then verify that it uses the expected config and stays healthy.
sudo systemctl enable --now cloudflared
systemctl status cloudflaredService step 3: read logs and test a restart
Use the logs to catch config path, credentials, DNS, and local service errors before you depend on the route.
journalctl -u cloudflared -f
sudo systemctl restart cloudflared
systemctl status cloudflaredOperations checklist for a small always-on tunnel
A home tunnel becomes boring in a good way only when reboot, updates, logs, and access rules are boring too. Test the boring parts before you share the URL widely.
Restart the Pi and confirm the hostname works without opening an SSH session first.
Put private apps behind Cloudflare Access, strong app login, or a local-only network boundary.
Patch the OS and cloudflared regularly, then verify the service after updates.
Do not publish logs or screenshots with tunnel IDs, account emails, hostnames, or private service names.
Back up the config intentionally, but protect tunnel credentials like secrets.
This setup hides the origin from visitors; it does not hide your Cloudflare account, domain trail, or admin behavior.
Troubleshooting: the failures that usually matter first
| Symptom | Likely cause | First check |
|---|---|---|
| Cloudflare error page instead of the app | Tunnel is down, service URL is wrong, or the local app is not listening. | Run systemctl status cloudflared, journalctl, and curl the local service on the Pi. |
| Service works in foreground but not after install | systemd is using a different home directory or config path. | Install the service again with an explicit --config path to /home/pi/.cloudflared/config.yml. |
| Hostname does not reach the tunnel | DNS route, hostname, or Cloudflare zone is not connected to the named tunnel. | Confirm the public hostname in Zero Trust and run cloudflared tunnel info home-pi. |
| Admin page is publicly reachable | The ingress rule points at a private tool without an access layer. | Move it behind Cloudflare Access or keep that service local-only. |
Official docs worth checking before you rely on it
Keep the Cloudflare vendor docs open while you set up the Pi. Product names, package commands, dashboard screens, and plan limits can change.
Cloudflare Tunnel setup guide Linux service guide Tunnel run parameters
Frequently asked questions about Raspberry Pi Cloudflare Tunnel
FAQ
Is a Raspberry Pi good for Cloudflare Tunnel?
Yes, when you want an always-on connector for a small home server or lab service. It is low-power, predictable, and easier to leave online than a daily laptop.
Do I need router port forwarding?
No. Cloudflare Tunnel uses outbound connector connections from cloudflared to Cloudflare, so visitors do not need a direct inbound route to your router.
Should I use GhostlyShare CLI instead?
Use GhostlyShare or the ghs CLI when you want app-managed local sharing for previews, webhooks, scripted sharing, or a long-running share you intentionally keep online. Use Raspberry Pi plus cloudflared when you want full control over service files, ingress config, and the host OS.
Does this make my home server anonymous?
No. It can hide the origin from visitors, but Cloudflare account data, domain records, payments, logs, content, and admin behavior can still connect the project to you.