Raspberry Pi tunnel configuration
Cloudflare Tunnel on Raspberry Pi for a continuously running home server
Follow this guide if you want a Raspberry Pi or compact mini PC to keep cloudflared active with a genuine hostname. It includes setup, systemd, safety checks, and when GhostlyShare or the ghs CLI is a simpler option.
The aim is a reliable outbound connection, not complete anonymity. Visitors don’t require router access, but Cloudflare, your accounts, and your usage habits remain important.
A Raspberry Pi is handy when a tunnel must persist through laptop sleep, desktop logoff, and everyday tasks. GhostlyShare also suits long-running shares if you favour app or CLI workflows over manual service files.
Contents
Briefly: choose a Raspberry Pi to keep the tunnel active
A Raspberry Pi is an effective Cloudflare Tunnel connector when your website, dashboard, webhook, or lab service must remain accessible without relying on your daily laptop. It’s not the sole long-running choice; GhostlyShare can offer a simpler tunnel process.
| Requirement | Use | Why |
|---|---|---|
| Persistent hostname for a home service | Cloudflare Tunnel on Raspberry Pi | The Pi can remain online, reboot reliably, and operate cloudflared as a Linux service. |
| Preview, webhook response, or managed share | GhostlyShare | GhostlyShare manages the tunnel workflow via app or CLI, often simpler than manually maintaining cloudflared configuration. |
| Production application with enhanced isolation | VPS or managed hosting | A public server is generally easier to monitor, back up, and isolate from a home network. |
Basic architecture: visitor, Cloudflare, Pi, local service
Cloudflare Tunnel maintains outbound connections from the origin. The Raspberry Pi initiates connector links to Cloudflare, which then maps your public hostname to a local service like localhost:3000 or a LAN address.
Visitors connect to your public hostname at Cloudflare's edge, not directly to a port on your home router.
Cloudflare manages the public edge, DNS zone, tunnel routing, and request path for your hostname.
cloudflared operates on the Pi, maintaining outbound connections to Cloudflare.
The actual application can remain on localhost, a different port, or a LAN device accessible by the Pi.
This should not be seen as a privacy barrier against all parties. It primarily stops visitors and random scans from accessing your home router or discovering the origin directly.
Prepare your Raspberry Pi before installing cloudflared
Most tunnel issues aren’t due to Cloudflare but stem from unstable hardware, changing local service addresses, or unreadable config files for the service user.
Begin with Raspberry Pi OS or Debian, update fully, and opt for 64-bit if your device supports it.
Provide the Pi with a dependable network connection, ideally wired Ethernet or a DHCP reservation if accessing LAN hosts.
Confirm the application functions locally before integrating Cloudflare, DNS, or systemd.
Avoid unintentionally exposing admin panels. Secure private tools behind Cloudflare Access or restrict them to local access.
Hardware choice: select a Raspberry Pi 5 kit, not just the board
For a tunnel connector, a Raspberry Pi 5 kit is a safer bet than a bare board. Ensure you have the board, a reliable USB-C power supply, cooling or a fan, and trusted storage before attributing disconnects to Cloudflare.
Raspberry Pi 5 kit for a compact Cloudflare Tunnel home server
Look for a Raspberry Pi 5 kit including a dependable USB-C power supply, cooling, a case, and storage. 4 GB suffices for cloudflared; 8 GB is better if the Pi also hosts the app.
Use the official Raspberry Pi 27W USB-C power supply or an equivalent 5V/5A unit, and ensure cooling is in place. Insufficient power or overheating can mimic tunnel instability despite correct cloudflared configuration.
Cloudflare Tunnel Raspberry Pi setup guide
Refer to the Cloudflare dashboard or official documentation for the latest package command matching your Pi’s architecture. The commands below provide a reliable workflow, not a guarantee that package URLs remain unchanged.
Step 1: update your Pi and verify its architecture
Apply updates first, then confirm the architecture to select the correct cloudflared package command from Cloudflare.
sudo apt update
sudo apt upgrade -y
dpkg --print-architectureStep 2: install cloudflared using the latest official command
Refer to the Cloudflare dashboard or documentation for the current Linux command suited to your architecture. Confirm the binary after installation.
# Paste the current official Cloudflare install command for your Pi here.
cloudflared --versionStep 3: authenticate and set up a named tunnel
Authorise the Cloudflare zone, create a named tunnel, and copy the tunnel UUID from the output.
cloudflared tunnel login
cloudflared tunnel create home-piStep 4: create a detailed config.yml
Update the tunnel UUID, hostname, local service, and credentials path before running. Ensure the fallback rule remains 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, configure DNS routing, and run in the foreground
Check the ingress rules, set up the DNS route, then run the tunnel in the foreground while testing from a different network.
cloudflared tunnel ingress validate
cloudflared tunnel route dns home-pi app.example.com
cloudflared tunnel run home-piRun cloudflared as a Linux service using the correct config path
On Linux, the key detail is the config path. Installing the service with sudo may switch the home directory to root's, causing the service to miss the config tested under the pi user.
Service step 1: install the service specifying the config path
This prevents the frequent sudo home-directory mismatch between the pi user's tested config and the service account.
sudo cloudflared --config /home/pi/.cloudflared/config.yml service installService step 2: enable the service and verify its status
Launch cloudflared via systemd, then confirm it uses the correct config and remains stable.
sudo systemctl enable --now cloudflared
systemctl status cloudflaredService step 3: review logs and test restarting
Check logs to identify errors in config path, credentials, DNS, or local services before relying on the route.
journalctl -u cloudflared -f
sudo systemctl restart cloudflared
systemctl status cloudflaredChecklist for managing a small, always-on tunnel
A home tunnel is reliably stable only when reboots, updates, logs, and access rules are routine. Test these basics before widely sharing the URL.
Restart the Pi and verify the hostname resolves without needing to open an SSH session first.
Secure private apps using Cloudflare Access, robust app authentication, or a local-only network boundary.
Regularly update the OS and cloudflared, then check the service post-update.
Avoid sharing logs or screenshots containing tunnel IDs, account emails, hostnames, or private service names.
Deliberately back up the config, ensuring tunnel credentials remain secure like sensitive secrets.
This configuration conceals the origin from visitors but does not mask your Cloudflare account, domain history, or administrative actions.
Troubleshooting: common issues to check first
| Symptom | Probable cause | Initial review |
|---|---|---|
| Cloudflare error page shown instead of the app | Tunnel inactive, incorrect service URL, or local app not responding. | Check systemctl status cloudflared, read journalctl, then curl the local service from the Pi. |
| Service runs in foreground but fails post-install | systemd is referencing a different home directory or configuration path. | Reinstall the service specifying --config path as /home/pi/.cloudflared/config.yml. |
| Hostname fails to connect to the tunnel | DNS route, hostname, or Cloudflare zone is not linked to the specified tunnel. | Verify the public hostname in Zero Trust and execute cloudflared tunnel info home-pi. |
| Admin page accessible publicly | Ingress rule directs to a private tool lacking an access layer. | Place it behind Cloudflare Access or restrict the service to local access only. |
Official documentation to review before relying on it
Keep Cloudflare’s official documentation handy during setup. Product names, commands, dashboard layouts, and plan limits may change.
Cloudflare Tunnel installation guide Linux service instructions Tunnel execution parameters
FAQs on Raspberry Pi Cloudflare Tunnel
FAQs
Is a Raspberry Pi suitable for Cloudflare Tunnel?
Yes, it’s ideal for an always-on connection for a small home server or lab setup. It’s energy-efficient, reliable, and simpler to keep running than a laptop used daily.
Is router port forwarding necessary?
No. Cloudflare Tunnel relies on outbound connections from cloudflared to Cloudflare, so no inbound router ports need to be opened.
Should I opt for GhostlyShare CLI instead?
Choose GhostlyShare or the ghs CLI for app-managed local sharing, previews, webhooks, scripted sharing, or long-term shares you deliberately keep active. Use Raspberry Pi with cloudflared when you require full control over service files, ingress configuration, and the host operating system.
Does this make my home server anonymous?
No. While it conceals the origin from visitors, Cloudflare account details, domain records, payments, logs, content, and administrator actions can still link the project back to you.