app.userdomain.com

• User does manually (must, can't be automated): create Cloudflare account, buy/transfer domain to Cloudflare, create API Token.
• Agent does automatically (this skill): verify token, pick zone, create tunnel, configure ingress, create DNS, install + start

  cloudflared

  , verify the public URL works.

1. They register a Cloudflare account + add a domain (manual, ~5 min)
2. They create an API Token and give it to you securely (manual, ~2 min)
3. You build the tunnel + DNS + start it (automatic, ~1 min)
4. You test the URL together (automatic)

• Direct them to https://dash.cloudflare.com/sign-up to register
• Then https://dash.cloudflare.com/?to=/:account/domains to buy a domain (Cloudflare sells

  .com / .net / .org / .io / .dev / .app

  etc. at registry cost), OR add an existing domain and change nameservers
• Wait for them to confirm "domain is active in Cloudflare" before proceeding

https://dash.cloudflare.com/profile/api-tokens → Create Token → Create Custom Token

• Account → Cloudflare Tunnel → Edit
• Zone → DNS → Edit
• Zone → Zone → Read

python3 skills/cloudflare-tunnel-publish/scripts/verify.py

• Token validity
• The user's account_id (saves to

  workspace/.cf_state.json

  )
• All zones (domains) on the account

zone_id

zone_name

1. Subdomain (e.g.,

   app

   ,

   demo

   ,

   www

   ) → final hostname will be

   <sub>.<zone_name>

   . Apex domain (

   @

   ) is also allowed.
2. Local port (e.g.,

   8080

   ,

   3000

   ). If they say "my Starchild preview", run

   cat /data/previews.json 2>/dev/null

   to look up an existing preview's port; otherwise ask explicitly.

http://localhost:<port>

python3 skills/cloudflare-tunnel-publish/scripts/setup.py --hostname <full_hostname> --port <port>

setup.py

cloudflared

cloudflared

--new-tunnel

1. Reuse a healthy tunnel if one exists (or create one named

   starchild-<hostname>

   if none, or use

   --new-tunnel

   to force a new one)
2. Fetch the tunnel run token (a long base64 string used to start

   cloudflared

   )
3. PUT the ingress configuration: merge

   <hostname>

   →

   http://localhost:<port>

   into the existing ingress rules (preserving other hostnames), fallback

   404

4. Create a CNAME DNS record:

   <hostname>

   →

   <tunnel_id>.cfargotunnel.com

   , proxied = true
5. Append the site to the

   sites

   array in

   workspace/.cf_state.json

   (multi-site support — see "Multiple sites" below)

curl https://<hostname>

curl -sS "https://dns.google/resolve?name=<hostname>&type=A" | python3 -m json.tool

1. Status: 0

   + IPs in

   Answer

   → live. Now

   curl -I https://<hostname>

   should return 200/301/302. Show the user their URL. 🎉

2. Status: 3

   (NXDOMAIN) + Authority = TLD registry NS (e.g.

   ns.trs-dns.com

   ) → TLD registry hasn't propagated the new domain yet. Tell the user: configuration is 100% done, wait 30–60 min (newly registered domains can take up to 24 h), then retry. Don't keep polling — let them check on their own device.
3. Tunnel logs show errors (check

   bash_process(action='log', session_id=...)

   ) → real config bug. Common culprits: ingress not pointing at the right port, local service not running, wrong CNAME target.

• User says "my service is on my laptop, not in Starchild" → exact same flow, but Phase 7 must run on their laptop, not in this container. Give them the equivalent install command for their OS:
  • macOS:

    brew install cloudflared && cloudflared tunnel run --token <TOKEN>

  • Linux/Windows: link to https://github.com/cloudflare/cloudflared/releases/latest Send the run_token via

    request_env_input

    if needed, or just print it once and tell them to copy it (it's safe to share with their own machine, but never paste back to chat).
• User wants multiple subdomains → reuse the same tunnel; PUT a new ingress config that lists all hostnames; create one CNAME per hostname. This is now the default behavior — just run

  setup.py

  for each subdomain and it will merge into the existing tunnel's ingress.
• User wants to remove it → run

  python3 skills/cloudflare-tunnel-publish/scripts/teardown.py

  (deletes DNS + tunnel + kills the local cloudflared process).

• Cloudflare-Tunnel:Edit

  does NOT grant

  /accounts

  listing. Calling

  GET /accounts

  returns an empty list even with a valid token. Solution: derive

  account_id

  from any zone's embedded

  account.id

  field —

  verify.py

  already does this. Do NOT add

  Account:Account Settings:Read

  just to fix it; the zone trick is cleaner.
• The "run token" from

  GET /accounts/{id}/cfd_tunnel/{tunnel_id}/token

  is what

  cloudflared tunnel run --token

  consumes. Do not confuse with:
  • tunnel secret — only relevant for legacy locally-managed tunnels (we don't use)
  • API Token — used to call api.cloudflare.com

• The CNAME target must be

  <tunnel_id>.cfargotunnel.com

  , NOT the tunnel name.
• Remotely-managed tunnel (

  config_src: "cloudflare"

  ) routes via the API config endpoint, NOT a local

  config.yml

  . Do not generate one.
• Creating a tunnel via API requires a

  tunnel_secret

  field (32 random bytes, base64) even for

  config_src=cloudflare

  .

  setup.py

  generates one automatically.

ERR_SSL_VERSION_OR_CIPHER_MISMATCH

echo | timeout 10 openssl s_client -connect <hostname>:443 -servername <hostname> 2>&1 | grep -E "(handshake|peer certificate|Cipher is)"

• no peer certificate available

  +

  handshake failure

  → cert not issued yet ⏳
• Real cert returned → working ✅

• Established zones with prior certs: usually < 5 min
• Brand-new domains: 15 min ~ 24 h (DNS validation + CA signing + edge propagation)

1. Open

   dash.cloudflare.com → <domain> → SSL/TLS → Edge Certificates

2. Look for a row like

   *.<domain>, <domain>

   and check status:

   • Active

     → done, refresh browser

   • Pending Validation

     /

     Initializing

     → wait
3. Confirm

   SSL/TLS → Overview → Encryption mode

   is Full (not Flexible, not Full Strict). Tunnel always carries HTTPS to the origin, so Full is the right match.

• dig @1.1.1.1 yourdomain.com NS

  returns NXDOMAIN (Status=3)
• The Authority section shows the TLD's registry NS (e.g.,

  ns.trs-dns.com

  for

  .fun

  via Tucows), NOT Cloudflare's NS

• cloudflared

  tunnel is connected and healthy, but

  https://yourdomain.com

  returns DNS resolution failure

curl -sS "https://dns.google/resolve?name=hello.example.com&type=A" | python3 -m json.tool

• Status: 0

  +

  Answer

  array with IPs → working ✅

• Status: 3

  (NXDOMAIN) +

  Authority: ns.trs-dns.com

  (or similar registry NS) → TLD propagation pending ⏳

• Status: 0

  but no

  Answer

  → CNAME exists but Cloudflare orange-cloud not yet routing → wait 30s

cloudflared

https://yourdomain.com

scripts/keepalive.sh

keepalive.sh

hostname

port

app_cmd

app_dir

.cf_state.json

keepalive.sh

1. Probe the public URL (reachability, not just PID — a

   cloudflared

   process can be alive but disconnected).
2. Healthy → log one line, exit silently.
3. Down → diagnose: local app port closed → restart app (via

   app_cmd

   ) and tunnel; only the tunnel dead → restart just the tunnel. Then re-verify with a few retries (covers cold-start warm-up).
4. Report on state transitions only (tracked in

   run/keepalive.state

   ): newly-recovered or newly-failed prints one line; steady-state (healthy, or already-known-down) is silent. So a scheduled task pushes signal, never spam.

command

.cf_state.json

scheduled_task(action="schedule",
  schedule="every 2 minutes",
  command="cd /data/workspace && bash skills/cloudflare-tunnel-publish/scripts/keepalive.sh",
  title="cloudflare tunnel keepalive (all sites)")

• Use a relative command with

  cd /data/workspace &&

  . An absolute

  /data/workspace/...

  path can be normalized by the scheduler into a non-existent

  /data/skills/...

  (the

  workspace/

  segment gets dropped), so every run fails silently.

  cd

  + relative path is immune. (Confirmed in a real run.)
• Keep

  deliver

  at its default so the transition-only alerts actually reach the user. keepalive is already silent on healthy runs, so there's no spam to suppress — and a real outage should ping you.
• The interval may be normalized (e.g. "every 2 minutes" → 3 min) — fine.

• Free plan is enough. No upsell needed.
• Free plan only proxies ports 80/443 publicly — irrelevant to us, since the tunnel always exposes 443 to the world;

  localhost:<port>

  can be anything.

workspace/.cf_state.json

sites

{
  "account_id": "...",
  "zone_id": "...",
  "zone_name": "example.com",
  "sites": [
    {
      "hostname": "app.example.com",
      "port": 8080,
      "tunnel_id": "...",
      "tunnel_name": "starchild-app-example-com",
      "run_token": "...",
      "app_cmd": "python3 server.py",
      "app_dir": "/data/workspace/projects/myapp"
    },
    {
      "hostname": "blog.example.com",
      "port": 3000,
      "tunnel_id": "...",
      "run_token": "...",
      "app_cmd": "",
      "app_dir": ""
    }
  ],
  "hostname": "blog.example.com",
  "port": 3000,
  "tunnel_id": "...",
  "run_token": "...",
  "app_cmd": "",
  "app_dir": ""
}

keepalive.sh

sites[]

• its own keepalive, and only one was watched" bug: there is now exactly one keepalive process that knows about every configured site.

• setup.py

  defaults to reusing the first healthy tunnel it finds on the account. It merges the new hostname into the tunnel's existing ingress rules (preserving other hostnames) and points the DNS CNAME at that tunnel.

• .cf_state.json

  holds a

  sites[]

  array. Each

  setup.py

  run appends (or replaces) one entry.

  teardown.py

  removes one entry.

• keepalive.sh

  iterates

  sites[]

  and guards every site. One process, one watchdog, all hostnames. If a site shares a tunnel with another, the same

  cloudflared

  process serves both — keepalive won't start a second one.

cloudflared

sites[]