Cara Self-Host Open Connector untuk Agen AI

Apa yang dilakukan Open Connector untuk agen AI

Menjalankan Open Connector secara mandiri menempatkan satu gateway autentikasi antara agen AI dan setiap API software as a service (SaaS) yang mereka panggil. Dengan demikian, agen tidak pernah menyimpan token provider. Open Connector adalah gateway dengan kode sumber yang tersedia dari OOMOL Lab. Saat ini, lisensinya menggunakan Apache 2.0 yang dimodifikasi dengan ketentuan tambahan. Rilis hingga v1.9.4 tetap menggunakan Apache 2.0. Perubahan tersebut diperkenalkan pada v1.9.5. Penyediaan layanan hosted atau managed yang nilai utamanya berasal dari fungsi OpenConnector memerlukan lisensi komersial dari OOMOL. Open Connector berjalan sebagai satu container, menyimpan statusnya dalam satu file SQLite, serta menyediakan action provider melalui HTTP dan MCP (model context protocol).

Masalah mulai muncul pada integrasi kedua. Setiap provider memiliki alur OAuth (open authorization), masa berlaku refresh token, dan nama scope sendiri. Menghubungkan lima provider ke agen secara manual berarti membuat lima redirect handler, lima credential store, dan lima refresh loop yang harus berjalan sebelum token kedaluwarsa. Hampir tidak ada yang menulis kode tersebut. Mereka membuat satu personal access token yang berumur panjang untuk setiap service, lalu menempelkannya ke konfigurasi agen, file environment, atau prompt itu sendiri. Token tersebut kemudian dapat dibaca oleh setiap tool yang dijalankan agen dan masuk ke transcript. Inilah kegagalan yang dijelaskan dalam menjaga secret tetap berada di luar agen AI.

Gateway autentikasi memisahkan credential menjadi dua bagian. Gateway menyimpan credential provider dan menjalankan alur OAuth. Agen menerima runtime token yang hanya valid untuk gateway. Saat agen memanggil suatu action, gateway memuat credential yang tersimpan, menyisipkannya ke dalam request keluar di sisi server, lalu hanya mengembalikan response body. Agen tidak pernah menerima access token provider. Dengan demikian, transcript agen yang bocor hanya menyebabkan Anda kehilangan satu runtime token yang dapat dicabut, bukan akun GitHub Anda.

Katalog tersebut mencantumkan lebih dari 1,000 provider dan 10,000 action siap pakai. Angka ini berasal dari proyek itu sendiri dan tidak dapat Anda verifikasi dari luar. Hal yang dapat diverifikasi adalah strukturnya: satu endpoint HTTP untuk setiap action, satu koneksi tersimpan untuk setiap provider, dan satu token untuk setiap agen. Jika sisi agen masih baru bagi Anda dan istilah seperti tool call atau MCP server belum sepenuhnya mapan, tahapan dalam cara mempelajari agen AI dari awal membangun loop, tool, dan kebiasaan keamanan yang diasumsikan sudah Anda miliki oleh gateway seperti ini.

Mengapa melakukan self-hosting Open Connector daripada menggunakan layanan connector yang di-host

Layanan connector yang di-host melakukan pekerjaan yang sama dan menyimpan refresh token untuk setiap provider yang Anda hubungkan. Refresh token untuk Google atau GitHub adalah kunci berumur panjang ke email dan repositori Anda. Jika layanan tersebut mengalami breach, Anda juga terdampak. Dengan self-hosting, catatan tersebut dipindahkan ke SQLite pada mesin yang Anda sewa dan administrasikan. Catatan itu dilindungi dengan key yang tidak pernah meninggalkan mesin Anda.

Sebutkan biayanya secara jelas sebelum memulai. VPS ini menjadi server paling berharga yang Anda jalankan. Server ini menyimpan kredensial aktif untuk belasan layanan dalam satu file. Karena itu, perlakukan server ini seperti host password manager: firewall hanya membuka 443, tidak ada login bersama, backup yang benar-benar pernah Anda pulihkan, dan alert saat server berhenti merespons. Jika Anda tidak bersedia menempatkan password vault di mesin ini, jangan tempatkan connector di mesin ini.

Sematkan versi sebelum menginstal apa pun

Open Connector masih tergolong baru. Panduan ini menetapkan v1.3.3, yang diterbitkan pada 30 July 2026, sebagai snapshot instalasi bertanggal 1 August 2026. Versi tersebut bukan lagi rilis terbaru. Registry juga menyediakan tag tip, yang dibuat dari commit terbaru pada main.

Pada proyek yang masih baru seperti ini, tag yang terus diperbarui sering berubah. docker compose pull yang melompati dua rilis dapat mengubah endpoint yang diandalkan agent Anda, sehingga Anda akan menghabiskan waktu untuk men-debug masalah tersebut dan mengira penyebabnya ada pada agent. Sematkan image ke tag rilis, lalu lakukan upgrade saat Anda memutuskan untuk melakukannya, setelah membaca catatan rilis.

Deploy Open Connector di balik TLS pada VPS Anda sendiri

Sebelum container dijalankan, Anda memerlukan:

• Docker Engine 28.0.0 atau yang lebih baru dengan plugin Compose, pada Ubuntu 24.04 atau distribusi yang serupa
• hostname yang A record-nya mengarah ke VPS ini, misalnya connect.example.com
• reverse proxy yang sudah melakukan terminasi TLS (transport layer security) untuk hostname tersebut
• dua secret acak yang dibuat di bawah

Panduan reverse proxy Traefik untuk beberapa aplikasi Docker Compose membahas sisi proxy. Konfigurasi sertifikat yang sama, dari awal hingga akhir untuk satu aplikasi, tersedia dalam panduan n8n pada VPS dengan Docker dan HTTPS.

Buat secret terlebih dahulu. Encryption key mengenkripsi kredensial yang tersimpan. Admin token melindungi konsol web dan seluruh permukaan /api. Keduanya tidak memiliki nilai default, dan runtime dapat berjalan tanpa keduanya.

mkdir -p ~/open-connector && cd ~/open-connector
umask 077
printf 'OOMOL_CONNECT_ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" > .env
printf 'OOMOL_CONNECT_ADMIN_TOKEN=%s\n' "$(openssl rand -base64 32)" >> .env
chmod 600 .env

Salin kedua nilai tersebut ke password manager sekarang, sebelum start pertama. Encryption key tidak memiliki jalur pemulihan. Alasannya dijelaskan dalam daftar kegagalan di bawah.

Sekarang compose.yaml. Konfigurasi ini berbeda dari contoh upstream pada dua bagian, dan keduanya penting.

services:
  connector:
    image: ghcr.io/oomol-lab/open-connector:v1.3.3
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - connector-data:/app/data
    environment:
      OOMOL_CONNECT_DATA_DIR: /app/data
      OOMOL_CONNECT_ORIGIN: "https://connect.example.com"
      OOMOL_CONNECT_ENCRYPTION_KEY: "${OOMOL_CONNECT_ENCRYPTION_KEY:?set this in .env}"
      OOMOL_CONNECT_ADMIN_TOKEN: "${OOMOL_CONNECT_ADMIN_TOKEN:?set this in .env}"

volumes:
  connector-data:

Perubahan pertama adalah tag yang dikunci versinya, bukan latest. Perubahan kedua adalah port. File upstream memublikasikan 3000:3000, yang mengikat semua interface pada host. Docker menulis port yang dipublikasikan ke tabel NAT (network address translation) sebelum paket mencapai rantai filter ufw. Karena itu, ufw deny 3000 tidak menutup port tersebut. Perangkap ini dijelaskan dalam alasan port Docker melewati ufw. Penulisan 127.0.0.1:3000:3000 memublikasikan port hanya pada interface loopback, dan reverse proxy Anda terhubung dari host yang sama. Sebelum Docker Engine 28.0.0, host pada segmen L2 yang sama dapat mengakses port yang dipublikasikan ke localhost. Karena itu, panduan ini memerlukan versi 28.0.0 atau yang lebih baru.

:? menandai setiap variabel sebagai wajib. Dengan demikian, stack menolak start ketika .env tidak ada, alih-alih start dengan kredensial yang tidak terenkripsi. Menyimpan nilai dalam .env, bukan dalam file compose, mengikuti pola dari file env dan secret Docker Compose. Jaga /v1 dan /mcp tetap privat di reverse proxy sampai Anda membuat token runtime pertama di bawah.

docker compose up -d
docker compose logs -n 30 connector
curl -s http://127.0.0.1:3000/health
sudo ss -tlnp | grep 3000

/health menjawab { "ok": true } setelah runtime aktif. ss harus mencetak 127.0.0.1:3000. Baris yang berbunyi 0.0.0.0:3000 berarti listener terikat pada setiap interface IPv4, tetapi tidak membuktikan bahwa layanan dapat dijangkau dari Internet. Firewall upstream atau aturan dalam rantai DOCKER-USER milik Docker masih dapat memblokir trafik eksternal. Jika health check mengembalikan connection refused, berarti container belum melakukan listen. Baca log sebelum mengubah konfigurasi proxy.

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.connector.rule=Host(`connect.example.com`)"
      - "traefik.http.routers.connector.entrypoints=websecure"
      - "traefik.http.routers.connector.tls.certresolver=le"
      - "traefik.http.services.connector.loadbalancer.server.port=3000"

Mengapa callback OAuth memerlukan origin yang benar

OOMOL_CONNECT_ORIGIN adalah pengaturan yang sering dilewati. Jika pengaturan ini dilewati, OAuth gagal dengan cara yang tampak seperti bug pada provider. Runtime membangun URI pengalihan dari origin tersebut, dalam format <origin>/oauth/callback. Jika tidak diatur, origin defaultnya adalah http://localhost:3000. Akibatnya, runtime mengirimkan URI pengalihan http://localhost:3000/oauth/callback kepada provider, sedangkan aplikasi OAuth Anda mendaftarkan https://connect.example.com/oauth/callback. Kedua string tersebut berbeda, sehingga GitHub memberikan respons:

The redirect_uri MUST match the registered callback URL for this application.

Provider OAuth mengalihkan browser kembali ke URI tersebut. Karena itu, alamat tersebut harus dapat dijangkau oleh browser. OAuth tidak selalu memerlukan hostname publik: OpenConnector mendokumentasikan callback GitHub pada http://localhost:3000/oauth/callback. Deployment VPS ini menggunakan hostname dan sertifikat agar browser dapat menjangkau gateway melalui origin HTTPS-nya. Atur origin sebelum start pertama, karena nilainya dibaca saat startup. Setelah mengedit .env atau compose.yaml, jalankan kembali docker compose up -d untuk menerapkan perubahan.

Hubungkan provider pertama melalui OAuth

Buat aplikasi OAuth terlebih dahulu di provider. Di GitHub, buka Settings, lalu Developer settings, kemudian OAuth Apps, dan pilih New OAuth App. Tetapkan URL callback otorisasi ke https://connect.example.com/oauth/callback. Simpan client ID dan client secret.

Setiap panggilan /api membawa admin token, jadi ekspor token tersebut sekali untuk sesi shell.

export ADMIN_TOKEN='paste-the-admin-token'
curl -s https://connect.example.com/api/oauth/configs \
  -H "authorization: Bearer $ADMIN_TOKEN"

Daftar tersebut menampilkan URI pengalihan yang diharapkan runtime untuk setiap provider. Ini adalah pemeriksaan tercepat untuk memastikan origin Anda sudah diterapkan. Jika masih menampilkan localhost, container berjalan dengan nilai lama dan alur OAuth akan gagal pada langkah terakhir.

Simpan kredensial client, lalu mulai proses otorisasi.

curl -s -X PUT https://connect.example.com/api/oauth/configs/github \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

curl -s -X POST https://connect.example.com/api/oauth/authorizations \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

Panggilan kedua mengembalikan authorizationUrl. Buka URL tersebut di browser, setujui scope, lalu provider mengarahkan browser kembali ke /oauth/callback. Pada tahap ini, runtime menukar code dan menyimpan kredensial. Web console pada origin Anda menjalankan langkah yang sama melalui formulir dengan admin token yang sama. Provider yang menggunakan API key biasa tidak memerlukan semua langkah ini: PUT /api/connections/<service> dengan {"authType":"api_key","values":{"apiKey":"..."}} menyimpan key secara langsung.

Berikan setiap agen token runtime, jangan pernah memberikan kredensial

Agen melakukan autentikasi ke gateway menggunakan token runtime yang diterbitkan oleh API admin.

curl -s -X POST https://connect.example.com/api/runtime-tokens \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"research-agent"}'

Respons berisi token yang diawali dengan oct_. Terbitkan satu token untuk setiap agen dan beri nama sesuai nama agen tersebut. Jika Anda tidak dapat mengidentifikasi token yang akan dicabut, Anda harus mencabut semuanya. Agen kemudian memanggil action melalui HTTP biasa.

curl -s -X POST https://connect.example.com/v1/actions/github.get_current_user \
  -H "authorization: Bearer oct_..." \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Respons yang sehat berupa envelope dengan field success bernilai true, sedangkan payload provider berada di bawah data. Token GitHub tidak terdapat di mana pun dalam respons tersebut. Untuk klien MCP, arahkan klien ke https://connect.example.com/mcp dengan header bearer yang sama. Gateway menyediakan tool discovery seperti search_actions dan execute_action, bukan satu tool untuk setiap API. Dengan demikian, daftar tool agen tetap kecil. Menjalankan server MCP pada VPS menjelaskan bagian konfigurasi klien tersebut.

Lakukan satu pemeriksaan lagi sebelum menganggap konfigurasi ini selesai. Ulangi pemanggilan action setelah menghapus header authorization. Quickstart proyek tersebut memanggil /v1 tanpa bearer sama sekali. Artinya, instalasi yang tidak mengonfigurasi autentikasi runtime akan menjalankan action untuk siapa pun yang dapat mengakses port tersebut. Jika pemanggilan tanpa autentikasi berhasil, ada dua solusi: konfigurasikan token runtime dan pastikan pemanggilan anonim kini gagal, atau batasi /api, /v1, dan /mcp pada reverse proxy agar hanya dapat diakses dari alamat asal agen Anda. /oauth/callback harus dapat dijangkau oleh browser yang menyelesaikan otorisasi. Endpoint tersebut tidak perlu dibuka untuk seluruh Internet.

Batasi daftar tindakan sesuai kebutuhan agent

Gateway dengan seribu provider di belakangnya memberikan permukaan akses yang terlalu luas kepada language model. Permukaan ini menjadi lebih luas ketika model mulai membaca teks yang tidak ditulisnya sendiri, karena halaman yang dikembalikan oleh instance SearXNG Anda sendiri yang menjawab pencarian web agent dapat berisi instruksi yang ditujukan untuk tindakan apa pun yang diizinkan agent. Prinsip pembatasan yang membuat coding agent melakukan perubahan terkecil yang berfungsi juga berlaku untuk izinnya: berikan hanya beberapa tindakan yang benar-benar diperlukan oleh tugas tersebut, tanpa izin tambahan. Dua kontrol dapat mempersempit akses ini.

OOMOL_CONNECT_ALLOWED_ACTIONS menerima allowlist yang dipisahkan dengan koma serta memahami service.* dan *. OOMOL_CONNECT_BLOCKED_ACTIONS adalah denylist, dan denylist memiliki prioritas. Jika allowlist diatur ke github.get_current_user,github.list_issues, semua tindakan lainnya akan ditolak, apa pun permintaan agent. Inilah perbedaan antara kesalahan dan insiden. Token runtime memiliki aturan tindakan sendiri di atas aturan global, dan daftar allowedProxies miliknya kosong secara default. Karena itu, POST /v1/proxy/:service ditolak sampai Anda memberikan izin. Endpoint proxy tersebut meneruskan request mentah ke provider dengan kredensial Anda terlampir. Biarkan daftar ini kosong kecuali ada agent tertentu yang memerlukannya.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK default-nya adalah false. Pengaturan ini mencegah koneksi ke provider yang di-host sendiri mengarah ke alamat privat, seperti layanan metadata cloud pada 169.254.169.254 atau database Anda di jaringan yang sama. Biarkan pengaturan ini nonaktif. Aktifkan hanya untuk provider yang Anda host sendiri.

Cadangkan server yang menyimpan semua token

Ada dua hal yang penting, dan masing-masing tidak berguna tanpa yang lain. Database di /app/data/connect.sqlite dalam volume connector-data menyimpan kredensial yang disegel. Kunci enkripsi di .env membukanya. Cadangan volume tanpa kunci tidak dapat memulihkan apa pun, dan kunci tanpa volume juga tidak dapat memulihkan apa pun. Karena itu, simpan kunci di password manager dan masukkan volume ke dalam rotasi pencadangan rutin.

Hentikan container saat menyalin file SQLite. Salinan yang dibuat saat proses penulisan berlangsung dapat dipulihkan sebagai database yang rusak.

docker volume ls | grep connector-data
docker compose stop connector
docker run --rm -v open-connector_connector-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/connector-data.tgz -C /data .
docker compose start connector

Nama volume adalah direktori proyek Anda ditambah _connector-data. Karena itu, perintah pertama ada di sini: tempel nama sebenarnya ke dalam perintah ketiga. Kirim arsip keluar dari VPS menggunakan pencadangan restic dari VPS. Arsip tersebut dienkripsi sebelum meninggalkan VPS karena berisi penyimpanan kredensial.

Runtime menyimpan proses tindakan terbaru sebagai catatan audit, secara default sebanyak 5,000 catatan. Dengan demikian, konsol dapat menunjukkan agen mana yang menjalankan tindakan apa dan kapan. Baca log tersebut terlebih dahulu ketika agen berperilaku tidak semestinya. Arahkan halaman status Uptime Kuma ke https://connect.example.com/health juga. Ketika gateway berhenti merespons, agen gagal dengan cara yang membingungkan. Mengetahui bahwa gateway sedang tidak aktif dapat menghemat waktu satu jam untuk membaca output agen.

Hal-hal yang mengalami kegagalan dan pesan yang akan ditampilkan

redirect_uri_mismatch di provider. Origin dan URL callback yang terdaftar berbeda. Bandingkan string persis dari /api/oauth/configs dengan pengaturan aplikasi provider, termasuk https terhadap http dan slash di bagian akhir.

Setiap pemanggilan /api mengembalikan 401. Header token admin tidak ada atau salah eja. Header tersebut adalah Authorization: Bearer <token>, dan konsol web meminta token yang sama.

Container berjalan, dan kredensial tersimpan dalam teks biasa. Ini terjadi ketika OOMOL_CONNECT_ENCRYPTION_KEY tidak pernah sampai ke container, karena runtime menyimpan catatan kredensial tanpa enkripsi, bukan menolak untuk start. Buktikan pada instalasi Anda sendiri: hubungkan provider dengan API key yang dapat Anda kenali, lalu cari key tersebut di database.

docker compose cp connector:/app/data/connect.sqlite /tmp/connect.sqlite
grep -c 'github_pat_' /tmp/connect.sqlite
shred -u /tmp/connect.sqlite

Nilai di atas 0 berarti key belum diterapkan. Pastikan .env berada di direktori yang sama dengan compose.yaml dan docker compose config menampilkan nilainya. Setelah key ditetapkan, pencarian yang sama mengembalikan 0 karena catatan tersebut disegel dengan AES-256-GCM (advanced encryption standard, kunci 256-bit, mode Galois/counter).

Tidak ada yang dapat didekripsi setelah pemulihan. Kunci enkripsi berubah atau hilang. Kunci tersebut memang tidak pernah ditulis di sebelah data, sehingga tidak ada jalur pemulihan dan tidak ada tiket dukungan yang dapat membantu. Hubungkan kembali setiap provider. Rotasi didukung melalui variabel key terpisah dan perintah data di runtime. Baca catatan rilis saat ini sebelum melakukan rotasi.

Agent menampilkan error yang menyebut action yang dapat dilihatnya di katalog. Discovery dan eksekusi merupakan proses terpisah. Action dapat muncul di search_actions, tetapi tetap ditolak oleh OOMOL_CONNECT_ALLOWED_ACTIONS, denylist, atau aturan milik token runtime tersebut.

Upgrade. Cadangkan volume, edit image tag ke rilis baru, lalu docker compose pull && docker compose up -d. Pantau docker compose logs -n 50 connector untuk mencari baris migrasi, lalu jalankan kembali health check dan satu action nyata sebelum menggunakannya kembali. Rollback berarti mengembalikan tag lama. Hal ini hanya berfungsi karena tag tersebut dipin.

FAQ

Apakah saya memerlukan domain publik untuk melakukan self-hosting Open Connector?

Untuk provider yang menggunakan API key, tidak: gateway pada 127.0.0.1 sudah cukup. OAuth juga tidak selalu memerlukannya: OpenConnector mendokumentasikan callback lokal GitHub sebagai http://localhost:3000/oauth/callback. Browser yang menyelesaikan otorisasi harus dapat mengakses URL callback tersebut. Untuk deployment VPS ini, tetapkan OOMOL_CONNECT_ORIGIN ke hostname https:// Anda sebelum start pertama, lalu daftarkan <origin>/oauth/callback pada aplikasi OAuth provider.

Apa yang terjadi jika saya kehilangan encryption key Open Connector?

Credential yang tersimpan tidak dapat didekripsi, dan tidak ada pemulihan. Key tersebut sengaja tidak pernah disimpan bersama data, sehingga siapa pun yang memiliki database tidak dapat membacanya, termasuk Anda. Satu-satunya pilihan adalah menetapkan key baru dan menghubungkan ulang setiap provider. Simpan key di password manager dan database dalam rotasi backup Anda, karena proses restore memerlukan keduanya.

Apakah AI agent saya dapat melihat access token provider?

Tidak jika agent memanggil melalui gateway. Agent melakukan autentikasi dengan runtime token yang diawali oct_, lalu gateway menyisipkan credential provider ke dalam request keluar di server dan hanya mengembalikan respons. Dua hal dapat menghilangkan perlindungan tersebut: endpoint /v1/proxy/:service, yang meneruskan raw request dengan credential Anda terlampir dan grant-nya sengaja dimulai dalam keadaan kosong, serta menempelkan API key ke agent secara manual, yang sepenuhnya melewati gateway.

Haruskah gateway dapat diakses dari Internet publik?

Callback OAuth harus dapat dijangkau oleh browser yang menyelesaikan otorisasi. Namun, gateway tidak perlu dapat diakses dari seluruh Internet. Dengan Docker Engine 28.0.0 atau yang lebih baru dan bridge networking default, publish port container pada 127.0.0.1 agar port yang dipublikasikan hanya dapat diakses dari host, lalu tempatkan reverse proxy di depannya. Docker versi lama memungkinkan host pada segmen L2 yang sama mengakses port yang dipublikasikan pada localhost. Selanjutnya, uji satu pemanggilan action tanpa header authorization. Jika berhasil, batasi /api, /v1, dan /mcp pada proxy ke alamat yang digunakan agent Anda sampai hanya pemanggilan yang terautentikasi yang berhasil.

Apakah Open Connector siap digunakan di production?

Release saat ini menggunakan lisensi Apache 2.0 yang dimodifikasi dengan persyaratan tambahan. Release hingga v1.9.4, termasuk v1.3.3 yang dipin, tetap menggunakan Apache 2.0. Layanan connector hosted atau managed yang nilai utamanya adalah fungsionalitas OpenConnector memerlukan lisensi komersial dari OOMOL berdasarkan lisensi saat ini. Perintah instalasi v1.3.3 tetap merupakan snapshot tertanggal 1 August 2026, dan release tersebut dirilis pada 30 July 2026. Jalankan dengan pinned release tag, jangan pernah menggunakan latest atau tip, baca release notes sebelum setiap upgrade, dan simpan backup volume yang sudah pernah Anda restore satu kali. Desain ini tepat untuk server yang Anda miliki. Risikonya terletak pada perubahan versi yang cepat, bukan pada arsitekturnya.