# Gateway

## Apa Itu Gateway?

Gateway adalah inti dari Neotask, sebuah layanan yang berjalan lama yang mengelola semua sesi agen, saluran pesan, eksekusi alat, dan koneksi perangkat. Semuanya mengalir melalui Gateway.

Ini adalah server WebSocket yang mendengarkan koneksi dari klien (aplikasi desktop, aplikasi mobile, dasbor web) dan mengelola seluruh siklus hidup asisten AI.

## Arsitektur

### Komponen

- **Server WebSocket**, Menerima koneksi klien (port default 18789)
- **Server HTTP**, Melayani Control UI, host kanvas, dan endpoint health
- **Adapter Channel**, Mempertahankan koneksi ke platform pesan (WhatsApp, Telegram, Discord, dll.)
- **Manajer Sesi**, Mempertahankan dan mengelola status percakapan agen
- **Penjadwal Cron**, Menjalankan pekerjaan terjadwal dan wakeup heartbeat
- **Runtime Plugin**, Memuat dan mengelola siklus hidup plugin
- **Layanan Browser**, Mengontrol instans Chromium untuk otomasi web

### Mode Binding

| Mode | Deskripsi |
|------|-------------|
| **Loopback** | Default. Hanya dapat diakses dari localhost (127.0.0.1) |
| **LAN** | Dapat diakses di jaringan lokal Anda. Dapat ditemukan otomatis melalui Bonjour/mDNS |
| **Tailnet** | Dapat diakses melalui VPN Tailscale dengan MagicDNS |
| **Kustom** | Ikat ke alamat tertentu |

### Autentikasi

| Metode | Deskripsi |
|--------|-------------|
| **Token** | Token bearer WebSocket (UUID atau string kustom) |
| **Kata sandi** | Autentikasi berbasis kata sandi (bcrypt di-hash) |
| **Trusted Proxy** | Untuk reverse proxy dengan header pra-auth |
| **Local Trust** | Koneksi loopback disetujui otomatis |

## Konfigurasi

Gateway dikonfigurasi melalui `neotask.json` (format JSON5). Bagian utama:

| Bagian | Kontrol |
|---------|----------|
| `agents` | Daftar agen, default, workspace |
| `gateway` | Port, mode binding, auth, perilaku reload |
| `channels` | Konfigurasi dan kredensial per-channel |
| `tools` | Izin alat, profil, keamanan |
| `plugins` | Pemuatan plugin, pengaktifan, konfigurasi per-plugin |
| `models` | Auth penyedia, fallback, pengaturan penyedia |
| `skills` | Direktori skill, konfigurasi per-skill |
| `browser` | Profil browser, port, mode headless |
| `cron` | Konfigurasi penjadwal |
| `session` | Aturan reset, ambang kompaksi |
| `messages` | Pengaturan TTS, kebijakan media |
| `memory` | Konfigurasi pengindeksan memori |
| `security` | Sandboxing, mode elevated, persetujuan |

### Hot Reload

Perubahan konfigurasi dapat diterapkan tanpa memulai ulang:

| Mode | Perilaku |
|------|----------|
| **Hybrid** (default) | Terapkan perubahan aman secara hot, restart untuk yang lainnya |
| **Hot** | Hanya terapkan perubahan yang aman secara hot, abaikan yang lainnya |
| **Restart** | Restart untuk perubahan yang memerlukan reload |
| **Off** | Tidak ada reload otomatis |

## Akses Jarak Jauh

### Tailscale (Direkomendasikan)

Tailscale menyediakan akses jarak jauh yang aman dan tanpa konfigurasi:

- Ikat Gateway ke Tailnet Anda
- Akses dari perangkat mana pun di jaringan Tailscale yang sama
- DNS otomatis melalui MagicDNS
- Tailscale Serve dapat mengekspos dasbor dengan HTTPS

### SSH Tunnel

Teruskan port Gateway melalui SSH:

- Sederhana, aman, tidak diperlukan perubahan konfigurasi
- Bekerja dengan mesin yang mendukung SSH apa pun
- Mendukung protokol WebSocket penuh dan Control UI

### Aturan Keamanan

- **Loopback + SSH/Tailscale** adalah kombinasi paling aman
- Binding non-loopback memerlukan konfigurasi token auth
- Pemintaan sidik jari TLS tersedia untuk keamanan ekstra
- Kontrol browser dinonaktifkan untuk koneksi jarak jauh secara default

## Pemantauan Kesehatan

### Endpoint Health

Endpoint HTTP `/health` mengembalikan:

- Status Gateway
- Aktivitas RPC
- Kesehatan per-channel (terhubung, status auth, jumlah akun)
- Kesiapan browser
- Agen aktif dan node yang terhubung
- Waktu aktif

### Probe

- **Aktivitas RPC**, Koneksi WebSocket + uji echo
- **Kesehatan channel**, Pemeriksaan auth + ping API per channel
- **Kesiapan browser**, Pemeriksaan port, pemeriksaan proses
- **Konektivitas node**, Timestamp heartbeat terakhir

## Penemuan

### Bonjour/mDNS

Saat terikat ke LAN, Gateway mengiklankan dirinya melalui multicast DNS:

- Jenis layanan: `_neotask-gw._tcp`
- Mencakup port, transport, status TLS, dan info DNS Tailscale
- Aplikasi pendamping menemukan Gateway secara otomatis

### Penemuan Area Luas

Temukan gateway di seluruh jaringan Anda dengan timeout yang dapat dikonfigurasi. Mendukung penemuan Bonjour lokal dan DNS Tailscale.

## Beberapa Gateway

Anda dapat menjalankan beberapa instans Gateway di mesin yang sama menggunakan profil:

- Setiap profil memiliki konfigurasi, workspace, sesi, dan status terpisah
- Port berbeda untuk setiap Gateway
- Berguna untuk isolasi (pribadi vs pekerjaan) atau pengujian

## Diagnostik

### Doctor

Alat diagnostik bawaan memeriksa:

- Validitas konfigurasi
- Izin file
- Konektivitas channel
- Status auth model
- Kompatibilitas versi Node.js
- Konfigurasi yang salah umum

Alat ini dapat memperbaiki banyak masalah secara otomatis ketika diberi izin.

### Logging

Log Gateway ditulis ke file JSONL harian:

- Pelacakan penggunaan token per-completion
- Log event channel
- Logging kesalahan dengan konteks terstruktur
- Level log yang dapat dikonfigurasi