---
name: public-endpoints-and-provider-integrations
description: "Use when making a local app or agent reachable by external providers: public HTTPS tunnels/domains, webhook reachability, DNS/email aliases for account setup, Twilio voice bridges, and provider-side verification/debugging. Consolidates Cloudflare Tunnel, branded-domain DNS/email, and telephony webhook bridge workflows."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [devops, public-endpoints, webhooks, cloudflare, dns, email, twilio, tunnels]
    related_skills: [webhook-subscriptions, nextjs-local-dev-troubleshooting]
---

# Public Endpoints and Provider Integrations

## Overview

External SaaS providers usually need one or more public-facing integration surfaces before they can work with a local prototype or Hermes-backed service:

- A public HTTPS URL that routes to a local service or webhook.
- DNS records for branded domains, forwarding aliases, or provider verification.
- Provider-side webhook configuration, logs, and verification events.
- Optional media/telephony surfaces such as Twilio voice webhooks and public audio URLs.

Use this umbrella before creating another one-session skill for a specific tunnel, DNS record, phone bridge, verification inbox, or provider callback bug. Put session-specific recipes under `references/`; put reusable probe scripts under `scripts/`; put provider config starters under `templates/`.

## When to Use

Use when the user asks to:

- Expose a local app, dashboard, API, webhook endpoint, or prototype publicly.
- Install, locate, inspect, run, or troubleshoot `cloudflared` / Cloudflare Tunnel.
- Configure a stable domain, DNS route, or quick `trycloudflare.com` URL for a provider callback.
- Create or troubleshoot branded domain email aliases for signup/verification flows.
- Check domain availability, registrar state, DNS records, MX/TXT forwarding, or Google Cloud Domains registration.
- Build or debug a phone-call agent bridge using Twilio, speech gathering, Hermes/LLM backends, tunnels, and external TTS.
- Diagnose “provider says webhook failed,” “call connects but silence,” “verification email did not arrive,” or “public URL reaches the wrong service.”

Do not use as a generic app-debugging skill after public reachability is proven. Hand off to the application/framework skill once local service behavior, public routing, and provider delivery have been separated.

## Integration Surface Map

Before changing anything, classify the job:

| Surface | Typical need | Source of truth | Fast verification |
| --- | --- | --- | --- |
| Local service | App must listen on a local port/path | process logs, `curl 127.0.0.1:<port>` | GET/POST local health endpoint |
| Public tunnel/domain | Provider needs public HTTPS | tunnel process/config, DNS, reverse proxy | `curl -i https://host/path` |
| Provider webhook | Provider must call the right URL/method | provider dashboard/API/logs | provider test event + local logs |
| DNS/email | Domain alias or verification records | registrar/DNS provider API + public DNS | `dig MX/TXT`, test email |
| Telephony/media | Twilio voice/audio callbacks | Twilio number config + call notifications | public TwiML/audio URL + call logs |

## Cloudflare Tunnel / Public HTTPS Workflow

### Quick tunnel

For temporary demos and webhook tests:

```bash
mkdir -p /opt/mrhan/logs
cloudflared tunnel \
  --url http://127.0.0.1:<port> \
  --loglevel info \
  --logfile /opt/mrhan/logs/<purpose>-cloudflared.log
```

Quick tunnels may have no config directory. The process output/log is the source of truth and should contain a `https://*.trycloudflare.com` URL.

### Discovery before answering status/location questions

```bash
set -e
printf 'which cloudflared: '; command -v cloudflared || true
printf '\ncloudflared version:\n'; cloudflared --version 2>/dev/null || true
printf '\npackage candidates:\n'; dpkg -l | grep -i cloudflared || true; snap list 2>/dev/null | grep -i cloudflared || true
printf '\nsystemd units:\n'; systemctl list-unit-files | grep -i cloudflared || true
printf '\nrunning processes:\n'; ps aux | grep -i '[c]loudflared' || true
printf '\nconfig dirs/files:\n'; for d in /etc/cloudflared ~/.cloudflared /usr/local/etc/cloudflared; do [ -e "$d" ] && printf '%s\n' "$d" && find "$d" -maxdepth 2 -type f -printf '  %p\n' 2>/dev/null; done
```

Answer simple user questions directly: what `cloudflared` is, where it is installed, version, whether it is running, and what URL/config/logs exist. Do not bury this under unrelated pending setup work.

### Stable named tunnel checklist

1. Confirm the user wants account/domain-backed stability.
2. `cloudflared tunnel login`
3. `cloudflared tunnel create <name>`
4. `cloudflared tunnel route dns <name> <subdomain.example.com>`
5. Configure `/etc/cloudflared/config.yml` with ingress rules.
6. `sudo cloudflared service install && sudo systemctl enable --now cloudflared`
7. Verify local service, public URL, DNS, and logs.

## DNS, Domain, and Branded Email Workflow

Use DNS/email setup when the task is about domain records, verification aliases, or account signup inboxes. `cloudflared` does not create email addresses and does not control registrar DNS unless Cloudflare is the authoritative DNS provider and the Cloudflare API is being used.

### Domain availability and purchase checks

- Check registry state with RDAP/WHOIS before trusting landing pages or registrar UI.
- Do not confuse expired hosting, parking, or HTTP 404 with an available domain.
- Report registrar, status, expiry, and nameservers when present.
- Do not purchase until the user confirms exact domain, registrar/account, price, privacy/contact handling, terms, and billing/payment scope.
- For Google Cloud Domains, use authenticated `gcloud`; `--no-launch-browser` codes are bound to the live login process that generated the URL.

### DNS-only forwarding aliases

For quick inbound-only verification addresses:

```text
MX @ mx1.forwardemail.net priority 10
MX @ mx2.forwardemail.net priority 10
TXT @ forward-email=hello:destination@example.net
```

Adapt provider syntax as needed. This creates forwarding, not a real login-able mailbox and not outbound sending reputation.

### Verification layers

Always verify both:

```bash
# Control plane: registrar/provider API readback
# Data plane: public DNS
dig +short MX example.com
dig +short TXT example.com
```

If control plane is correct but public DNS lags, schedule a short re-check rather than repeatedly polling manually.

## Telephony Agent Bridge Workflow

A phone-call agent bridge is a provider webhook integration with voice-specific latency and media constraints.

Core path:

1. Select/provision a voice-capable Twilio number.
2. Expose a public HTTPS app endpoint via stable domain or tunnel.
3. Configure incoming voice webhook: `https://<public-host>/voice`, method `POST`.
4. `/voice` returns TwiML with `<Gather input="speech" action="/respond" method="POST">`.
5. `/respond` reads `SpeechResult`, calls Hermes/LLM backend, returns short audio/TwiML, and loops.
6. Use short phone answers; phone latency and turn-taking punish long responses.
7. Restrict tools in live-call mode unless the user explicitly wants actions during calls.

### Twilio trial and call-debug pitfalls

- Trial accounts may inject a disclaimer and restrict calls.
- `21219`: outbound destination is not a verified caller ID.
- `21264`: inbound caller's `From` number is not verified.
- `10002`: API verification calls may be blocked on trial accounts.
- Query `OutgoingCallerIds` when a number “looks verified” but Twilio blocks it; friendly name may not match the canonical stored phone number.

### External TTS and public audio

For better voice quality, generate/cache MP3 and return `<Play>https://<public-host>/audio/<hash>.mp3</Play>`. Implement `HEAD` on audio URLs; Twilio/CDNs may probe with `HEAD`, and a `501` can cause silence even when GET works.

## End-to-End Verification Sequence

Use this sequence before telling the user an integration is live:

1. **Local service:** `curl -i --max-time 10 http://127.0.0.1:<port>/<path>`.
2. **Public route:** `curl -i --max-time 20 https://<host>/<path>`.
3. **Method/path match:** test the exact provider method (`POST`, body, headers) where possible.
4. **Provider config:** read back the webhook/DNS/number/account setting from the provider API or dashboard.
5. **Provider event logs:** inspect recent deliveries/calls/notifications for hidden errors.
6. **Public DNS/email:** verify `dig` results and send/receive a test message when the task is email.
7. **Media URLs:** test both `HEAD` and `GET` for audio/file URLs used in Twilio or similar providers.

A `501 Unsupported method ('HEAD')` from a simple local Python server can still prove routing reached the service. Retry with GET or implement HEAD when the provider needs it.

## Security Rules

- Never persist registrar API keys, Cloudflare tokens, Twilio Auth Tokens, TTS keys, or mailbox credentials in skills, references, memory, screenshots, logs, or final replies.
- Use environment variables or approved secret stores for scripts.
- Redact pasted secrets as `[REDACTED]` in durable artifacts.
- Tell the user to rotate/revoke credentials that were pasted into chat or exposed in screenshots.
- Stop at legitimate verification boundaries: CAPTCHA, phone checks, anti-abuse gates, or human mailbox confirmation may require user action.

## Support Files

This umbrella is intended to hold absorbed narrow details as support files:

- `references/cloudflare-tunnels-original.md` — absorbed Cloudflare Tunnel installation, quick/named tunnel, logging, and reachability guidance.
- `references/domain-email-dns-setup-original.md` — absorbed branded-domain DNS/email, registrar, forwarding, Google Cloud Domains, and signup-alias guidance.
- `references/telephony-agent-bridges-original.md` — absorbed Twilio/Hermes phone bridge, external TTS, and low-latency call-debug guidance.

## Common Pitfalls

1. **Debugging the app before proving routing.** First separate local app, public route, provider configuration, and provider logs.
2. **Using `curl -I` only.** Some servers lack HEAD; retry with GET. Conversely, providers like Twilio may require HEAD for media URLs, so implement it when needed.
3. **Confusing tunnel, DNS, and email responsibilities.** Tunnels expose HTTP services; DNS controls names and mail routing; email providers deliver messages.
4. **Stopping at control-plane success.** A dashboard save, registrar API 200, or tunnel-start log is not enough. Verify the data plane.
5. **Forgetting provider-side logs.** Twilio notifications, webhook delivery attempts, and DNS/provider diagnostics often reveal errors absent from the local app.
6. **Overusing quick tunnels for recurring workflows.** Quick URLs change. Use named tunnels or stable HTTPS domains for anything the user expects to reuse.
7. **Persisting secrets in durable artifacts.** Sanitized commands and non-secret paths belong in references; tokens do not.

## Verification Checklist

- [ ] Integration surface classified: tunnel/domain/webhook/email/telephony/media.
- [ ] Local service health and exact path/method verified.
- [ ] Public URL or DNS record verified from outside the app.
- [ ] Provider setting read back and matches the public URL/record.
- [ ] Provider logs/events checked for delivery/call/signature errors.
- [ ] Email aliases verified with public MX/TXT and, where possible, a received test message.
- [ ] Telephony audio/TwiML URLs tested with appropriate HEAD/GET methods.
- [ ] Secrets were not written to durable artifacts and user was warned to rotate exposed credentials.