---
name: cloudflare-tunnel-manager
description: Membantu setup, manajemen, dan debugging Cloudflare Tunnels (Quick & Named) serta integrasinya dengan aplikasi lokal (seperti Vite dan Express) dan Cloudflare MCP API Proxy.
---

# Cloudflare Tunnel Manager Skill

Skill ini memberikan Anda (Agent) pengetahuan komprehensif tentang cara mengelola, menghubungkan, dan men-*debug* koneksi antara *localhost* dan internet menggunakan **Cloudflare Tunnel**, serta mengatasi masalah umum terkait *frontend proxy* (Vite) dan *backend* (API).

## 1. Jenis-jenis Tunnel

### Quick Tunnels (Gratis, Anonim)
Menghasilkan subdomain acak `*.trycloudflare.com`. Tidak memerlukan akun Cloudflare.

**AGENT TOOL:** Gunakan script bawaan:
```bash
/home/aseps/MCP/.agents/skills/cloudflare-tunnel-manager/scripts/cf_quick_tunnel.sh <PORT>
```

Script ini secara otomatis akan:
1. Mencari binary `cloudflared` di `$PATH` + lokasi fallback
2. Memvalidasi apakah port target sedang aktif
3. Menginjeksi `allowedHosts: true` pada Vite config (jika ada)
4. Menghentikan tunnel lama yang masih berjalan
5. Memulai tunnel baru dengan protokol QUIC
6. Mencetak URL publik yang dihasilkan

### Named Tunnels (Zero Trust)
Membutuhkan akun Cloudflare, token otentikasi, dan domain aktif di DNS Cloudflare.

```bash
cloudflared tunnel run --token <TOKEN>
```

Harus dipastikan:
- Nama domain bisa di-resolve ke IP Cloudflare
- Token API memiliki *scope* `Zone:Read`
- Konfigurasi tunnel terdaftar di Cloudflare Dashboard

## 2. Pengecekan Target Localhost (Port Collision)

Sebelum menyambungkan Tunnel ke suatu port, Agent **WAJIB** mengecek aplikasi apa yang berjalan di port tersebut:

```bash
# Cek port aktif
ss -lptn 'sport = :<PORT>'
# atau
lsof -i :<PORT>
```

**PENTING:** Jika port target (misal: 3000) sibuk oleh proses lain, aplikasi frontend seperti **Vite** secara otomatis berpindah ke port berikutnya (3001, 3002, dst). Selalu cek log `npm run dev` untuk memastikan port aktual, dan arahkan Tunnel ke port aktual tersebut.

## 3. Bypass "Blocked Request" pada Vite

Ketika aplikasi Vite diekspos melalui Cloudflare Tunnel, header `Host` tidak lagi `localhost` melainkan domain `.trycloudflare.com`. Vite 5+ secara ketat memblokir Host yang tidak dikenal (*DNS Rebinding protection*).

**Solusi:** Script `cf_quick_tunnel.sh` sudah menangani ini secara otomatis. Jika perlu manual:

```typescript
// vite.config.ts
export default defineConfig({
  server: {
    allowedHosts: true, // Izinkan semua host
    // konfigurasi lain...
  }
});
```

## 4. Validasi Full-Stack (Backend API)

Jika *frontend* diekspos namun mengalami kendala (login gagal, 502 Bad Gateway), Agent **WAJIB** mengecek:

1. **Backend API aktif:** Pastikan service backend (FastAPI, Node.js, dll) berjalan di port yang benar
2. **Proxy configuration:** Pastikan `vite.config.ts` memiliki konfigurasi proxy yang benar ke backend
3. **CORS settings:** Backend harus mengizinkan origin dari domain `.trycloudflare.com`

```bash
# Cek ketersediaan backend (contoh port 8001)
curl -s http://localhost:8001/health || echo "Backend BELUM aktif!"
```

## 5. Integrasi MCP Settings (Cloudflare API)

Untuk mengakses atau memodifikasi Tunnel via API Cloudflare secara programatik, gunakan MCP Proxy:

**Proxy Script:** `/home/aseps/MCP/scripts/cloudflare_mcp_proxy.py`

Script ini membuat bridge antara stdio (JSON-RPC) dan Cloudflare MCP SSE endpoint, memungkinkan Agent mengakses Cloudflare API melalui protokol MCP standar.

**Konfigurasi MCP:**
Pastikan variabel berikut ada di `.env`:
```
CLOUDFLARE_API_TOKEN=<your_token>
CLOUDFLARE_ACCOUNT_ID=<your_account_id>
```

Untuk registrasi ke `cline_config.json` atau `blackbox_mcp_settings.json`:
```json
{
  "mcpServers": {
    "cloudflare": {
      "command": "python3",
      "args": ["/home/aseps/MCP/scripts/cloudflare_mcp_proxy.py"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "${CLOUDFLARE_API_TOKEN}"
      }
    }
  }
}
```

## 6. Troubleshooting

### Tunnel tidak menghasilkan URL
- **Penyebab:** `cloudflared` tidak terinstal atau koneksi internet terputus
- **Solusi:** Jalankan `cloudflared --version` untuk verifikasi instalasi. Cek `$LOG_FILE` untuk detail error.

### Error "connection refused" di tunnel
- **Penyebab:** Tidak ada aplikasi yang berjalan di port target
- **Solusi:** Pastikan aplikasi sudah `npm run dev` atau equivalent sebelum membuat tunnel

### Tunnel berhenti tiba-tiba
- **Penyebab:** Quick Tunnel memiliki TTL terbatas, atau proses di-kill
- **Solusi:** Jalankan ulang script `cf_quick_tunnel.sh`. Untuk solusi permanen, gunakan Named Tunnel.

### Vite menolak koneksi ("Blocked Request")
- **Penyebab:** Vite 5+ DNS Rebinding protection
- **Solusi:** Tambahkan `allowedHosts: true` di `vite.config.ts` (otomatis dilakukan oleh script)