feat: support permanent Cloudflare tunnels via custom domains

[woltspace]

Summary

• Adds three-tier tunnel detection in container/entrypoint.sh: managed tunnel (permanent domain) when CF_TUNNEL_TOKEN is set, otherwise falls back to ephemeral quick tunnel (current behavior)
• Adds /setup-tunnel skill that walks users through the entire Cloudflare setup interactively
• Zero regression — no env vars set = exact same behavior as before

How to set up a permanent domain (beginner guide)

What you need

• A free Cloudflare account
• A domain on Cloudflare (buy one there ~$10/yr, or transfer existing DNS)

Steps

1. Go to the Cloudflare Zero Trust dashboard: https://one.dash.cloudflare.com/
2. Navigate to Networks → Tunnels → Create a tunnel
3. Choose Cloudflared as the connector type
4. Name it whatever you want (e.g. your wolt's name)
5. On the "Install connector" page — don't install anything. Just copy the token — it's the long eyJ... string after --token in the install command they show you
6. Click next. On Route tunnel → Add a public hostname:
   • Subdomain: whatever you want (e.g. nw)
   • Domain: pick your Cloudflare domain from the dropdown
   • Service type: HTTP
   • URL: localhost:3000
7. Save the tunnel
8. Add two lines to your wolt's .env:

   CF_TUNNEL_TOKEN=eyJ...your-token-here
   CF_TUNNEL_HOSTNAME=nw.yourdomain.com
   

9. Restart: woltspace restart
10. Visit https://nw.yourdomain.com — your wolt now has a permanent URL that survives restarts

Or just use the skill

Run /setup-tunnel inside any wolt session — it walks you through every step interactively and configures everything for you.

How it works

The entrypoint checks for CF_TUNNEL_TOKEN at startup:

• Token present → runs cloudflared tunnel run --token (permanent domain, URL written instantly)
• No token → runs cloudflared tunnel --url (ephemeral *.trycloudflare.com, current default)

Everything downstream (bot links, split view, CLI) reads .state/tunnel-url — no changes needed. The file just contains a stable URL instead of a random one.

Reverting to ephemeral

Remove or comment out CF_TUNNEL_TOKEN and CF_TUNNEL_HOSTNAME from .env, restart. Falls back automatically.

Test plan

• Start without CF_TUNNEL_TOKEN — verify ephemeral tunnel works as before
• Set CF_TUNNEL_TOKEN + CF_TUNNEL_HOSTNAME — verify permanent domain connects
• Check .state/tunnel-url contains the permanent hostname
• Verify bot session links use the permanent URL
• Remove the vars, restart — confirm fallback to ephemeral

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
woltspace	Ready	Preview, Comment	Mar 13, 2026 3:59am