Konfigurasi dengan settings.json

#Lokasi file

Path-nya sama di setiap OS:

~/.ferret/settings.json          # your settings (edit this)
~/.ferret/settings.schema.json   # JSON Schema, rewritten by the app on launch
~/.ferret/state.json             # open folder, last URL, open tabs (managed by the app)
~/.ferret/.env                   # optional: API keys referenced by apiKeyEnv

• Atur FERRET_CONFIG_DIR (nama lama MOVIE_ADE_CONFIG_DIR juga berfungsi) untuk memakai folder lain, misalnya folder di dalam repo dotfiles. ~ akan diekspansi.
• Build pengembangan (pnpm dev) memakai ~/.ferret/dev/, sehingga mengutak-atik Ferret tidak pernah menimpa pengaturan Anda yang sebenarnya.
• Upgrade dari 0.1.0: saat peluncuran pertama, <userData>/settings.json yang lama disalin ke file-file baru. File lama dibiarkan di tempatnya sebagai cadangan dan tidak pernah diubah.

Upgrade dari MOVIE-ADE: saat peluncuran pertama, settings.json, state.json, usage/, dan .env disalin dari ~/.movie-ade/ ke ~/.ferret/. Folder lama dibiarkan di tempatnya dan tidak diubah.

Di aplikasi, Pengaturan menampilkan path-nya di bagian atas, dengan Buka settings.json (mengeditnya di editor bawaan dengan pelengkapan dari schema) dan Tampilkan di folder.

#Schema dan validasi

Baris pertama settings.json adalah "$schema": "./settings.schema.json". Editor seperti VS Code dan agent seperti Claude Code memakainya untuk pelengkapan, validasi, dan deskripsi setiap field. Schema disertakan di dalam aplikasi dan ditulis di sebelah file pada setiap peluncuran, sehingga selalu cocok dengan versi yang terinstal.

Key yang tidak dikenal Ferret dipertahankan apa adanya saat aplikasi menyimpan. Tab yang terbuka, URL terakhir, dan status sesi lainnya disimpan di state.json, bukan di sini.

#Contoh dengan penjelasan

JSON tidak mendukung komentar, jadi catatannya ada di bawah contoh. Setiap field bersifat opsional; hilangkan yang tidak Anda perlukan.

{
  "$schema": "./settings.schema.json",
  "theme": "dark",
  "locale": "en",
  "projects": [
    {
      "id": "shop",
      "name": "shop",
      "folderPath": "/Users/you/src/shop",
      "kind": "web",
      "urls": [
        { "id": "local", "label": "local", "url": "http://localhost:3000" },
        { "id": "prd", "label": "prd", "url": "https://shop.example.com" }
      ]
    }
  ],
  "agents": {
    "customAgents": [
      { "id": "custom:my-agent", "name": "My agent", "command": "my-agent", "args": "--yes" }
    ],
    "startupAgents": ["claude", "custom:my-agent"]
  },
  "capture": {
    "transcription": "compatible",
    "language": "auto",
    "costLimitUsd": null,
    "sttEndpoints": {
      "compatible": {
        "baseUrl": "http://gpu-box.local:8000/v1",
        "model": "Systran/faster-whisper-large-v3",
        "apiKeyEnv": "WHISPER_SERVER_TOKEN"
      }
    }
  },
  "organizer": {
    "runner": "api:compatible",
    "endpoints": {
      "compatible": { "baseUrl": "http://localhost:11434/v1", "model": "qwen3:14b" }
    }
  },
  "decision": {
    "enabled": true,
    "preset": "ollama",
    "endpoint": "http://localhost:11434/v1/systemone",
    "model": "clef-flash"
  },
  "layout": {
    "panels": {
      "projects": { "dock": "left", "visible": true },
      "terminal": { "dock": "bottom", "visible": true },
      "files": { "dock": "right", "visible": false }
    }
  }
}

• projects[].urls: target tinjauan untuk menu URL. Yang pertama dibuka saat proyek dibuka. id boleh berupa string unik apa pun.
• agents.customAgents: CLI atau skrip wrapper apa pun. startupAgents berisi daftar tab agent yang dibuka bersama proyek, sesuai urutan.
• capture.sttEndpoints.compatible: server apa pun yang mengimplementasikan /v1/audio/transcriptions milik OpenAI (speaches, vLLM, LocalAI…). costLimitUsd: null mematikan batas biaya, yang masuk akal untuk GPU milik sendiri. Lihat Transkripsi dan biaya.
• organizer: Rapikan temuan yang dikirim langsung ke server /v1/chat/completions yang kompatibel dengan OpenAI (di sini Ollama). Gunakan "runner": "claude-code" atau "codex" untuk memakai login CLI Anda sendiri, dan organizer.cliModels untuk memilih modelnya.
• decision: model yang memeriksa apakah setiap temuan sudah diperbaiki. Clef Flash di Ollama lokal gratis dan bisa membaca screenshot. preset juga bisa berupa cloudflare, vercel, typesafe, atau custom.
• Setiap blok penyedia (sttEndpoints.*, organizer.endpoints.*) juga menerima timeoutMs, headers, dan, untuk Azure, apiVersion.

#Penyedia apa pun: endpoint kustom

Preset hanya mengisi URL dan model di awal. Setiap koneksi (transkripsi, Rapikan temuan, model keputusan) juga menerima URL, model, header, dan autentikasi apa pun, sehingga Anda bisa memakai penyedia apa pun: Cloudflare, gateway, proxy perusahaan, atau server Anda sendiri. Field di bawah ini memiliki nama dan bentuk yang sama di ketiganya.

Transkripsi dengan server /v1/audio/transcriptions kompatibel OpenAI mana pun yang meminta key-nya di header api-key:

"capture": {
  "transcription": "compatible",
  "sttEndpoints": {
    "compatible": {
      "baseUrl": "https://stt.internal.example.com/v1",
      "model": "whisper-large-v3",
      "authScheme": "header",
      "authHeader": "api-key",
      "apiKeyEnv": "INTERNAL_STT_KEY",
      "headers": { "X-Team": "design" }
    }
  }
}

Rapikan temuan dengan Cloudflare Workers AI (chat completions yang kompatibel dengan OpenAI), opsional melalui AI Gateway:

"organizer": {
  "runner": "api:compatible",
  "endpoints": {
    "compatible": {
      "baseUrl": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
      "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
      "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
    }
  }
}

Model keputusan di Cloudflare Workers AI (Clef Flash), atau dengan "preset": "custom" di server apa pun yang mendukung System One API. Model keputusan menerima URL permintaan lengkap di endpoint (dengan {account_id} dan {model} yang diisi); setiap field lainnya memiliki nama dan bentuk yang sama seperti di atas:

"decision": {
  "enabled": true,
  "preset": "cloudflare",
  "endpoint": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}",
  "model": "clef-flash",
  "authScheme": "bearer",
  "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
  "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
}

Taruh CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, dan variabel lainnya di ~/.ferret/.env. Nama model di atas hanya contoh. Periksa daftar model penyedia Anda.

#API key

Setiap blok penyedia menerima key dengan salah satu dari tiga cara. Yang pertama ditemukan yang dipakai:

1. "apiKey": "…": key dalam teks biasa di settings.json. Siapa pun yang bisa membaca file tersebut bisa membaca key-nya, dan Pengaturan menampilkan peringatan selama key tersebut ada. Hindari cara ini, terutama jika file berada di repo dotfiles.
2. "apiKeyEnv": "OPENAI_API_KEY": nama variabel lingkungan. Ferret mencari di lingkungannya sendiri, lalu di .env proyek yang terbuka, lalu di ~/.ferret/.env. Aplikasi yang dibuka dari Finder atau menu Start tidak melihat variabel yang diekspor di profil shell Anda, jadi ~/.ferret/.env adalah tempat yang andal.
3. Key yang disimpan di Pengaturan: dienkripsi dengan keychain OS di <userData>/stt-keys.bin (lihat Tempat key disimpan).

Ferret hanya membaca variabel lingkungan yang Anda sebutkan di apiKeyEnv. Key tidak pernah dicatat di log, tidak pernah ditampilkan di UI, dan tidak pernah disertakan dalam laporan crash.

#Muat ulang langsung

Ferret memantau settings.json. Saat file berubah, aplikasi membacanya ulang, memeriksanya terhadap schema, lalu menerapkannya: tema, bahasa, tata letak, agent, proyek, dan endpoint AI diperbarui tanpa restart, dan halaman Pengaturan ikut diperbarui.

• Jika file memiliki error sintaks JSON atau nilai dengan tipe yang salah, tidak ada bagian dari edit tersebut yang diterapkan. Aplikasi mempertahankan pengaturan valid terakhir, menampilkan error beserta nomor barisnya, dan tidak menimpa file Anda sampai Anda memperbaikinya.
• Saat aplikasi sendiri yang menyimpan (Anda mengubah sesuatu di Pengaturan), aplikasi menulis ke file sementara lalu mengganti namanya menjadi settings.json, sehingga crash tidak pernah meninggalkan file yang setengah tertulis.

#Biarkan agent coding mengonfigurasi Ferret

Tempel ini ke Claude Code, Codex, atau agent apa pun yang bisa mengedit file:

Edit ~/.ferret/settings.json following the JSON Schema in
~/.ferret/settings.schema.json (read the field descriptions first).
Keep unknown keys and keep the file valid JSON. Never write API keys in
plaintext: set "apiKeyEnv" to an environment variable name instead and
tell me which variable to put in ~/.ferret/.env.
Ferret applies the change as soon as the file is saved.

Task: <what you want, e.g. "use my Ollama at http://localhost:11434 with
qwen3:14b for Organize findings and add a prd URL for the shop project">

Prompt yang sama, dengan path Anda yang sebenarnya sudah terisi, ada di Pengaturan → Biarkan coding agent mengonfigurasi Ferret dengan tombol Salin prompt.