k3d on mac "timed out waiting for cluster to start" | wrong hostname to connect to cluster

Waiting 5m for Kubernetes cluster "k3d-k3s-default" to start...
timed out waiting for cluster to start: Get "https://host.docker.internal:49730/version": context deadline exceeded

When trying to start a k3d cluster on mac, ctlptl fails to detect cluster is online because it's using the docker internal name for the host machine (host.docker.internal), not the machine hostname outside of docker (localhost).

Steps to Reproduce

Install k3d and ctlptl

# https://k3d.io/v5.4.3/#installation
curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash
brew install tilt-dev/tap/ctlptl

ctlptl-k3d.yml

apiVersion: ctlptl.dev/v1alpha1
kind: Cluster
product: k3d
registry: ctlptl-k3d-registry
---
apiVersion: ctlptl.dev/v1alpha1
kind: Registry
name: ctlptl-k3d-registry
port: 5000

apply cluster config

ctlptl apply -f ctlptl-k3d.yml

after 5 minute timeout we get an error

...
INFO[0016] Cluster 'k3s-default' created successfully!  
INFO[0016] You can now use it like this:                
kubectl cluster-info
Switched to context "k3d-k3s-default".
Waiting 5m for Kubernetes cluster "k3d-k3s-default" to start...
timed out waiting for cluster to start: Get "https://host.docker.internal:49730/version": context deadline exceeded

However, the k8s controller is available at https://localhost:49730/version

Temporary FIx

add host.docker.internal to /etc/hosts

sudo echo "127.0.0.1  host.docker.internal" | sudo tee -a  /etc/hosts

apply command now works fully

...
INFO[0016] Cluster 'k3s-default' created successfully!  
INFO[0016] You can now use it like this:                
kubectl cluster-info
Switched to context "k3d-k3s-default".
cluster.ctlptl.dev/k3d-k3s-default created

Start with the ctlptl apply -f ctlptl-k3d.yml flow and the k3d cluster startup check described in the report. Trace how the Kubernetes endpoint is selected on macOS, then verify that the check reaches https://localhost:49730/version without requiring an /etc/hosts workaround and that the apply command completes successfully.