Cara Pasang OpenHands pada VPS dengan Docker

Apakah OpenHands, dan satu risiko yang perlu difahami terlebih dahulu

OpenHands, yang dahulunya dikenali sebagai OpenDevin, ialah ejen kejuruteraan perisian autonomi. Anda memberikan tugasan dalam bahasa biasa, dan ia akan merancang kerja, menulis kod, menjalankan arahan, membaca output, serta melakukan lelaran sehingga tugasan tersebut selesai. Anda menjalankannya pada pelayan anda sendiri menggunakan Docker dan menyambungkannya kepada model bahasa. Pada VPS, ia menjadi ejen pengekodan yang bekerja semasa anda tiada.

Satu fakta harus menentukan keseluruhan persediaan anda. OpenHands bukan sekadar mencadangkan kod, ia menjalankannya, dan untuk berbuat demikian, kontena pengawalnya melekapkan (mount) soket Docker hos pada /var/run/docker.sock supaya ia boleh menjana kontena kotak pasir (sandbox) bagi setiap tugasan. Apa-apa sahaja yang boleh berkomunikasi dengan soket Docker boleh memulakan kontena baharu yang melekapkan keseluruhan sistem fail hos anda, yang bermaksud akses soket secara efektif adalah akses root pada mesin tersebut. Oleh itu, anggap kotak OpenHands sebagai pelayan yang menjalankan kod yang tidak dipercayai, kerana itulah sebenarnya yang ia lakukan. Setiap pilihan pengukuhan (hardening) di bawah adalah berdasarkan perkara tersebut.

Keperluan anda

Anda memerlukan VPS yang menjalankan Ubuntu 24.04 dengan Docker Engine terkini, sekurang-kurangnya 4 GB RAM, dan kunci API untuk model bahasa (OpenAI, Anthropic, atau Google), atau model tempatan yang dihoskan oleh Ollama pada VPS yang sama. OpenHands menyokong berpuluh-puluh backend model, jadi pilihan di tangan anda. Jika anda belum pernah menyediakan kontena sebelum ini, asas Docker pada VPS merangkumi perkara yang diandaikan dalam panduan ini.

Pemasangan dengan Docker

OpenHands diedarkan sebagai dua imej: imej aplikasi yang anda jalankan, dan imej agent-server yang ditarik untuk menjalankan sandbox bagi setiap tugasan. Jalankan seperti berikut, dengan menggantikan tag semasa daripada dokumentasi projek:

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 perincian ini akan menjimatkan masa anda daripada kekeliruan. Imej aplikasi dan imej agent-server sengaja menggunakan nombor versi yang berbeza, jadi jangan cuba untuk menyamakannya: gunakan tag agent-server yang dipadankan oleh dokumentasi dengan versi aplikasi anda. Perhatikan juga -p 127.0.0.1:3000:3000 berbanding -p 3000:3000. Perubahan tunggal itu adalah perbezaan antara UI Web yang hanya boleh dicapai oleh anda dengan UI Web yang boleh dicapai oleh seluruh internet, yang akan dibincangkan dalam bahagian seterusnya.

Pastikan Web UI tidak terdedah kepada internet awam

OpenHands menyediakan antara mukanya pada port 3000. Antara muka tersebut mengawal ejen yang menjalankan kod, jadi menerbitkannya ke internet memberikan sesiapa sahaja yang menemuinya laluan jauh ke dalam proses yang melaksanakan arahan. Ikat ia kepada loopback, seperti yang dilakukan oleh arahan jalankan di atas, dan capai ia dari komputer riba anda melalui SSH tunnel:

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

Kemudian buka http://127.0.0.1:3000 pada mesin anda sendiri. Trafik tersebut melalui sesi SSH sedia ada anda, dan tiada apa-apa yang baharu mendengar pada internet awam. Tidak semua ejen memerlukan port: sesi Claude Code pada VPS yang sama menghantar mesej antara satu sama lain melalui terminal, jadi satu-satunya perkara yang anda dedahkan ialah SSH itu sendiri. Tabiat loopback-dan-tunnel yang sama wajar diamalkan pada setiap papan pemuka ejen yang anda hoskan; mencapai UI pengimbasan open-kritt melalui tunnel berfungsi dengan cara yang sama, cuma pada port 5173. Untuk persediaan yang lebih kekal, letakkan ia di sebalik VPN. Walau apa pun caranya, letakkan firewall default-deny di hadapan kotak tersebut supaya tiada apa-apa yang terdedah secara tidak sengaja, dan ingat bahawa firewall yang hanya meliputi IPv4 membiarkan port yang sama terbuka pada IPv6, iaitu jurang firewall IPv6 yang memerangkap ramai orang.

Asingkan kunci model dan sebarang kelayakan repositori

OpenHands memerlukan kunci API untuk modelnya, dan selalunya token untuk melakukan klon serta menolak (push) ke repositori anda. Kedua-duanya boleh membelanjakan wang dan bertindak bagi pihak anda, jadi layan ia seperti kata laluan. Simpan kunci tersebut dalam fail persekitaran yang hanya boleh dibaca oleh akaun yang betul, jangan sekali-kali meletakkannya dalam arahan jalankan (run command) kerana ia akan tersimpan dalam sejarah shell dan senarai proses, serta jangan sesekali menyimpannya dalam fail di dalam repositori git. Jika anda menyimpan yang asal dalam pengurus kata laluan yang dihoskan sendiri, keraskan pelayan tersebut juga, kerana titik lemah peti besi (vault) adalah token pentadbir dan fail sandarannya, bukannya item yang disulitkan itu sendiri, sebagaimana yang diterangkan dalam pengerasan Vaultwarden.

Jalankan pada pelayan yang boleh dibuang

Oleh kerana pengawal mesti memegang Docker socket, anda tidak boleh mengasingkan OpenHands sepenuhnya daripada hosnya. Mitigasi yang jujur adalah pengasingan melalui penempatan: jalankan OpenHands pada VPS khusus yang tidak mengandungi sebarang data penting, bukan pada pelayan yang menjalankan pangkalan data atau laman web anda. Ambil snapshot sebelum anda bermula, dan bina semula daripada snapshot tersebut dan bukannya mempercayai pelayan yang telah menjalankan kod ciptaan ejen selama seminggu. VPS yang murah, boleh guna semula dan bertujuan tunggal adalah tempat yang sesuai untuknya. Penempatan adalah satu-satunya kawalan yang diberikan oleh OpenHands kepada anda di sini, jadi jika anda juga ingin mengawal sejauh mana ejen boleh bertindak sebelum ia berhenti untuk bertanya, mod kebenaran Claude Code menunjukkan rupa tuil kedua itu pada pelayan yang tidak dipantau oleh sesiapa.

Mengukuhkan persekitaran pelayan

Langkah seterusnya adalah kebersihan pelayan standard, dan ia lebih penting di sini kerana beban kerja yang dikendalikan lebih berisiko daripada biasa. Cipta pengguna pentadbir tanpa keistimewaan (unprivileged) dan elakkan bekerja sebagai root, dengan merujuk kepada menjalankan servis sebagai pengguna tanpa keistimewaan. Tukar pengesahan SSH kepada penggunaan kunci sahaja. Kemudian, jalankan senarai semak di bawah dan simpan di lokasi yang mudah dilihat semula.

Untuk memahami komponen yang terlibat dan bukan sekadar menjalankannya, lihat membina ejen AI anda sendiri pada VPS; bagi platform yang kurang memerlukan pengekodan, self-hosting Dify merupakan titik permulaan yang lebih mudah.

FAQ

Adakah OpenHands selamat untuk dijalankan pada pelayan?

Ia boleh menjadi selamat jika dikendalikan dengan berhati-hati, namun ia lebih berisiko berbanding aplikasi web biasa kerana ia menulis dan menjalankan kod. Pengawalnya memegang soket Docker hos, yang secara efektif memberikan akses root pada mesin tersebut. Jalankan ia pada VPS khusus yang boleh dibuang dan tidak mengandungi data berharga lain. Pastikan UI Webnya berada pada loopback di sebalik terowong SSH atau VPN, asingkan kunci-kuncinya, dan perketatkan keselamatan pelayan tersebut. Jangan jalankan ia bersama perkhidmatan penting anda.

Mengapa OpenHands memerlukan soket Docker?

OpenHands menjalankan setiap tugasan dalam kontena sandbox yang baharu. Ia meminta daemon Docker hos untuk mencipta kontena tersebut dengan melekapkan /var/run/docker.sock ke dalam pengawalnya. Ini memberikan kontena pengawal kawalan ke atas Docker pada hos, yang merupakan kuasa besar dan berisiko. Oleh itu, hos itu sendiri mesti dianggap sebagai mesin yang menjalankan kod yang tidak dipercayai.

Bolehkah OpenHands menggunakan model tempatan dan bukannya API berbayar?

Ya. OpenHands menyokong model tempatan yang dihoskan oleh Ollama atau vLLM. Anda boleh menjalankannya secara self-hosted sepenuhnya tanpa kos per-token dan tiada data yang keluar dari pelayan anda. Anda memerlukan mesin dengan memori yang mencukupi untuk model pengekodan yang berkebolehan, iaitu isu saiz yang sama seperti yang dibincangkan dalam panduan Ollama.

Patutkah saya menjalankan OpenHands pada pelayan utama saya?

Tidak. Kerana ia menjalankan kod yang ditulis oleh ejen dan memegang soket Docker, simpan ia pada VPS berasingan yang dikhaskan untuk tujuan tunggal dan yang anda sanggup untuk bina semula. Menempatkannya bersama pangkalan data, laman web, atau perkhidmatan anda yang lain bermakna kesilapan oleh ejen, atau pepijat di dalamnya, boleh menjejaskan perkara yang tidak sepatutnya disentuh.