🌩️ Cloudflare Tunnel automation script for Laravel Herd - Share your local development sites instantly with custom domains.
cftunnel is a powerful command-line tool that automates the setup and management of Cloudflare tunnels for your Laravel Herd local development environment. With a single command, you can expose your local sites to the internet using your own custom domains.
- 🚀 One-command setup - No complex configuration files
- 🔒 Secure tunnels - Uses Cloudflare's zero-trust network
- 🌐 Custom domains - Use your own domains instead of random URLs
- 🔄 Automatic management - Handles tunnel creation, DNS routing, and cleanup
- 🎯 Laravel Herd integration - Perfect for PHP/Laravel development
- 💾 Persistent tunnels - Remembers your configurations between sessions
- ✅ Automatic Cloudflare tunnel creation and management
- ✅ DNS route configuration via Cloudflare API
- ✅ Laravel Herd domain linking
- ✅ HTTPS support with
--secureflag - ✅ Multiple tunnel management
- ✅ Configuration persistence
- ✅ Graceful cleanup and removal
- ✅ Error recovery and validation
Before installing cftunnel, ensure you have the following:
- Laravel Herd - Download from herd.laravel.com
- Cloudflared - Cloudflare tunnel client
- jq - JSON processor
- A domain managed by Cloudflare
brew install cloudflared jq# Download and install
curl -L https://raw.githubusercontent.com/iamswap/cftunnel/main/cftunnel -o cftunnel
chmod +x cftunnel
# Install globally (optional)
sudo mv cftunnel /usr/local/bin/git clone https://github.com/iamswap/cftunnel.git
cd cftunnel
chmod +x cftunnel
# Install globally (optional)
./cftunnel install-
Authenticate with Cloudflare:
cloudflared login
This opens your browser to authenticate with your Cloudflare account.
-
Verify installation:
cftunnel help
-
Navigate to your Laravel project:
cd /path/to/your/laravel/project -
Share your site:
cftunnel share myapp.com
-
Your site is now live at
https://myapp.com🎉
# Basic sharing
cftunnel share example.com
# With HTTPS (requires Herd secure)
cftunnel share example.com --securecftunnel listcftunnel remove example.comcftunnel cleanup example.com# Share different projects on different domains
cd ~/Sites/project1
cftunnel share project1.yourdomain.com
cd ~/Sites/project2
cftunnel share project2.yourdomain.com
# List all active tunnels
cftunnel list# First secure your site with Herd
herd secure myapp
# Then share with HTTPS
cftunnel share myapp.com --secure# Start your development session
cd ~/Sites/my-laravel-app
cftunnel share staging.mycompany.com
# Your site is now accessible at https://staging.mycompany.com
# Share this URL with clients, team members, or for testing
# When done, stop with Ctrl+C
# The tunnel configuration is saved for next time- Tunnel Creation: Creates a Cloudflare tunnel for your domain
- DNS Configuration: Automatically sets up DNS routing through Cloudflare
- Herd Integration: Links your domain with Laravel Herd's local server
- Configuration Persistence: Saves tunnel information for reuse
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Your Domain │───▶│ Cloudflare Tunnel │───▶│ Laravel Herd │
│ (example.com) │ │ │ │ (example.test) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
- macOS/Linux:
~/.cftunnel/config.json
{
"tunnels": {
"example.com": {
"id": "12345678-1234-1234-1234-123456789abc",
"name": "herd-example-com"
}
}
}Individual tunnel configurations are stored in:
~/.cloudflared/config-{domain}.yml
Install cloudflared using the installation instructions above.
Download and install Laravel Herd from herd.laravel.com.
- Ensure your domain is managed by Cloudflare
- Check that you're authenticated:
cloudflared login - Verify Herd is running:
herd status
- Check your Cloudflare authentication:
cloudflared login - Ensure you have permission to create tunnels
- Try cleaning up:
cftunnel cleanup yourdomain.com
This is usually harmless - cftunnel will use the existing route.
For detailed output, you can modify the script to add debugging:
# Add to the top of the script after set -e
set -x # Enable debug mode- Check the help:
cftunnel help - Verify dependencies:
cftunnelwill check and report missing requirements - Check Cloudflare tunnel status:
cloudflared tunnel list - Check Herd status:
herd status
We welcome contributions! Here's how you can help:
- Fork the repository
- Clone your fork:
git clone https://github.com/iamswap/cftunnel.git - Make your changes
- Test thoroughly with different scenarios
- Submit a pull request
Since this is a Bash script, testing involves:
- Testing with different domain configurations
- Verifying tunnel creation and cleanup
- Testing error conditions and recovery
- Checking integration with Herd and Cloudflare
- Follow existing code patterns
- Use meaningful function and variable names
- Add comments for complex logic
- Maintain backward compatibility
- Tunnel Access: Only you control the tunnel through your Cloudflare account
- Domain Ownership: Requires domain ownership and Cloudflare management
- Local Access: Tunnels only expose what Herd already serves locally
- Credentials: Uses Cloudflare's secure authentication flow
This project is licensed under the MIT License - see the LICENSE file for details.
- Initial release
- Basic tunnel creation and management
- Laravel Herd integration
- DNS route automation
- Configuration persistence
- Cloudflare for the amazing tunnel technology
- Laravel Herd for simplifying local PHP development
- The open source community for inspiration and feedback
- 📖 Documentation: Check this README and
cftunnel help - 🐛 Bug Reports: Open an issue
- 💬 Discussions: GitHub Discussions
- 🚀 Feature Requests: Request a feature
Made with ❤️ for the Laravel and PHP community.