Factory Droid + JoinGonka Gateway: BYOK pada model jaringan Gonka

Langkah 1: pasang Droid. Cara resmi dari dokumentasi Factory:

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

Skrip ini menaruh binary di ~/.local/bin dan memberi tahu cara menambahkan direktori tersebut ke PATH; di Linux dokumentasinya meminta Anda memasang paket xdg-utils juga. Verifikasi — droid --version.

Langkah 2: dapatkan kunci. Daftar di gate.joingonka.ai/register, konfirmasi alamat Anda, lalu buat kunci dengan awalan jg- di bagian «Kunci API». Satu kunci dan satu saldo berlaku untuk semua model di jaringan.

Langkah 3: jalankan penginstal.

npx @joingonka/setup --tool droid

Penginstal akan meminta kunci — kunci tidak diteruskan lewat argumen baris perintah agar tidak tersimpan di riwayat shell — dan melakukan empat hal:

• menambahkan entri ke array customModels di file ~/.factory/settings.json (di Windows — %USERPROFILE%\.factory\settings.json) untuk setiap model di jaringan: alamat gateway, tipe penyedia generic-chat-completion-api, kunci secara literal, jendela konteks dan batas respons yang sebenarnya; file akan mendapat izin 600;
• menetapkan model default — sessionDefaultSettings.model — ke DeepSeek V4 Flash, tetapi hanya jika belum dipilih atau menunjuk ke model yang sudah tidak ada di jaringan. Model dari katalog Factory atau entri BYOK milik orang lain tidak akan diambil alih, melainkan hanya diberi tahu cara beralih;
• menyimpan salinan file sebelumnya, sementara entri milik orang lain di customModels, pengaturan lain, dan komentar dibiarkan apa adanya; file yang tidak dapat diurai tidak akan ditimpa, melainkan diberi tahu apa yang harus diperbaiki;
• di akhir, mengirim permintaan langsung ke gateway dan memberi tahu secara jelas apakah kunci, alamat, dan model diterima.

Model default lain diatur dengan flag --model dengan singkatan deepseek, glm, atau minimax — model yang ditentukan secara eksplisit selalu ditulis. Untuk dotfile dan server tersedia mode tanpa pertanyaan, di mana kunci diambil dari variabel lingkungan:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

Droid tidak perlu dijalankan ulang: perubahan di settings.json terdeteksi otomatis. Baris ! Could not verify right now dengan respons 429 di akhir berarti model sedang sibuk, bukan kesalahan konfigurasi — konfigurasinya sudah tersimpan.

Semua yang dilakukan installer bisa Anda kerjakan sendiri secara manual. Pengaturan pengguna Droid tersimpan di ~/.factory/settings.json; jika file tersebut belum ada, Droid akan membuatnya saat pertama kali dijalankan. Untuk jaringan Gonka, Anda memerlukan array customModels dan model default:

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

Model default disimpan di sessionDefaultSettings.model dan merujuk ke entri lewat id-nya. Dokumentasi Factory juga menyebut key model di root file, tapi pada uji coba kami, droid exec tanpa flag -m justru mengambil model dari sessionDefaultSettings — termasuk setelah nilainya diganti.

Kunci API tersimpan sebagai teks biasa di file: amankan dengan chmod 600 ~/.factory/settings.json dan jangan pindahkan entri berisi kunci ke .factory/settings.json milik proyek — file itu biasanya ikut masuk ke repositori. Dan kalau setelah Droid dijalankan file terlihat berbeda, itu wajar: setiap kali menyimpan pengaturan apa pun, Droid menulis ulang seluruh file — merapikan urutan key, menambahkan field index pada entri, dan tidak menyimpan komentar. Izin 600 tetap bertahan, dan installer bisa memperbarui entri semacam itu tanpa masalah.

Droid menampilkan entri buatannya secara terpisah dari katalog: menurut dokumentasi, dalam mode interaktif perintah /model menampilkannya di bagian Custom models, dan Ctrl+N menelusuri model langsung di kolom input. Dalam mode sekali jalan, model ditentukan oleh flag -m dengan nilai dari kolom id, garis miring ditulis apa adanya: droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Jika salah menulis nama, Droid akan menjawab Invalid model dan mendaftar semua model yang dikenali, termasuk model buatan Anda dalam bentuk custom:… (display name): sekaligus terlihat bahwa entri berhasil dimuat. Nama bergaya dokumentasi Factory, dari label dan nomor (custom:DeepSeek-V4-Flash-(Gonka)-0), tidak akan berfungsi dengan id eksplisit — dalam uji coba kami, hasilnya sama saja: Invalid model.

Apa yang memerlukan akun Factory. Model buatan sendiri menghilangkan urusan pembayaran token, tetapi bukan urusan masuk ke produk itu sendiri. Inilah yang ditunjukkan uji coba Droid 0.225.1 tanpa login akun:

Untuk bekerja di antarmuka, buat akun Factory dan login melalui browser — opsi Login atau perintah /login; di mesin tanpa browser, dokumentasi menyarankan kunci dari pengaturan akun pada variabel FACTORY_API_KEY. Menjalankan droid exec tanpa login praktis untuk mencoba, tetapi tidak dijelaskan secara resmi — jangan mengandalkannya di CI. Menurut halaman tarif Factory, BYOK termasuk dalam semua paket individual dengan batas gratis, dan di atas batas tersebut penggunaan BYOK ditagih sesuai ketentuan paket; ketentuan terkini ada di factory.ai/pricing. Token model jaringan dibayar terpisah — dari saldo JoinGonka.

Model mana yang harus dipilih. Harga semua model di jaringan sama, jadi pilihannya soal perilaku. Beginilah mereka bekerja dalam uji coba droid exec kami pada satu tugas — membaca file dan menemukan kesalahan:

Flag -r (tingkat penalaran) tidak berlaku untuk model BYOK, menurut dokumentasi Factory. Mengapa DeepSeek V4 Flash dipilih secara default, dibahas di ulasan model.

Letakkan di direktori kosong sebuah file calc.py dengan kesalahan yang jelas — misalnya, luas persegi panjang yang sisi-sisinya dijumlahkan alih-alih dikalikan — lalu minta Droid menemukannya:

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Tanpa flag, droid exec berjalan dalam mode hanya-baca: file bisa dilihat, tapi tidak bisa diubah. Agen akan memanggil sendiri alat pembaca dan menjawab secara substantif, dengan menyebutkan ekspresi yang salah. Dengan flag -o json, jawaban datang sebagai satu objek yang praktis diurai dengan skrip (output dipersingkat):

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

Field factory_credits: 0 menegaskan bahwa pekerjaan berjalan di model Anda, bukan di kredit Factory. Agar agen bisa mengubah file, tambahkan tingkat otonomi: droid exec --auto low "Fix the bug in calc.py and change nothing else." — dalam pengujian kami, DeepSeek V4 Flash membaca file, mengganti penjumlahan menjadi perkalian, dan menjalankan sendiri skrip untuk memastikan yang tercetak adalah 12.

Pemeriksaan ketiga — dari sisi gateway: di dasbor pada bagian "Penggunaan" permintaan akan muncul dalam rincian "Per model", dan di blok "Per kunci" waktu permintaan terakhir akan diperbarui.

Jika ada yang tidak beres, perhatikan keunikan Droid: di konsol droid exec hanya mencetak Error during droid execution: Exec failed (dalam JSON — "result":"Exec failed"), sedangkan penyebab sebenarnya tetap ada di log. Cara mengambilnya dengan satu perintah:

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

Alat agen menghabiskan token secara berbeda dari chat: untuk setiap kalimat Anda, Droid menambahkan sistem prompt, deskripsi alat, dan snapshot direktori kerja, dan tugas memakan beberapa putaran. Dalam pengujian kami, setiap putaran memakan sekitar 9,5 ribu token input sebelum pertanyaan Anda: tugas «baca file dan temukan kesalahan» memakan dua putaran dan sekitar 19 ribu token, «perbaiki dan periksa» — empat putaran dan sekitar 44 ribu. Oleh karena itu, harga per token di sini sangat menentukan.

Melalui JoinGonka Gateway, token berharga $0.0069 per juta di input dan $0.021 per juta di output — harga sama untuk semua model jaringan dan diperbarui di halaman ini dari sumber langsung.

Estimasi di kolom kanan berdasarkan harga per September 2026. Sebagai perbandingan — bagaimana cara membayar model di Droid:

Perintah /cost di antarmuka Droid menampilkan statistik sesi, sedangkan penggunaan akurat dan saldo untuk model BYOK ada di dashboard gateway, di bagian «Penggunaan» dan «Penagihan». Buat kunci terpisah untuk Droid — lalu lintasnya akan terlihat sebagai baris terpisah.

Otonomi. Dalam mode sekali jalan, Droid secara default hanya membaca, sedangkan hak diperluas lewat tingkatan: --auto low — mengubah file, --auto medium — plus memasang dependensi, build, tes, dan commit lokal, --auto high — hingga push dan deploy. Flag --skip-permissions-unsafe mencabut semua pemeriksaan — hanya untuk kontainer sekali pakai. Di mode interaktif, tingkatannya diganti dengan Ctrl+L, sedangkan tingkat awal ditentukan oleh sessionDefaultSettings.autonomyLevel; secara default nilainya off — semuanya dengan konfirmasi.

Tanda tangan di commit. Pengaturan includeCoAuthoredByDroid aktif secara default: Droid menambahkan baris co-author ke pesan commit. Jika tidak diperlukan, tulis "includeCoAuthoredByDroid": false di settings.json.

Di mana sesi disimpan. Setelah masuk ke akun, Droid secara default mencerminkan sesi CLI ke versi web Factory — ini diatur oleh cloudSessionSync. Kunci BYOK, menurut dokumentasi, tetap lokal; jika percakapan pun harus tetap di mesin, setel "cloudSessionSync": false. Gateway dari sisinya tidak menyimpan isi prompt dan jawaban — di statistik hanya tersisa agregat pemakaian.

Pembaruan. Instalasi lewat skrip diperbarui sendiri; versi bisa dipatok dengan variabel FACTORY_DROID_AUTO_UPDATE_ENABLED=false atau perintah droid update --version <version>; build dari npm tidak diperbarui sendiri. Setelah pembaruan, pastikan dengan satu droid exec bahwa model jaringan masih ada.

Gambar. Model jaringan bersifat teks; untuk screenshot, simpan di dekatnya entri dengan model yang bisa vision, di penyedia lain.

Jika bekerja tanpa akun vendor itu prinsip. Model jaringan yang sama bisa dihubungkan ke agen terminal terbuka yang tidak butuh login — misalnya ke OpenCode dengan installer yang sama, memakai flag --tool opencode.