Cara pasang OpenHands pada VPS guna Docker

Apa itu OpenHands, dan satu risiko utama yang perlu difahami

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

Satu fakta perlu menentukan keseluruhan tetapan anda. OpenHands bukan sekadar mencadangkan kod, ia menjalankannya, dan untuk melakukan itu, kontena pengendali (controller container) memuatkan (mount) Docker socket hos pada /var/run/docker.sock supaya ia boleh menghasilkan kontena sandbox untuk setiap tugasan. Apa sahaja yang boleh berkomunikasi dengan Docker socket boleh memulakan kontena baharu yang memuatkan keseluruhan sistem fail hos anda, yang bermaksud akses socket tersebut secara berkesan adalah root pada mesin tersebut. Oleh itu, anggap pelayan OpenHands sebagai pelayan yang menjalankan kod yang tidak dipercayai, kerana itulah fungsinya. Setiap pilihan pengukuhan (hardening) di bawah adalah berdasarkan perkara ini.

Apa yang anda perlukan

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

Pasang dengan Docker

OpenHands dihantar sebagai dua imej: imej aplikasi yang anda jalankan, dan imej agent-server yang ia muat turun untuk menjalankan sandbox setiap tugasan. Jalankannya seperti ini, 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 butiran ini dapat menjimatkan masa anda selama satu jam. Imej aplikasi dan imej agent-server mempunyai nombor versi yang berbeza secara sengaja, jadi jangan cuba menyamakannya: gunakan tag agent-server yang dipadankan dengan versi aplikasi anda dalam dokumentasi. Dan perhatikan -p 127.0.0.1:3000:3000 dan bukannya -p 3000:3000. Perubahan tunggal itu adalah perbezaan antara Web UI yang hanya boleh dicapai oleh anda dan Web UI yang boleh dicapai oleh seluruh internet, yang akan dibincangkan dalam seksyen seterusnya.

Pastikan Web UI tidak terdedah ke internet awam

OpenHands menyediakan antaramukanya pada port 3000. Antaramuka itu menggerakkan ejen yang menjalankan kod, jadi mendedahkannya ke internet memberikan sesiapa sahaja yang menemuinya laluan jauh ke dalam proses yang melaksanakan arahan. Ikat (bind) ia pada loopback, seperti arahan jalan yang di atas, dan akses ia dari komputer riba anda melalui terowong SSH:

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

Kemudian buka http://127.0.0.1:3000 pada mesin anda sendiri. Trafik akan melalui sesi SSH sedia ada anda, dan tiada perkara baharu yang mendengar pada internet awam. Untuk tetapan yang lebih kekal, gunakan VPN sebagai ganti. Dalam apa jua cara, letakkan firewall "default-deny" di hadapan pelayan supaya tiada apa yang terdedah secara tidak sengaja, dan ingat bahawa firewall yang hanya melindungi IPv4 akan membiarkan port yang sama terbuka pada IPv6, yang merupakan jurang firewall IPv6 yang memerangkap ramai pengguna.

Asingkan kunci model dan sebarang kredensial repo

OpenHands memerlukan kunci API untuk modelnya, dan sering kali memerlukan token untuk melakukan clone dan push ke repositori anda. Kedua-duanya boleh membelanjakan wang dan bertindak sebagai anda, jadi layan ia seperti kata laluan. Simpan ia dalam fail persekitaran (environment file) yang hanya boleh dibaca oleh akaun yang betul, jangan sekali-kali letakkannya dalam arahan jalan di mana ia akan tersimpan dalam sejarah shell dan senarai proses, dan jangan sekali-kali letakkannya dalam fail di dalam repositori git.

Jalankan pada mesin yang boleh dibuang

Kerana pengendali mesti memegang Docker socket, anda tidak boleh mengasingkan OpenHands sepenuhnya daripada hosnya. Langkah mitigasi yang jujur adalah pengasingan melalui penempatan: jalankan OpenHands pada VPS khas yang tidak menyimpan perkara lain yang penting bagi anda, bukan pada pelayan yang juga menjalankan pangkalan data atau laman web anda. Ambil snapshot sebelum anda bermula, dan bina semula daripada snapshot tersebut daripada mempercayai mesin yang telah menjalankan kod buatan ejen selama seminggu. VPS murah, pakai buang, dan bertujuan tunggal adalah tempat yang sesuai untuknya.

Kukuhkan mesin di sekelilingnya

Selebihnya adalah kebersihan pelayan standard, dan ia lebih penting di sini berbanding biasa kerana beban kerja ini lebih berisiko daripada biasa. Cipta pengguna admin tanpa keistimewaan (unprivileged admin user) dan bukannya bekerja sebagai root, dengan mengikuti menjalankan perkhidmatan sebagai pengguna tanpa keistimewaan. Tukar SSH kepada pengesahan kunci sahaja. Kemudian jalankan senarai semak di bawah dan simpan di tempat yang anda akan lihat semula.

Untuk memahami komponen yang bergerak dan bukannya sekadar menjalankannya, lihat membina ejen AI anda sendiri pada VPS; untuk platform dengan kod yang lebih rendah, self-hosting Dify adalah permulaan yang lebih mudah.

FAQ

Adakah OpenHands selamat untuk dijalankan pada pelayan?

Ia boleh jadi selamat dengan berhati-hati, tetapi ia lebih berisiko daripada aplikasi web biasa kerana ia menulis dan menjalankan kod dan pengendalinya memegang Docker socket hos, yang secara berkesan adalah root pada mesin tersebut. Jalankannya pada VPS khas yang boleh dibuang yang tidak menyimpan perkara berharga lain, kekalkan Web UI pada loopback di sebalik terowong SSH atau VPN, asingkan kunci-kuncinya, dan kukuhkan mesin tersebut. Jangan jalankannya bersebelahan dengan perkhidmatan penting anda.

Mengapa OpenHands memerlukan Docker socket?

OpenHands menjalankan setiap tugasan dalam kontena sandbox yang baharu, dan ia meminta daemon Docker hos untuk mencipta kontena tersebut dengan memuatkan /var/run/docker.sock ke dalam pengendalinya. Ini memberikan kontena pengendali kawalan ke atas Docker pada hos, yang mana ia sangat berkuasa dan berisiko, jadi hos itu sendiri mesti dianggap sebagai mesin yang menjalankan kod yang tidak dipercayai.

Bolehkah OpenHands menggunakan model tempatan sebagai ganti API berbayar?

Ya. OpenHands menyokong model tempatan yang diserahkan oleh Ollama atau vLLM, jadi anda boleh menjalankannya secara hos sendiri sepenuhnya tanpa kos setiap token dan tanpa data meninggalkan pelayan anda. Anda memerlukan mesin dengan memori yang mencukupi untuk model pengekodan yang berkemampuan, yang merupakan persoalan saiz yang sama seperti dalam panduan Ollama.

Patutkah saya menjalankan OpenHands pada pelayan utama saya?

Tidak. Kerana ia menjalankan kod buatan ejen dan memegang Docker socket, simpan ia pada VPS berasingan yang bertujuan tunggal yang anda sanggup bina semula. Menempatkannya bersama pangkalan data, laman web, atau perkhidmatan anda yang lain bermaksud kesilapan oleh ejen, atau pepijat di dalamnya, boleh mencapai perkara yang tidak sepatutnya disentuhnya.