← Back to Setup Guide

Cloudflare Setup

Secure remote access to reattachd using Cloudflare Tunnel and Access.

Prerequisites: A Cloudflare account and a domain managed by Cloudflare.

Overview

This guide covers two components:

  1. Cloudflare Tunnel - Securely expose reattachd to the internet without opening ports
  2. Cloudflare Access - Add authentication to protect your tunnel with Service Tokens

Install cloudflared

1 Install cloudflared

macOS

brew install cloudflared

Linux

# Debian/Ubuntu
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Other distributions
# See https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/

Quick Start (for testing)

If you just want to quickly test remote access without setting up a domain, you can use Quick Tunnel:

cloudflared tunnel --url http://localhost:8787

This will generate a temporary URL like https://xxxx-xxxx-xxxx.trycloudflare.com.

Note: Quick Tunnel is for testing only. The URL changes every time you restart the command, so you'll need to re-scan the QR code each time. For permanent setup with your own domain, continue below.

Permanent Setup with Custom Domain

2 Authenticate with Cloudflare 
cloudflared tunnel login

This opens a browser to authenticate and authorize cloudflared for your Cloudflare account.

3 Create a tunnel 
cloudflared tunnel create reattach

This creates a tunnel and generates a credentials file at ~/.cloudflared/<TUNNEL_ID>.json.

4 Configure the tunnel

Create or edit ~/.cloudflared/config.yml:

tunnel: reattach
credentials-file: /Users/YOUR_USERNAME/.cloudflared/TUNNEL_ID.json

ingress:
  - hostname: reattach.your-domain.com
    service: http://localhost:8787
  - service: http_status:404

Replace YOUR_USERNAME, TUNNEL_ID, and your-domain.com with your values.

5 Create DNS record 
cloudflared tunnel route dns reattach reattach.your-domain.com

This creates a CNAME record pointing to your tunnel.

6 Run the tunnel

Test the tunnel:

cloudflared tunnel run reattach

Run as a service (macOS)

sudo cloudflared service install
sudo launchctl start com.cloudflare.cloudflared

Run as a service (Linux)

sudo cloudflared service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

Part 2: Cloudflare Access with Service Token

Cloudflare Access adds authentication to your tunnel. Service Tokens allow the Reattach iOS app to authenticate without interactive login.

1 Create an Access Application
  1. Go to Cloudflare Zero Trust Dashboard
  2. Navigate to Access → Applications
  3. Click Add an application
  4. Select Self-hosted
  5. Configure the application:
    • Application name: Reattach
    • Session duration: 24 hours (or your preference)
    • Application domain: reattach.your-domain.com
2 Create a Service Token
  1. In the Zero Trust Dashboard, go to Access → Service Auth
  2. Click Create Service Token
  3. Enter a name (e.g., "Reattach iOS")
  4. Set token duration (e.g., 1 year)
  5. Click Generate token

Important: Copy both CF-Access-Client-Id and CF-Access-Client-Secret immediately. The secret is only shown once!

You will get two values:

CF-Access-Client-Id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.access
CF-Access-Client-Secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3 Create Access Policy
  1. Go back to your Reattach application in Access → Applications
  2. Click on the application to edit it
  3. Go to the Policies tab
  4. Add a policy:
    • Policy name: Service Token Access
    • Action: Service Auth
    • Include: Service Token → Select your token
  5. Save the policy
4 Configure the iOS App

In the Reattach iOS app:

  1. Go to server settings
  2. Enter your Service Token credentials:
    • Client ID: Your CF-Access-Client-Id
    • Client Secret: Your CF-Access-Client-Secret
  3. Save the settings

The app will automatically include these headers in all API requests.

Verification

Test that everything is working:

# Test without authentication (should fail with 403)
curl https://reattach.your-domain.com/sessions

# Test with Service Token (should return session list)
curl -H "CF-Access-Client-Id: YOUR_CLIENT_ID" \
     -H "CF-Access-Client-Secret: YOUR_CLIENT_SECRET" \
     https://reattach.your-domain.com/sessions

Need help? Check out the GitHub repository for more details and troubleshooting.