ngrokd

1. Create an ngrok API Key

1. Go to ngrok API dashboard
2. Click "New API Key"
3. Give it a description (e.g., "ngrokd daemon")
4. Copy the API key - you'll use it with ngrokctl set-api-key

The API key allows ngrokd to discover your bound endpoints and provision certificates.

2. Create Private Cloud Endpoints

1. Go to ngrok Endpoints dashboard
2. Click "New Endpoint" → "Cloud"
3. Choose "Kubernetes Operator" as the binding type
4. Configure your endpoint:
   • URL: identifier.subdomain (e.g., api.myapp)
   • Traffic Policy: Optional routing rules, auth, rate limiting
5. Click "Create Endpoint"

ngrokd automatically discovers these endpoints and creates local access points for them.

Virtual Mode (Default)

Each endpoint gets a unique IP address. Best for same-machine access.

net:
  listen_interface: "virtual"

Example:

• Endpoint 1: 127.0.0.2:80 (macOS) or 10.107.0.2:80 (Linux)
• Endpoint 2: 127.0.0.3:80
• Endpoint 3: 127.0.0.4:80

Network Mode - All Interfaces

Uses shared listeners with SNI/Host header routing. Multiple endpoints share the original port (80, 443). Built-in DNS server resolves hostnames for external clients (phones, VMs, CI). Best for cross-machine access.

net:
  listen_interface: "0.0.0.0"

Example:

• All HTTPS endpoints share 0.0.0.0:443 (routed by SNI)
• All HTTP endpoints share 0.0.0.0:80 (routed by Host header)
• DNS server at <LAN_IP>:53 resolves all managed hostnames
• External clients: set DNS to ngrokd machine's IP

Network Mode - Named Interface

Bind shared listeners to a specific network interface. Great for multi-homed servers.

net:
  listen_interface: "eth0"    # or "en0", "enp0s1", etc.

Example:

• Automatically resolves eth0 to its IP (e.g., 192.168.1.100)
• Shared listeners on 192.168.1.100:443, 192.168.1.100:80
• DNS server at 192.168.1.100:53

Network Mode - Specific IP

Bind shared listeners to a specific IP address.

net:
  listen_interface: "192.168.1.100"

1. Virtual Network Interface

Creates an interface with subnet for unique IP allocation:

• Linux: dummy interface ngrokd0 with 10.107.0.0/16 subnet
• macOS: loopback aliases on lo0 with 127.0.0.0/8 subnet

2. IP Allocation

Each discovered endpoint gets a unique IP:

10.107.0.2 → api.example.com
10.107.0.3 → web.example.com
10.107.0.4 → db.example.com

IP mappings persist across restarts in /etc/ngrokd/ip_mappings.json

3. DNS Management

Virtual mode: Updates /etc/hosts with unique IPs per endpoint:

# BEGIN ngrokd managed section
127.0.0.2    api.example.com
127.0.0.3    web.example.com
# END ngrokd managed section

Network mode: Runs a built-in DNS server that resolves all managed hostnames to the LAN IP. External clients point their DNS at the ngrokd machine. Per-domain routing configured automatically (macOS: /etc/resolver/, Linux: resolvectl or resolv.conf).

4. Traffic Forwarding

Virtual mode: Each endpoint has a dedicated listener on its unique IP:

App → Listener (127.0.0.2:443) → mTLS → ngrok cloud → Backend

Network mode: Shared listeners multiplex by SNI (TLS) or Host header (HTTP):

External client → DNS (→ LAN IP) → Shared listener (0.0.0.0:443) → SNI routing → mTLS → ngrok cloud → Backend

Virtual Mode

Pros:

• Multiple endpoints can use the same port (e.g., all on port 80)
• DNS works via /etc/hosts
• Clean separation per endpoint

Cons:

• Only accessible from same machine
• Requires root for /etc/hosts and interface management

Network Mode

Pros:

• Accessible from any device on the network (phones, VMs, CI runners)
• Multiple endpoints share original ports (80, 443) via SNI/Host routing
• Built-in DNS server — external clients just point DNS at ngrokd
• Supports both exact and wildcard (*.example.com) endpoints

Cons:

• Requires port 53 available for DNS server
• External clients must configure DNS to ngrokd machine's IP
• Raw TCP endpoints (non-HTTP/TLS) fall back to port remapping

No Endpoints Discovered

Symptoms: ngrokctl list shows 0 endpoints

Solutions:

• Wait 30 seconds for first poll cycle
• Verify API key is set: ngrokctl status
• Check bound endpoints exist in ngrok dashboard
• Check daemon logs: tail ~/ngrokd.log

Connection Refused

Symptoms: curl: (7) Failed to connect

Solutions:

• Verify daemon is running: ps aux | grep ngrokd
• Check endpoint is listed: ngrokctl list
• Verify DNS entry in /etc/hosts (virtual mode)
• Check IP allocation: cat /etc/ngrokd/ip_mappings.json

Port Already in Use

Symptoms: bind: address already in use

What happens: Daemon automatically retries with next port (up to 20 attempts)

Check logs:

tail ~/ngrokd.log | grep "Port in use, trying next port"

If you see this, the conflict was automatically resolved!

Docker: Can't Access Endpoints from Host

Issue: Using virtual mode, virtual IPs only exist inside container

Solution: Use listen_interface: "0.0.0.0" for Docker

# Edit config
docker exec -it ngrokd ngrokctl config edit

# Change to:
listen_interface: "0.0.0.0"

# Wait ~5s for reload
docker exec ngrokd ngrokctl list

# Access from host
curl http://localhost:9080/

Network Interface Errors

Symptoms: Failed to create virtual network interface

Solutions:

• Ensure running as root/sudo
• On Linux: Check kernel modules for dummy interface
• On macOS: Verify permissions for ifconfig
• Check logs for specific error details

Certificate Errors

Symptoms: Connection failures after long uptime, TLS handshake errors

Solutions:

• Force certificate renewal: ngrokctl refresh-cert --force
• Check certificate status in logs: tail ~/ngrokd.log | grep cert
• Verify certificate files exist: ls -la /etc/ngrokd/tls.*

Invalid Interface Name

Symptoms: Config validation failed with interface name

Solution: Check available interfaces:

# Linux
ip addr show

# macOS
ifconfig

# Docker
docker exec ngrokd ip addr show

Use the correct interface name from the list (e.g., enp0s1 instead of eth0)