domain-mask

Mask a URL behind a custom domain for demos and recordings. Opens an HTTPS reverse proxy so the browser address bar shows a clean domain (e.g., wknd.adventures) while content is served from the real URL (e.g., https://main--mysite--org.aem.page). Trusted certificate via mkcert — no browser warnings.

Prerequisites

Node 22+
mkcert (brew install mkcert && mkcert -install)
sudo access (for port 443 and /etc/hosts)

Script Location

if [[ -n "${CLAUDE_SKILL_DIR:-}" ]]; then
  DOMAIN_MASK="${CLAUDE_SKILL_DIR}/scripts/domain-mask.mjs"
else
  DOMAIN_MASK="$(find ~/.claude -path "*/domain-mask/scripts/domain-mask.mjs" \
    -type f 2>/dev/null | head -1)"
fi
if [[ -z "$DOMAIN_MASK" || ! -f "$DOMAIN_MASK" ]]; then
  echo "Error: domain-mask.mjs not found." >&2
fi

Workflow

Step 1: Gather inputs

Ask the user for two values (or extract from their message):

Display domain — the domain to show in the browser (e.g., wknd.adventures)
Target URL — the real URL to proxy (e.g., https://gabrielwalt.github.io)

Step 2: Check prerequisites

which mkcert || echo "Install mkcert: brew install mkcert && mkcert -install"

If mkcert is missing, tell the user to install it and run mkcert -install once to set up the local CA.

Step 3: Start the proxy

sudo node "$DOMAIN_MASK" <display-domain> <target-url>

The script handles everything automatically:

Adds 127.0.0.1 <display-domain> to /etc/hosts
Generates a trusted HTTPS certificate via mkcert
Starts an HTTPS reverse proxy on port 443
Prints the URL to open

Tell the user:

Open https://<display-domain> in their browser
The address bar will show the display domain with a green padlock
Press Ctrl+C when done — the script removes the hosts entry and cleans up temp certs automatically

Step 4: Confirm cleanup

After the user stops the proxy, verify cleanup succeeded by checking the script output. If it reports a warning about /etc/hosts cleanup, help the user remove the entry manually:

sudo sed -i '' '/<display-domain>/d' /etc/hosts

Limitations

macOS only (/etc/hosts path, brew install mkcert)
Requires sudo (privileged port 443 + hosts file)
One display domain per invocation
Does not rewrite URLs inside HTML/CSS/JS response bodies