cftunn

cftunn

Zero-config Cloudflare Tunnels for Developers.
Expose localhost to the world in seconds with a custom domain.

cftunn is a lightweight CLI tool that automates the creation of Cloudflare Tunnels. It abstracts away the complexity of creating tunnels, routing DNS, and configuring ingress rules into a single command.

Designed for developers who want the ease of ngrok but with their own custom domains and the security/performance of Cloudflare.

✨ Features

• One-Command Setup: No YAML configs, no UUID management. Just cftunn <port> <domain>.
• Automatic DNS: Automatically manages CNAME records for your domain.
• Smart Auth: seamlessly integrates with your existing cloudflared login or API tokens.
• Self-Healing: Automatically cleans up or rotates credentials for existing named tunnels to ensure a successful connection.
• Safe: Prompts for confirmation before overwriting existing DNS records.
• Cross-Platform: Works on macOS and Linux.

🚀 Installation

Automatic (Recommended)

Install the latest binary for your OS/Arch:

curl -fsSL https://raw.githubusercontent.com/thatjuan/cftunn/main/install.sh | bash

From Source

You need Go 1.20+ installed.

go install github.com/thatjuan/cftunn@latest

Or clone the repo:

git clone https://github.com/thatjuan/cftunn.git
cd cftunn
make install

🔄 Updating

To update to the latest version, simply run the installation command again.

Automatic:

curl -fsSL https://raw.githubusercontent.com/thatjuan/cftunn/main/install.sh | bash

From Source:

go install github.com/thatjuan/cftunn@latest

Prerequisites

1. cloudflared
This tool relies on the official Cloudflare Tunnel daemon.

• macOS: brew install cloudflared
• Linux: Installation Instructions

2. Authentication
You need to be authenticated with Cloudflare.

• Method A: Interactive Login (Recommended)
  Run this once to authorize your machine:

  cloudflared tunnel login
  

  This will open your browser and generate a cert.pem file.

• Method B: API Token (CI/CD friendly)
  Set the environment variable:

  export CLOUDFLARE_API_TOKEN=your_api_token
  

  Required Permissions: Zone:DNS:Edit, Account:Cloudflare Tunnel:Edit.

📖 Usage

Basic Example

Expose your local server running on port 3000 to dev.example.com:

cftunn 3000 dev.example.com

Advanced Usage

Tunnel to a specific host (e.g., a container or VM):

cftunn 8080 dev.example.com --host 192.168.1.100

What happens next?

1. cftunn checks for the tunnel cftunn-dev-example-com.
2. If it doesn't exist, it creates it.
3. It checks if dev.example.com exists in your DNS.
4. It routes the tunnel to that hostname (prompting if it needs to overwrite).
5. It starts the tunnel, forwarding traffic to localhost:3000.

Flags

Usage:
  cftunn [PORT] [DOMAIN] [flags]

Flags:
  -D, --debug           Enable debug output for troubleshooting
  -d, --domain string   Domain to expose (e.g. dev.example.com)
  -h, --help            help for cftunn
  -H, --host string     Target host to tunnel to (default: localhost)
  -p, --port int        Local port to tunnel to
  -v, --version         version for cftunn

Troubleshooting

If you encounter issues during tunnel setup, use the --debug flag to get detailed output:

cftunn 3000 dev.example.com --debug

This will show:

• Authentication method detection (API token vs cert.pem)
• cloudflared commands being executed
• API calls and responses
• Zone and DNS record lookups
• Tunnel creation/deletion operations

🛠️ Development & Contributing

We welcome contributions!

Setup

1. Fork the repository.
2. Clone your fork:

   git clone https://github.com/thatjuan/cftunn.git
   cd cftunn
   

3. Install dependencies:

   go mod tidy
   

Building

Use the included Makefile:

make build
# Output binary is ./cftunn

Testing

Currently, manual testing is required due to the integration nature of the tool (requires real Cloudflare API).

• Mocking: Future improvements should include interfaces for the Cloudflare API to allow unit testing.

Reporting Bugs

Please open an issue on GitHub with:

1. Your OS version.
2. The command you ran.
3. The error output (redacted of any tokens/secrets).
4. Output of cloudflared --version.

📄 License

MIT License. See LICENSE for details.

Disclaimer

This is a community project and is not affiliated with Cloudflare. Use it at your own risk.