ngrok-tunnels skill

# ngrok-tunnels skill

## When to use

Use this skill when the user needs to:

- Expose a local HTTP service at a public HTTPS URL
- Understand how the webhook-relay integrates with ngrok vs Cloudflare Tunnel
- Troubleshoot tunnel startup failures
- Switch tunnel providers at runtime

## What is a tunnel

A tunnel opens a persistent connection from your machine to a cloud relay. The cloud relay receives HTTPS traffic at a public URL and forwards it over the persistent connection to a local port. No firewall or router changes are required.

webhook-relay supports two providers:

- `ngrok` - uses the `@ngrok/ngrok` Node.js SDK. Requires an auth token. Free tier gives one random subdomain.
- `cloudflare` - uses `cloudflared` binary via child_process.spawn. Requires no account for temporary tunnels.
- `none` - no tunnel. The relay server is only reachable on localhost.

## ngrok setup

1. Create a free account at ngrok.com
2. Copy your auth token from the ngrok dashboard
3. Set the environment variable:

```
RELAY_NGROK_AUTHTOKEN=your_token npx webhook-relay
```

The token is stored only in the environment - never written to disk by webhook-relay.

## Cloudflare Tunnel setup

1. Install `cloudflared`: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
2. Set the provider:

```
RELAY_TUNNEL_PROVIDER=cloudflare npx webhook-relay
```

Cloudflare provides a random `trycloudflare.com` subdomain. No account or token required. The URL changes on every restart.

## Implementation reference

```typescript
// Tunnel interface implemented by both providers
interface TunnelHandle {
  url: string;
  close(): Promise<void>;
}

// ngrok provider
import * as ngrok from '@ngrok/ngrok';

async function startNgrokTunnel(port: number, token: string): Promise<TunnelHandle> {
  const listener = await ngrok.forward({
    addr: port,
    authtoken: token,
  });
  const url = listener.url();
  if (!url) throw new Error('ngrok did not return a URL');
  return {
    url,
    close: () => listener.close(),
  };
}

// Cloudflare provider (spawn cloudflared, parse URL from stderr)
import { spawn } from 'node:child_process';

async function startCloudflareTunnel(port: number): Promise<TunnelHandle> {
  return new Promise((resolve, reject) => {
    const child = spawn('cloudflared', [
      'tunnel', '--url', `http://localhost:${port}`,
      '--no-autoupdate',
    ], { stdio: ['ignore', 'ignore', 'pipe'] });

    const URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
    let buf = '';

    child.stderr.on('data', (chunk: Buffer) => {
      buf += chunk.toString();
      const match = URL_RE.exec(buf);
      if (match) {
        resolve({
          url: match[0],
          close: async () => { child.kill('SIGTERM'); },
        });
      }
    });

    child.on('exit', (code) => {
      reject(new Error(`cloudflared exited with code ${code}`));
    });

    setTimeout(() => reject(new Error('cloudflared URL timeout after 15s')), 15_000);
  });
}
```

## Tunnel lifecycle

1. Server starts and listens on `RELAY_PORT` (default 7701)
2. Tunnel provider starts and connects to the cloud relay
3. The public URL is stored in memory and emitted via SSE to the dashboard
4. The TunnelStatusBar in the dashboard updates from `starting` to `connected`
5. On shutdown (SIGTERM/SIGINT), `TunnelHandle.close()` is called before process exit

## SSE tunnel events

The dashboard receives tunnel state changes over the `/api/sse` event stream:

```
event: tunnel
data: {"status":"connected","url":"https://abc123.ngrok-free.app"}

event: tunnel
data: {"status":"starting"}

event: tunnel
data: {"status":"disconnected","error":"auth token invalid"}
```

## Status values

| Status | Meaning |
|--------|---------|
| `starting` | Tunnel process is starting, URL not yet available |
| `connected` | Tunnel is up, URL is available |
| `disconnected` | Tunnel process exited or failed |
| `local-only` | Provider is set to `none` |

## Common pitfalls

- Do not parse ngrok URLs from the ngrok web dashboard URL (port 4040). Use the SDK `listener.url()` return value.
- `cloudflared` writes the URL to stderr, not stdout. Always capture stderr.
- The ngrok free tier allows only one concurrent tunnel per account. If another process is using ngrok, the second will fail with `ERR_NGROK_108`.
- cloudflared URLs are ephemeral and change on every restart. Do not hardcode them in webhook provider settings.
- Both providers require outbound TCP connections. Verify firewall rules allow outbound on port 443.
- If `cloudflared` is not on PATH, the spawn will fail with `ENOENT`. Check installation with `which cloudflared`.

## Troubleshooting

| Symptom | Resolution |
|---------|------------|
| `ERR_NGROK_108` | Another ngrok agent is already running with this token. Stop it before starting webhook-relay |
| `auth token invalid` | The `RELAY_NGROK_AUTHTOKEN` value is wrong or expired. Regenerate at dashboard.ngrok.com |
| `cloudflared URL timeout` | cloudflared is installed but slow to connect. Check outbound connectivity |
| `cloudflared: command not found` | Install cloudflared and add it to PATH |
| Dashboard shows "starting" for > 30s | Tunnel is stuck. Restart the relay server |
| URL changes on every restart | Expected behavior for ngrok free tier and all cloudflare tunnels. Configure a fixed domain in ngrok paid plans |