DEV Community

Doni Leong
Doni Leong

Posted on Edited on

Cutting the Cord: Wireless iOS Testing with Cloudflare Tunnel

Testing iOS builds on physical hardware often means hunting down a USB cable and staying tethered to a desk. While Xcode supports wireless deployment, it frequently drops connection or requires pairing hurdles across mixed Wi-Fi setups.

Years ago, enterprise teams commonly distributed internal builds using Apple's Over-The-Air (OTA) deployment protocol (itms-services://). By combining xcodebuild, a lightweight Python server, and Cloudflare Quick Tunnels, you can set up a one-click wireless install flow directly from your terminal to your personal iPhone.

Here is how the architecture works and how to set it up.


How OTA Deployment Works on iOS

When Safari encounters a link structured like this:

<a href="itms-services://?action=download-manifest&url=https://your-domain.com/manifest.plist">
  Install App
</a>
Enter fullscreen mode Exit fullscreen mode

iOS triggers an automated system prompt asking to install the app. Under the hood, iOS performs three steps:

  1. Downloads and parses manifest.plist.
  2. Fetches the .ipa binary referenced inside the manifest.
  3. Validates the code signature against the provisioning profile embedded in the .ipa.

There are two strict platform requirements:

  • HTTPS Enforcement: iOS strictly requires the manifest URL and .ipa download link to be served over valid, trusted HTTPS. Local IP addresses (http://192.168.x.x) fail automatically.
  • Code Signing Scope: For personal testing on a free Apple ID, your physical iPhone's UDID must already be registered in the provisioning profile, and the certificate carries a 7-day lifespan.

Why Cloudflare Quick Tunnel?

To serve the build files over valid HTTPS locally without configuring custom SSL certificates or purchasing a domain, tunneling tools are ideal.

While ngrok is a standard choice, its free tier serves an HTML interstitial warning screen before proxying requests. Safari's background OTA installer cannot bypass this warning, causing silent download failures.

Cloudflare Quick Tunnel solves this cleanly:

  • Zero registration or auth tokens needed.
  • Spun up instantly via cloudflared tunnel --url http://localhost:8000.
  • Serves a direct HTTPS URL on *.trycloudflare.com without warning interstitials or payload throttling.

Architecture Overview

[ Mac Terminal: ./build-and-deploy.sh ]
       |
       |-- 1. Compiles .app via xcodebuild (Personal Development Team)
       |-- 2. Packages into Payload/ and zips into app.ipa
       |-- 3. Starts local Python HTTP server on port 8000
       |-- 4. Spins up Cloudflare Quick Tunnel
       |
       v
[ Cloudflare Quick Tunnel (HTTPS) ]
       ^
       | (Direct itms-services:// URL)
       v
[ iPhone: Safari / iMessage ]
       |
       |-- Reads manifest.plist over HTTPS
       |-- Installs app directly to Home Screen
Enter fullscreen mode Exit fullscreen mode

Step 1: Building and Packaging the IPA

Using xcodebuild, compile the app targeting generic iOS devices:

#!/usr/bin/env bash
set -euo pipefail

SCHEME="YourAppScheme"
BUILD_DIR="./build"
IPA_DIR="./dist"

# Clean build directory
rm -rf "$BUILD_DIR" "$IPA_DIR"
mkdir -p "$IPA_DIR/Payload"

# Build archive
xcodebuild \
  -scheme "$SCHEME" \
  -configuration Debug \
  -destination 'generic/platform=iOS' \
  -derivedDataPath "$BUILD_DIR" \
  build

# Locate .app bundle and package into IPA
APP_PATH=$(find "$BUILD_DIR/Build/Products/Debug-iphoneos" -name "*.app" -maxdepth 1)
cp -R "$APP_PATH" "$IPA_DIR/Payload/"
cd "$IPA_DIR" && zip -qr "app.ipa" Payload && cd ..
Enter fullscreen mode Exit fullscreen mode

Step 2: Generating the OTA Manifest and Landing Page

Next, create the manifest.plist pointing to your tunnel URL, along with a minimal HTML page for one-tap installation:

import sys

def generate_manifest(tunnel_url: str, bundle_id: str, app_title: str):
    plist_content = f"""<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>items</key>
    <array>
        <dict>
            <key>assets</key>
            <array>
                <dict>
                    <key>kind</key>
                    <string>software-package</string>
                    <key>url</key>
                    <string>{tunnel_url}/app.ipa</string>
                </dict>
            </array>
            <key>metadata</key>
            <dict>
                <key>bundle-identifier</key>
                <string>{bundle_id}</string>
                <key>bundle-version</key>
                <string>1.0.0</string>
                <key>kind</key>
                <string>software</string>
                <key>title</key>
                <string>{app_title}</string>
            </dict>
        </dict>
    </array>
</dict>
</plist>"""
    with open("dist/manifest.plist", "w") as f:
        f.write(plist_content)

    html_content = f"""<!DOCTYPE html>
<html>
<head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Install {app_title}</title>
    <style>
        body {{ font-family: -apple-system, sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f2f2f7; }}
        a {{ background: #007aff; color: white; padding: 16px 28px; border-radius: 12px; text-decoration: none; font-weight: bold; font-size: 18px; }}
    </style>
</head>
<body>
    <a href="itms-services://?action=download-manifest&url={tunnel_url}/manifest.plist">Install {app_title}</a>
</body>
</html>"""
    with open("dist/index.html", "w") as f:
        f.write(html_content)
Enter fullscreen mode Exit fullscreen mode

Step 3: Serving via Cloudflare Quick Tunnel

Run a local Python web server from your distribution folder and expose it using cloudflared:

# Start background HTTP server
cd dist && python3 -m http.server 8000 &
SERVER_PID=$!

# Spin up Cloudflare Tunnel and capture public URL
cloudflared tunnel --url http://localhost:8000 2>&1 | tee tunnel.log &
TUNNEL_PID=$!

# Wait for tunnel domain to appear
sleep 3
PUBLIC_URL=$(grep -o 'https://[a-zA-Z0-9-]*\.trycloudflare\.com' tunnel.log | head -n 1)

echo "Live Install URL: $PUBLIC_URL"
Enter fullscreen mode Exit fullscreen mode

Step 4: Optional Automation (Push Link to Device)

To eliminate manual typing, you can send the URL directly to your phone via macOS AppleScript through iMessage:

osascript -e "tell application \"Messages\" to send \"$PUBLIC_URL\" to buddy \"your-phone-or-appleid@icloud.com\""
Enter fullscreen mode Exit fullscreen mode

When the message arrives, tap the link in Safari, tap Install, and the fresh build downloads directly onto your home screen.


Trusting the Profile on First Run

If you are using a free Apple ID personal development certificate, iOS requires trusting the certificate on the initial install:

  1. Go to Settings > General > VPN & Device Management.
  2. Tap your Apple ID under Developer App.
  3. Tap Trust.

Subsequent builds with the same certificate update seamlessly without repeating this step.


Practical Trade-Offs

  • 7-Day Expiry: Personal team profiles remain subject to the standard 7-day expiration limit.
  • Pre-registered Devices: This is not a public distribution channel. The target device UDID must already be associated with your Xcode provisioning profile.
  • Development Convenience: For quick day-to-day iterations away from your desk, it completely removes the need to plug in a USB cable or troubleshoot Xcode wireless device drops.

Top comments (2)

Collapse
 
krusenas profile image
Karolis •

Quick tunnels hand out a new random hostname every restart, so the manifest link in an old message goes dead. I built Webhook Relay, and its HTTP tunnel can expose your local OTA server so that link stops changing.

Collapse
 
doni_leong profile image
Doni Leong •

Good point on the random URLs! For my workflow, it's strictly an on-demand, fire-and-forget install right after a build finishes, so a short-lived URL actually works well without having to maintain a fixed endpoint.

If someone does need a persistent URL, setting up a named Cloudflare Tunnel with a custom domain works nicely too. Thanks for sharing your tool!