menu
languageBahasa Indonesia
save_alt Download

Gatekeeper

SQL yang disetujui manusia untuk agen AI: agen mengusulkan query, Anda menyetujuinya di Beekeeper Studio sebelum dijalankan, read-only secara default.

oleh Gldywn Plugin komunitas

Readme

Teks ini ditulis oleh pihak ketiga dan diterjemahkan secara otomatis. Baca versi asli dalam bahasa Inggris

Gatekeeper

Gatekeeper

Agen Anda mengusulkan SQL. Anda yang menyetujui apa yang dijalankan.

CI Rilis Lisensi

Berfungsi dengan Claude Code Berfungsi dengan Codex CLI Berfungsi dengan OpenCode

Gatekeeper adalah jembatan yang disetujui manusia antara agen AI dan database Anda. Agen mengusulkan query lewat MCP; secara default, tidak ada yang dijalankan sampai Anda menyetujuinya di Beekeeper Studio, berdasarkan teks SQL-nya, sebelum eksekusi. Query lalu dijalankan pada koneksi yang sudah dimiliki Beekeeper, dan baris hasilnya dikembalikan ke agen.

Read-only secara default. Operasi tulis hanya berjalan dalam mode yang Anda aktifkan sendiri di plugin, dan mode itu bersifat sementara. Agen tidak pernah memegang kredensial database Anda.

Musik dari #Uppbeat Shine oleh Swoop: https://uppbeat.io/t/swoop/shine

Tips

Auto mode beta: aktifkan secara eksplisit persetujuan otomatis untuk subset baca PostgreSQL yang terbatas. Pemeriksaan lokal dan Jev harus sama-sama lolos. Lihat Auto mode untuk penyiapan, berbagi provider, dan batasannya.

Tiga komponen

Komponen Fungsinya Tempat berjalan
Plugin Beekeeper Studio Menampilkan setiap query yang diusulkan, mengklasifikasikan risikonya, dan menjalankannya pada koneksi Anda setelah disetujui Di dalam Beekeeper Studio
Server MCP Sisi yang menghadap agen: tool yang dipanggil agen untuk mengusulkan query dan mengambil hasilnya Di mesin Anda, dijalankan oleh agen Anda
Skill agen Mengajari agen mana pun untuk memakai tool tersebut dengan baik Di folder skills agen Anda

Ketiganya dirilis bersama dalam satu versi, dan berguna jika dipakai bersama: plugin tanpa server tidak punya apa pun untuk disetujui, server tanpa plugin tidak punya siapa pun untuk ditanya.

Mengapa

  • Persetujuan manual secara default. Auto mode bersifat opsional dan sementara. Sumber persetujuan dan atribusi evaluator yang tersedia dicatat.
  • Tidak ada kredensial database yang keluar dari Beekeeper. Query berjalan melalui koneksinya yang sudah terautentikasi. Arahkan Beekeeper ke read replica atau role read-only sebagai pengaman tambahan.
  • Risiko diklasifikasikan, bukan diasumsikan. Parser yang memahami dialek memilah setiap query menjadi baca, tulis, atau destruktif, dan tombol Approve tetap terkunci sampai mode yang sesuai diaktifkan.

Cara kerjanya

  MCP client                     Gatekeeper server (127.0.0.1)          Beekeeper Studio
 ┌────────────────────┐   MCP    ┌───────────────────────────┐  fetch   ┌────────────────────┐
 │ submit_query(sql)  │ ───────► │ MCP server + HTTP broker  │ ◄─────── │ Plugin (iframe)    │
 │ get_query_result() │ ◄─────── │ SQLite lease queue + audit│  poll    │ 1. show SQL        │
 │ cancel_query()     │          │ /pending /executing       │ ───────► │ 2. human approves  │
 │                    │          │ /result  /lease/renew     │  result  │ 3. runQuery()      │
 └────────────────────┘          └───────────────────────────┘          │ 4. post result     │
                                                                        └────────────────────┘
  1. Agen mengirim usulan dan langsung mendapat request id. Tidak ada yang memblokir.
  2. Plugin melakukan polling ke broker lokal, mengklaim usulan dengan lease, lalu menampilkan SQL-nya.
  3. Anda menyetujui atau menolak. Jika disetujui, Beekeeper menjalankan query pada koneksi Anda.
  4. Plugin mengirim hasilnya kembali, dan agen mengambilnya saat sudah siap.

Plugin berjalan di iframe yang di-sandbox, sehingga tidak pernah bisa menerima koneksi masuk: plugin melakukan polling ke broker sebagai gantinya. Satu batasan itulah yang menjelaskan seluruh desainnya. Detail lengkap ada di Architecture.

Memulai

Prasyarat: Beekeeper Studio >= 5.4 dan Node >= 22. Jika Anda memakai Claude Code atau Codex CLI, Node sudah terpasang. Tidak ada layanan latar belakang yang perlu diinstal: agen Anda menjalankan server saat sesinya dibuka, dan server berhenti saat sesi itu berakhir.

Peringatan

Untuk saat ini hanya macOS. Gatekeeper dikembangkan dan diuji di macOS. Windows dan Linux belum diuji, jadi anggap belum didukung sampai ada yang melaporkan. Tidak ada kode yang khusus macOS (server mencari path dari direktori home Anda, plugin adalah webview Beekeeper standar), jadi keduanya diharapkan berfungsi, tetapi diharapkan belum berarti terverifikasi. Laporan dari kedua platform sangat kami harapkan.

Instalasi cepat

Skill khusus akan menyiapkan semuanya untuk Anda: plugin, server MCP, skill pendamping, dan pairing. Tambahkan skills ke agen Anda:

npx skills add Gldywn/gatekeeper

Lalu minta agen Anda menginstal Gatekeeper, atau jalankan skill-nya langsung:

/install-gatekeeper

Skill ini menjalankan setiap langkah yang diizinkan lingkungan Anda dan memberi checklist singkat untuk sisanya, seperti me-restart Beekeeper. Nantinya, /update-gatekeeper memeriksa ketiga komponen dan hanya memperbarui yang tertinggal.

Instalasi manual

Lebih suka melakukannya sendiri, atau ingin melihat persis apa yang terjadi?

Penting

Belum ada di registry plugin Beekeeper. Pengajuan sedang diproses bersama maintainer Beekeeper. Sampai disetujui, Manage Plugins tidak akan menampilkan Gatekeeper dan instalasi sekali klik belum tersedia, jadi langkah 1 di bawah adalah cara manualnya. Selebihnya sama.

1. Instal plugin di Beekeeper Studio. Download gatekeeper-<version>.zip dari rilis terbaru, ekstrak ke folder plugins Beekeeper, lalu restart Beekeeper:

OS Folder plugins
macOS ~/Library/Application Support/beekeeper-studio/plugins/
Linux ~/.config/beekeeper-studio/plugins/
Windows %APPDATA%\beekeeper-studio\plugins\

Folder hasil ekstrak harus bernama persis gatekeeper. File zip terekstrak menjadi gatekeeper-<version>/, jadi ganti namanya setelah diekstrak. Beekeeper mencocokkan nama folder dengan id plugin dan melewati folder yang tidak cocok tanpa pemberitahuan apa pun: tanpa error, tanpa entri di Manage Plugins, tanpa apa pun untuk diklik. Inilah penyebab paling umum instalasi manual seolah tidak berbuat apa-apa.

2. Daftarkan server MCP ke agen Anda. Ini sekaligus instalasi server: npx mengunduh dan menyimpannya di cache saat pertama kali dijalankan.

# Claude Code
claude mcp add gatekeeper --scope user -- npx -y @gldywn/gatekeeper-mcp-server

# Codex CLI, in ~/.codex/config.toml
[mcp_servers.gatekeeper]
command = "npx"
args = ["-y", "@gldywn/gatekeeper-mcp-server"]

Lebih suka pnpm? pnpm dlx @gldywn/gatekeeper-mcp-server adalah padanan langsung dari baris npx. Agar paket hanya di-resolve sekali dan tidak setiap kali agen dijalankan, instal dengan pnpm add -g @gldywn/gatekeeper-mcp-server lalu arahkan client Anda ke binary gatekeeper-mcp-server yang ditambahkan ke PATH Anda.

Client apa pun yang membaca .mcp.json bisa memakai .mcp.json.example apa adanya. Kunci versinya (@gldywn/gatekeeper-mcp-server@<version>) jika Anda lebih suka mengaudit upgrade daripada langsung menerimanya: tanpa dikunci, npx mengambil rilis terbaru setiap kali agen dijalankan, yang membuat Anda selalu up to date tetapi berarti proses yang punya akses ke database Anda bisa berubah tanpa Anda sadari.

3. Instal skill agen.

npx skills add Gldywn/gatekeeper

CLI-nya interaktif: menanyakan agen mana yang akan diinstal dan apakah instalasi dilakukan secara global. Berfungsi di Claude Code, Codex, Cursor, dan lainnya.

4. Pairing plugin, sekali per mesin. Jalankan agen Anda, lalu minta apa saja yang membutuhkan database. Sampai plugin di-pairing, setiap tool Gatekeeper menjawab dengan kode 6 digit: ketik kode itu di plugin (Tools -> Gatekeeper). Kode hanya bisa dipakai sekali dan berlaku sekitar lima menit, dan http://127.0.0.1:9999/pair selalu menampilkan kode yang berlaku. Capability token yang diserahkan disimpan di penyimpanan terenkripsi Beekeeper.

Port tersebut tidak akan merespons sampai agen Anda menjalankan server setidaknya sekali. Jika Anda membuka plugin sebelum itu, plugin akan memberi tahu Anda, alih-alih menampilkan kolom pairing yang tidak bisa diproses.

5. Gunakan. Minta agen Anda sesuatu yang membutuhkan database. Agen mengusulkan SQL, query muncul di plugin, Anda menyetujui, dan baris hasilnya dikembalikan ke agen. Operasi baca langsung berfungsi; operasi tulis hanya berjalan setelah Anda mengaktifkan mode Write atau Destructive.

Cara build dari source didokumentasikan di Development.

Jika plugin tidak pernah muncul

Sistem plugin Beekeeper dikunci secara default, jadi instalasi baru bisa saja mengabaikan plugin pihak ketiga sepenuhnya. Ada tiga hal yang perlu dicek, berurutan:

1. Nama folder. Harus persis gatekeeper, bukan gatekeeper-0.1.1. Nama yang tidak cocok dilewati diam-diam, seperti dijelaskan di atas.

2. Sistem plugin aktif. Default bawaan Beekeeper mengatur pluginSystem.disabled = true, dengan allowlist yang hanya berisi dua plugin miliknya sendiri. Tambahkan ini ke config pengguna Anda, lalu restart:

[pluginSystem]
disabled = false

3. Plugin komunitas aktif. communityDisabled = true juga merupakan default bawaan, dan menonaktifkan plugin apa pun yang dikategorikan Beekeeper sebagai komunitas. Jika plugin manager menampilkan “Community plugins are disabled via configuration”, tambahkan communityDisabled = false di blok yang sama.

OS File config pengguna
macOS ~/Library/Application Support/beekeeper-studio/user.config.ini
Linux ~/.config/beekeeper-studio/user.config.ini
Windows %APPDATA%\beekeeper-studio\user.config.ini

Mode akses

Secara default, setiap query memerlukan klik manusia pada teksnya. Mode eksekusi menentukan kelas risiko mana yang boleh berjalan. Auto mode terpisah dan memaksa Read only selama aktif.

Mode Menyetujui Diaktifkan oleh
Read (default) SELECT dan sejenisnya Tidak perlu apa-apa
Write INSERT, UPDATE Anda, di plugin, dengan konfirmasi kedua
Destructive DELETE, DROP, TRUNCATE, ALTER Anda, di plugin, dengan konfirmasi kedua

Mode yang aktif hanya disimpan di memori, tidak pernah dipersistenkan, dan kembali ke read-only saat berganti koneksi atau pairing ulang. Plugin mengklasifikasikan dan memeriksa ulang tepat saat eksekusi, sehingga mengaktifkan dan menonaktifkan mode langsung berlaku.

Kartu membacakan query untuk Anda, sehingga keputusan cukup diambil sekilas tanpa harus menelaah dengan cermat. SQL tampil terformat dan di-highlight, dengan karakter tak terlihat dan pembalik arah ditampilkan sebagai penanda eksplisit, jadi yang Anda baca adalah yang dijalankan. Pernyataan tulis atau destruktif diberi badge kelas berwarna serta menyebut verb dan tabel targetnya, dan pernyataan yang tidak bisa dibaca parser akan disebutkan dalam teks tetap dan diperlakukan sebagai destruktif.

Di bawah SQL, anotasi menyebut tabel yang dibaca query dan kolom sensitif di antaranya: data pribadi dengan satu warna aksen, data perusahaan dan komersial dengan warna lain, nilai sensitif tetap ditandai meski hanya muncul di filter WHERE, dan SELECT * diperluas ke kolom sebenarnya sehingga tidak ada yang bersembunyi di balik bintang. Titik pada ikon database di header menunjukkan apakah pemeriksaan koneksi terakhir lolos, dan ikon itu membuka detailnya: pemeriksaan tersebut, lalu tiga lapisan read-only (mode yang aktif, koneksi Beekeeper, dan endpoint database). Ikon robot di sebelahnya menunjukkan koneksi ke server Gatekeeper tempat agen Anda mengirim query. Warnanya hijau saat server merespons, kuning saat menyambung, dan dicoret merah saat tidak terjangkau, dan mengarahkan kursor ke ikon menampilkan kapan server terakhir merespons.

Setiap detektor bisa diaktifkan atau dinonaktifkan di pengaturan plugin, semuanya berjalan di mesin Anda, dan apa pun yang ditemukan tidak pernah dikirim ke agen. Detektor mencocokkan nama kolom dan pola nilai, jadi anggap sebagai petunjuk cepat untuk hal yang perlu dicek ulang, bukan bukti bahwa query aman. Tidak adanya tanda juga bisa berarti anotasi tidak pernah berhasil diproses.

Keamanan

  • Gerbang berada di tempat eksekusi. Plugin adalah satu-satunya komponen yang bisa menjalankan query, jadi di situlah classifier dan pemeriksaan mode berada.
  • Capability token di setiap request. Broker menjawab 401 tanpa token. Token dibuat saat pertama kali dijalankan, disimpan dengan izin 0600 di bawah ~/.gatekeeper, dan dipegang plugin di penyimpanan terenkripsi Beekeeper.
  • Pairing dengan kode. Broker tidak bisa membedakan plugin dari halaman web mana pun yang Anda kunjungi, jadi token dikirim lewat saluran yang tidak bisa diamati halaman: kode 6 digit sekali pakai yang Anda baca dengan mata sendiri, berlaku lima menit, dan hangus setelah lima kali salah tebak.
  • Hanya loopback. Broker bind ke 127.0.0.1 dan menolak header Host yang tidak terduga, sehingga halaman DNS-rebinding mendapat 421.
  • Hasil dibatasi, audit minimal. Baris yang diteruskan dibatasi jumlah dan ukuran byte-nya sehingga pembacaan massal tidak membanjiri konteks agen. Audit yang menghadap agen menyimpan keputusan dan digest SQL, tidak pernah SQL mentah maupun baris data.

Read bukan jaminan tanpa efek samping: SELECT bisa memanggil fungsi volatile, dan karena itulah persetujuan dilakukan pada SQL yang terlihat. SECURITY.md berisi threat model, batas kepercayaan same-user, periode retensi, dan kebijakan supply chain.

Dokumentasi

Dokumen Isinya
Architecture Dua saluran, loop persetujuan, antrean lease, batas hasil
MCP tools Setiap tool yang bisa dipanggil agen, bentuk tiket, kontrak menunggu
Configuration Variabel lingkungan dan notifikasi desktop
Keamanan Threat model, batas kepercayaan, retensi, supply chain
Development Build dari source, wiring dev, struktur repo, tech stack
Releasing Bagaimana sebuah commit menjadi rilis plugin dan paket npm

Development

pnpm install
pnpm build     # both packages
pnpm ci        # typecheck + build + test

pnpm dev:link mengarahkan Beekeeper ke checkout Anda dan pnpm dev menjalankan UI plugin dengan hot reload. Penyiapan lengkap, termasuk database uji, ada di Development.

Lisensi

MIT