Dokumentasi NoirRouter

Quickstart

Lima menit dari nol sampai request pertama. Syarat tunggal: Node.js ≥ 22 (untuk node:sqlite bawaan) — atau Docker.

# 1. Unduh tarball dari https://noir-research.pages.dev/router lalu instal
npm install -g ./noir-router-0.3.0.tgz

# 2. Jalankan sebagai daemon latar belakang
noir-router --daemon

# 3. Buka dashboard, tambahkan provider + API key, buat combo
#    http://127.0.0.1:20129  → tab Settings menampilkan gateway key (nr-…)

# 4. Arahkan klien Anda
#    base URL : http://127.0.0.1:20129/v1
#    api key  : gateway key dari dashboard
#    model    : nama combo (mis. "coding") atau "provider/model"

# Uji cepat dengan curl
curl http://127.0.0.1:20129/v1/chat/completions \
  -H "Authorization: Bearer nr-GANTI-DENGAN-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"coding","messages":[{"role":"user","content":"Halo!"}]}'

Instalasi

Empat jalur resmi. Semuanya menjalankan kode yang sama persis, tanpa build step dan tanpa dependensi untuk diinstal.

A. npm — tarball produksi (jalur utama saat ini)

npm install -g ./noir-router-0.3.0.tgz   # 33,9 KB, "added 1 package"
noir-router                    # foreground
noir-router --daemon           # latar belakang
noir-router --port 8080 --password secret

Nama paket noir-router sudah terdaftar di npm; setelah publikasi registry aktif, jalur ini menjadi npm install -g noir-router.

B. Docker image (GHCR)

docker run -d --name noir-router -p 127.0.0.1:20129:20129 \
  -v noir-router-data:/app/data ghcr.io/azhar0407/noir-router:latest
docker logs noir-router        # menampilkan gateway key yang ter-generate

Image berbasis node:22-alpine, hanya berisi source (tidak ada npm install), berjalan sebagai user non-root node, dengan HEALTHCHECK. Tag tersedia: :latest dan :0.3.0. Catatan: image saat ini berstatus privat — perlu akses GitHub Packages untuk pull.

C. Docker Compose

docker compose up -d --build
docker compose logs -f         # gateway key ada di log

Compose bawaan repo mengikat 127.0.0.1:20129 saja (localhost), menyediakan slot DASHBOARD_PASSWORD, dan menyimpan data di volume noir-router-data (/app/data/data.db). Data provider terverifikasi selamat dari restart container.

D. Dari sumber (source)

./run.sh                                # Linux/macOS
run.bat                                 # Windows (atau: npm start)
PORT=8080 ./run.sh
DASHBOARD_PASSWORD=secret ./run.sh      # proteksi dashboard

Perintah CLI

Launcher noir-router adalah satu-satunya titik masuk instalasi. Ia melakukan preflight versi Node dan menolak jalan di bawah Node 22 dengan pesan yang jelas.

noir-router [--port 20129] [--host 127.0.0.1] [--password SECRET] [--db PATH]
noir-router --daemon     # mulai di latar belakang
noir-router stop         # hentikan daemon
noir-router status       # cek daemon (pid + lokasi log)
noir-router --version    # 0.3.0
noir-router --help

File pid dan log daemon tinggal di ~/.noir-router (dapat diganti dengan env NOIR_HOME).

Konfigurasi (environment)

Semuanya opsional. NoirRouter berjalan dengan nol konfigurasi; tabel ini mendokumentasikan setiap variabel yang dibaca kode, beserta nilai bawaannya — persis seperti .env.example di paket rilis.

Menghubungkan klien

Setiap tool yang menerima base URL kustom kompatibel-OpenAI dapat memakai NoirRouter tanpa perubahan lain:

• Base URL: http://127.0.0.1:20129/v1
• API key: gateway key dari tab Settings dashboard (format nr-…)
• Model: nama combo (mis. coding) atau rute langsung provider/model

Untuk tool tertutup, dashboard menyediakan hub integrasi yang men-generate konfigurasi resmi untuk Claude Code, OpenCode, Cline/Continue, dan Cursor (BYOK / override OpenAI). Tidak ada intersepsi MITM dan tidak ada root CA yang dipasang — konfigurasi resmi tool itu sendiri yang dipakai. Server MCP atau skill agen apa pun yang menerima base URL kustom juga bekerja tanpa perubahan, karena gateway ini endpoint OpenAI-compatible biasa.

Provider & preset

Empat tipe provider didukung:

• OpenAI-compatible — API key; semua API bergaya OpenAI dan server lokal.
• Anthropic — Messages API native, dengan translasi format dua arah.
• Google Gemini — API native, dengan translasi format dua arah.
• CLI bridge — memanggil CLI resmi provider yang sudah login di mesin (claude -p, codex exec, gemini -p, atau perintah kustom apa pun). Langganan dapat dicapai tanpa menyentuh token OAuth.

44 preset sekali klik di paket rilis: openai, openrouter, deepseek, groq, mistral, xai, together, fireworks, cerebras, perplexity, cohere, kimi, kimi-cn, glm, glm-cn, minimax, minimax-cn, qwen, qwen-cn, volcengine, stepfun, siliconflow, novita, huggingface, github-models, nvidia, sambanova, hyperbolic, nebius, ollama-cloud, azure, cloudflare, ollama-local, lmstudio, llamacpp, vllm, voyage, jina, anthropic, gemini, claude-cli, codex-cli, gemini-cli, custom-cli. Preset adalah data, bukan kode — daftarnya bertambah tanpa perubahan program. Provider kustom bebas juga dapat dibuat manual.

Setiap provider dapat menyimpan banyak API key: key berputar round-robin, kegagalan dihitung per key, dan failover antar-key terjadi otomatis pada error 401/403/408/429/5xx maupun gangguan jaringan.

Combo & strategi

Combo adalah rantai bernama berisi langkah-langkah provider/model. Klien cukup meminta nama combo sebagai nama model.

Rute langsung tetap tersedia kapan pun: gunakan provider/model sebagai nama model untuk memukul satu provider tanpa combo.

Token Saver

Diaktifkan per combo. Token Saver mengompresi hasil tool sebelum diteruskan ke model, meniru pendekatan RTK:

• Menghapus kode ANSI dan meruntuhkan baris kosong berlebih
• Dedup baris berurutan dengan penanda pengulangan, plus batas baris yang berulang
• Minifikasi JSON
• Truncate cerdas head/tail pada hasil tool yang panjang (ambang: NOIR_TOOL_MAX_CHARS, bawaan 12000 karakter)

Penghematan diukur per request dan ditotal di dashboard, sehingga klaim hematnya dapat diperiksa, bukan ditebak.

Referensi endpoint

Semua endpoint klien memakai otentikasi Authorization: Bearer <gateway-key>. Tanpa key yang valid, responsnya 401.

Dashboard & keamanan

Dashboard (di port yang sama dengan API) mencakup: CRUD provider & key dengan tombol Test koneksi, editor combo beserta strateginya, log request, statistik token per model/provider, total penghematan Token Saver, pengelolaan gateway key, dan hub integrasi tool.

• Password opsional via DASHBOARD_PASSWORD / --password: layar login sungguhan, cookie sesi HttpOnly kedaluwarsa 24 jam.
• Rate-limit login: 5 kegagalan → penguncian 5 menit (terverifikasi: tetap 429 walau password benar selama terkunci).
• Header keamanan: CSP, X-Content-Type-Options (nosniff), frame-deny di semua respons.
• Bind localhost secara bawaan. Untuk akses publik, taruh reverse proxy di depannya dan set password terlebih dahulu.
• Nol telemetri: tidak ada analytics dan tidak ada panggilan keluar atas inisiatif NoirRouter sendiri — dapat diverifikasi dari source-nya yang kecil atau dari trafiknya.

Lokasi data

Seluruh state adalah satu file SQLite (data.db) — provider, key, combo, log, statistik. Resolusi lokasinya satu aturan di semua jalur instalasi:

1. $NOIR_DB                       ← bila di-set (Docker: /app/data/data.db)
2. ./data.db                       ← bila sudah ada (instalasi lokal lama tetap utuh)
3. ~/.noir-router/data.db          ← instalasi baru; selamat dari upgrade

Backup = salin satu file itu. Tidak ada cloud sync dan tidak ada komponen server di tempat lain: 100% NoirRouter ada di paket yang Anda unduh.

Troubleshooting

FAQ

Apakah NoirRouter fork dari 9Router?

Bukan. NoirRouter implementasi original yang ditulis setelah audit source-level atas 9Router v0.5.104: kekuatannya diimplementasikan ulang, kelemahannya dijawab dengan perbaikan struktural. Peta paritas lengkapnya diringkas di halaman produksi.

Kenapa nol dependensi?

Karena Node 24 menyediakan node:sqlite dan fetch bawaan. Hasilnya: tarball 33,9 KB, tidak ada build step, tidak ada rantai pasok untuk diaudit selain kode NoirRouter sendiri, dan perilaku identik di semua platform.

Bagaimana langganan Claude/Codex/Gemini dipakai tanpa API key?

Lewat tipe provider CLI bridge: NoirRouter memanggil CLI resmi yang sudah login di mesin Anda. Tidak ada token yang diekstrak, tidak ada sidik jari yang dipalsukan, tidak ada trafik yang disadap.

Apakah ada telemetri?

Tidak ada. NoirRouter tidak menelepon rumah. Satu-satunya trafik keluar adalah request yang Anda minta ke provider yang Anda konfigurasi.

Apakah ini untuk dipakai bersama / dijual lagi akses akunnya?

Bukan tujuan desainnya. NoirRouter adalah gateway personal: pooling akun upstream untuk resale/sharing secara eksplisit di luar cakupan.

Di mana melaporkan masalah?

Ke pengelola lab: noirlucilfer@gmail.com. Sertakan versi (noir-router --version), jalur instalasi, dan potongan log request dari dashboard.