Cara install OpenHands di VPS pakai Docker

Apa itu OpenHands, dan satu risiko yang harus dipahami terlebih dahulu

OpenHands, sebelumnya OpenDevin, adalah agen rekayasa perangkat lunak otonom. Anda memberikan tugas dalam bahasa manusia, dan ia akan merencanakan pekerjaan, menulis kode, menjalankan perintah, membaca output, dan melakukan iterasi hingga tugas selesai. Anda menjalankannya di server sendiri menggunakan Docker dan menghubungkannya ke model bahasa. Pada VPS, ia menjadi agen pengodean yang bekerja saat Anda sedang tidak aktif.

Satu fakta harus menentukan seluruh pengaturan Anda. OpenHands tidak hanya menyarankan kode, ia menjalankannya, dan untuk melakukan itu kontainer controller melakukan mount host Docker socket pada /var/run/docker.sock agar dapat membuat kontainer sandbox untuk setiap tugas. Segala sesuatu yang dapat berkomunikasi dengan Docker socket dapat memulai kontainer baru yang melakukan mount seluruh filesystem host Anda, yang berarti akses socket secara efektif adalah root pada mesin tersebut. Jadi, perlakukan server OpenHands sebagai server yang menjalankan kode yang tidak tepercaya, karena itulah yang sebenarnya ia lakukan. Setiap pilihan pengamanan di bawah ini didasarkan pada hal tersebut.

Apa yang Anda butuhkan

Anda membutuhkan VPS yang menjalankan Ubuntu 24.04 dengan Docker Engine versi terbaru, minimal 4 GB RAM, dan API key untuk model bahasa (OpenAI, Anthropic, atau Google), atau model lokal yang disajikan oleh Ollama pada VPS yang sama. OpenHands mendukung puluhan backend model, jadi pilihannya ada di tangan Anda. Jika Anda belum pernah mengatur kontainer sebelumnya, dasar-dasar Docker pada VPS mencakup materi yang diasumsikan dalam panduan ini.

Instal dengan Docker

OpenHands hadir dalam dua image: image aplikasi yang Anda jalankan, dan image agent-server yang ditarik untuk menjalankan sandbox setiap tugas. Jalankan dengan cara berikut, dengan mengganti tag saat ini dari dokumentasi proyek:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Dua detail ini akan menghemat satu jam kebingungan Anda. Image aplikasi dan image agent-server sengaja memiliki nomor versi yang berbeda, jadi jangan mencoba menyamakannya: gunakan tag agent-server yang dipasangkan dengan versi aplikasi Anda dalam dokumentasi. Dan perhatikan -p 127.0.0.1:3000:3000 alih-alih -p 3000:3000. Perubahan tunggal tersebut adalah perbedaan antara Web UI yang hanya bisa diakses oleh Anda dan Web UI yang bisa diakses oleh seluruh internet, yang akan dibahas pada bagian berikutnya.

Jauhkan Web UI dari internet publik

OpenHands menyajikan antarmukanya pada port 3000. Antarmuka tersebut menggerakkan agen yang menjalankan kode, sehingga mempublikasikannya ke internet memberikan akses jarak jauh kepada siapa pun yang menemukannya ke dalam proses yang mengeksekusi perintah. Ikat ke loopback, seperti yang dilakukan perintah run di atas, dan akses dari laptop Anda melalui terowongan SSH:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Kemudian buka http://127.0.0.1:3000 pada mesin Anda sendiri. Lalu lintas berjalan melalui sesi SSH Anda yang sudah ada, dan tidak ada layanan baru yang mendengarkan di internet publik. Untuk pengaturan yang lebih permanen, gunakan VPN sebagai gantinya. Apa pun caranya, pasang firewall default-deny di depan server agar tidak ada yang terekspos secara tidak sengaja, dan ingatlah bahwa firewall yang hanya mencakup IPv4 akan membiarkan port yang sama terbuka pada IPv6, yang merupakan celah firewall IPv6 yang menjebak banyak orang.

Isolasi kunci model dan kredensial repositori apa pun

OpenHands membutuhkan API key untuk modelnya, dan sering kali membutuhkan token untuk melakukan clone dan push ke repositori Anda. Keduanya dapat menghabiskan uang dan bertindak sebagai Anda, jadi perlakukan keduanya seperti kata sandi. Simpan di dalam file environment yang hanya dapat dibaca oleh akun yang tepat, jangan pernah di dalam perintah run karena akan masuk ke riwayat shell dan daftar proses, dan jangan pernah di dalam file di dalam repositori git.

Jalankan pada mesin yang bisa Anda buang

Karena controller harus memegang Docker socket, Anda tidak dapat mengisolasi OpenHands sepenuhnya dari host-nya. Mitigasi yang jujur adalah isolasi melalui penempatan: jalankan OpenHands pada VPS khusus yang tidak menyimpan hal penting lainnya, bukan pada server yang juga menjalankan database atau situs web Anda. Ambil snapshot sebelum memulai, dan bangun ulang dari snapshot tersebut daripada mempercayai mesin yang telah menjalankan kode buatan agen selama seminggu. VPS murah, sekali pakai, dan tujuan tunggal adalah tempat yang tepat untuknya.

Perkuat keamanan mesin di sekitarnya

Sisanya adalah higiene server standar, dan ini lebih penting di sini daripada biasanya karena beban kerja ini lebih berisiko dari biasanya. Buat pengguna admin tanpa hak istimewa (unprivileged) alih-alih bekerja sebagai root, ikuti menjalankan layanan sebagai pengguna tanpa hak istimewa. Ubah SSH ke autentikasi berbasis kunci saja. Kemudian jalankan checklist di bawah ini dan simpan di tempat yang akan Anda lihat lagi.

Untuk memahami bagian-bagian yang bergerak alih-alih hanya menjalankannya, lihat membangun agen AI Anda sendiri pada VPS; untuk platform dengan sedikit kode, self-hosting Dify adalah cara masuk yang lebih ringan.

FAQ

Apakah OpenHands aman untuk dijalankan di server?

Bisa, dengan kehati-hatian, tetapi ini lebih berisiko daripada aplikasi web biasa karena ia menulis dan menjalankan kode dan controllernya memegang host Docker socket, yang secara efektif adalah root pada mesin tersebut. Jalankan pada VPS khusus yang dapat dibuang yang tidak menyimpan hal berharga lainnya, jaga Web UI tetap pada loopback di balik terowongan SSH atau VPN, isolasi kunci-kuncinya, dan perkuat keamanan mesinnya. Jangan menjalankannya berdampingan dengan layanan penting Anda.

Mengapa OpenHands membutuhkan Docker socket?

OpenHands menjalankan setiap tugas dalam kontainer sandbox baru, dan ia meminta Docker daemon host untuk membuat kontainer tersebut dengan melakukan mount /var/run/docker.sock ke dalam controllernya. Hal ini memberikan kontainer controller kendali atas Docker pada host, yang sangat kuat dan berisiko, sehingga host itu sendiri harus diperlakukan sebagai mesin yang menjalankan kode yang tidak tepercaya.

Bisakah OpenHands menggunakan model lokal alih-alih API berbayar?

Ya. OpenHands mendukung model lokal yang disajikan oleh Ollama atau vLLM, sehingga Anda dapat menjalankannya secara mandiri sepenuhnya tanpa biaya per-token dan tanpa data keluar dari server Anda. Anda membutuhkan mesin dengan memori yang cukup untuk model pengodean yang mumpuni, yang merupakan pertanyaan ukuran yang sama seperti yang dibahas dalam panduan Ollama.

Haruskah saya menjalankan OpenHands di server utama saya?

Tidak. Karena ia menjalankan kode buatan agen dan memegang Docker socket, simpanlah pada VPS terpisah dengan tujuan tunggal yang siap Anda bangun ulang. Menempatkannya bersama database, situs web, atau layanan Anda lainnya berarti kesalahan oleh agen, atau bug di dalamnya, dapat menjangkau hal-hal yang tidak seharusnya ia sentuh.