Jinsi ya kuweka OpenHands kwenye VPS

OpenHands ni nini, na hatari moja ya kuelewa kwanza

OpenHands, zamani ikiitwa OpenDevin, ni agent anayejiendesha kwa ajili ya uhandisi wa programu. Unampa kazi kwa lugha rahisi, kisha anapanga kazi, anaandika kodi, anafanya amri (commands), anasoma matokeo, na kurudia mchakato hadi kazi iishe. Unaiendesha kwenye seva yako mwenyewe kwa kutumia Docker na kuiunganisha na model ya lugha. Kwenye VPS, inakuwa agent wa kodi anayefanya kazi wakati wewe haupo.

Kuna ukweli mmoja unapaswa kuongoza mipangilio yako yote. OpenHands haishauri kodi tu, bali inaendesha kodi, na ili kufanya hivyo, container ya controller inafungamanisha (mounts) Docker socket ya host kwenye /var/run/docker.sock ili iweze kutengeneza sandbox containers kwa kila kazi. Kitu chochote kinachoweza kuwasiliana na Docker socket kinaweza kuanzisha container mpya inayofungamanisha mfumo wote wa faili wa host yako, ikimaanisha kuwa ufikiaji wa socket ni sawa na kuwa na root kwenye mashine. Hivyo, itumie OpenHands kama seva inayojiendeshea kodi isiyoaminika, kwa sababu ndivyo inavyofanya. Chaguo zote za uimarishaji (hardening) hapa chini zinatokana na hilo.

Unachohitaji

Unahitaji VPS inayotumia Ubuntu 24.04 ikiwa na Docker Engine ya hivi karibuni, angalau RAM ya GB 4, na API key kwa model ya lugha (OpenAI, Anthropic, au Google), au model ya ndani inayotolewa na Ollama kwenye VPS hiyo hiyo. OpenHands inasaidia mbinu nyingi za model, hivyo uchaguzi ni wako. Kama hujawahi kusanidi containers hapo awali, misingi ya Docker kwenye VPS inaelezea mambo ambayo mwongozo huu unayafikiria tayari.

Sakinisha kwa Docker

OpenHands inakuja na picha (images) mbili: picha ya programu unayoiendesha, na picha ya agent-server inayovuta (pulls) ili kuendesha sandbox ya kila kazi. Iendeshe hivi, ukibadilisha tag za sasa kutoka kwenye docs za mradi:

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

Maelezo mawili yatakuepusha na mkanganyiko wa saa moja. Picha ya app na picha ya agent-server zina namba tofauti za toleo kwa makusudi, hivyo usijaribu kuzifanya zifanane: tumia tag ya agent-server inayopendekezwa na docs kwa toleo lako la app. Pia, zingatia -p 127.0.0.1:3000:3000 badala ya -p 3000:3000. Mabadiliko hayo pekee ndiyo tofauti kati ya Web UI inayoweza kufikiwa na wewe pekee na ile inayoweza kufikiwa na mtandao mzima, ambayo sehemu inayofuata inahusu.

Weka Web UI mbali na mtandao wa umma

OpenHands inatoa interface yake kwenye port 3000. Interface hiyo inaendesha agent anayefanya kazi ya kodi, hivyo kuipandisha kwenye mtandao kunampa mtu yeyote anayeyipata njia ya mbali ya kuingia kwenye mchakato unaotekeleza amri. Ifungamanishe (bind) kwenye loopback, kama amri ya kuendesha ilivyo hapo juu, na uifikie kutoka kwenye laptop yako kupitia SSH tunnel:

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

Kisha fungua http://127.0.0.1:3000 kwenye mashine yako mwenyewe. Trafiki itatumia session yako ya SSH iliyopo, na hakuna kitu kipya kitakachosikiliza kwenye mtandao wa umma. Kwa mpangilio wa kudumu zaidi, iweke nyuma ya VPN badala yake. Vyovyote vile, weka firewall inayozuia kila kitu (default-deny) mbele ya mashine ili kusiwe na kitu kinachofichuliwa kwa bahati mbaya, na kumbuka kuwa firewall inayofunika IPv4 pekee inaacha port ile ile ikiwa wazi kwenye IPv6, ambayo ni pengo la IPv6 firewall linalowakamata watu wengi.

Tenga model key na nywila zozote za repo

OpenHands inahitaji API key kwa ajili ya model yake, na mara nyingi inahitaji token ya ku-clone na ku-push kwenye repositories zako. Zote zinaweza kutumia pesa na kutenda kama wewe, hivyo zichukulie kama nywila. Zihifadhi kwenye faili la mazingira (environment file) ambalo ni akaunti sahihi pekee inayoweza kusoma, usiziweke kwenye amri ya kuendesha ambapo zitaingia kwenye historia ya shell na orodha ya michakato, na usiziweke kwenye faili ndani ya git repository.

Iendeshe kwenye mashine unayoweza kuitupa

Kwa sababu controller lazima iwe na Docker socket, huwezi kuitenga OpenHands kabisa kutoka kwa host yake. Suluhisho la kweli ni utengano kwa njia ya mahali: iendeshe OpenHands kwenye VPS maalum ambayo haina kitu kingine unachokijali, si kwenye seva inayojiendesha pia database yako au tovuti yako. Chukua snapshot kabla ya kuanza, na ujenge upya kutoka kwenye snapshot hiyo badala ya kuamini mashine ambayo imekuwa ikiendesha kodi iliyoandikwa na agent kwa wiki moja. VPS rahisi, inayoweza kutupwa, na yenye kazi moja ndiyo nyumba sahihi kwake.

Imarisha mashine inayoiendesha

Sehemu iliyobaki ni usafi wa kawaida wa seva, na ni muhimu zaidi hapa kuliko kawaida kwa sababu mzigo wa kazi ni hatari zaidi kuliko kawaida. Tengeneza mtumiaji wa admin asiye na mamlaka (unprivileged) badala ya kufanya kazi kama root, ukifuata kuendesha huduma kama mtumiaji asiye na mamlaka. Hamisha SSH kwenda kwenye uthibitishaji wa funguo (key-only authentication) pekee. Kisha fanya orodha ya ukaguzi (checklist) hapa chini na uihifadhi mahali utakapoweza kuiona tena.

Ili kuelewa sehemu zinazohusika badala ya kuzirun tu, tazama kujenga agent yako mwenyewe wa AI kwenye VPS; kwa jukwaa lenye kodi ndogo, self-hosting Dify ni njia rahisi zaidi ya kuanza.

FAQ

Je, OpenHands ni salama kuendesha kwenye seva?

Inaweza kuwa salama, kwa uangalifu, lakini ina hatari zaidi kuliko programu ya kawaida ya wavuti kwa sababu inaandika na kuendesha kodi, na controller yake ina Docker socket ya host, ambayo ni sawa na kuwa na root kwenye mashine. Iendeshe kwenye VPS maalum, inayoweza kutupwa ambayo haina kitu kingine cha thamani, iweke Web UI yake kwenye loopback nyuma ya SSH tunnel au VPN, tenga funguo zake, na imarisha mashine hiyo. Usiiendeshe kando ya huduma zako muhimu.

Kwa nini OpenHands inahitaji Docker socket?

OpenHands inaendesha kila kazi katika sandbox container mpya, na inaomba Docker daemon ya host itengeneze hizo container kwa kufungamanisha /var/run/docker.sock ndani ya controller yake. Hii inakupa controller container udhibiti juu ya Docker kwenye host, jambo ambalo ni lenye nguvu na hatari, hivyo host yenyewe lazima ichukuliwe kama inayojiendesha kodi isiyoaminika.

Je, OpenHands inaweza kutumia model ya ndani badala ya API ya kulipia?

Ndiyo. OpenHands inasaidia model za ndani zinazotolewa na Ollama au vLLM, hivyo unaweza kuiendesha ikiwa imejihifadhi kikamilifu bila gharama ya kila token na bila data kutoka kwenye seva yako. Unahitaji mashine yenye kumbukumbu ya kutosha kwa model ya kodi yenye uwezo, ambayo ni swali lilelile la ukubwa unaozungumziwa kwenye mwongozo wa Ollama.

Je, nianze kuendesha OpenHands kwenye seva yangu kuu?

Hapana. Kwa sababu inaendesha kodi iliyoandikwa na agent na ina Docker socket, iweke kwenye VPS tofauti, yenye kazi moja, ambayo uko tayari kuijenga upya. Kuiweka pamoja na database, tovuti, au huduma zako nyingine inamaanisha kuwa makosa ya agent, au hitilafu (bug) ndani yake, yanaweza kufikia vitu ambavyo hayakuwekwa vyote kugusa.