OpenHands installeren op een VPS

Wat OpenHands is en het eerste risico dat u moet begrijpen

OpenHands, voorheen OpenDevin, is een autonome software-engineering agent. U geeft de agent een taak in gewone taal en de agent plant het werk, schrijft code, voert commando's uit, leest de output en herhaalt dit tot de taak is voltooid. U draait het op uw eigen server met Docker en koppelt het aan een taalmodel. Op een VPS wordt het een programmeeragent die doorwerkt terwijl u niet aanwezig bent.

Eén feit bepaalt uw volledige configuratie. OpenHands stelt niet alleen code voor, maar voert deze ook uit. Om dit te doen, mount de controller-container de host Docker socket op /var/run/docker.sock, zodat er voor elke taak sandbox-containers gestart kunnen worden. Alles wat verbinding kan maken met de Docker socket kan een nieuwe container starten die uw volledige host-filesystem mount. Dit betekent dat toegang tot de socket effectief root-rechten op de machine geeft. Behandel de OpenHands-machine daarom als een server die onbetrouwbare code uitvoert, want dat is precies wat het doet. Elke beveiligingsmaatregel hieronder is hierop gebaseerd.

Wat u nodig heeft

U heeft een VPS nodig met Ubuntu 24.04 en een recente Docker Engine, minimaal 4 GB RAM, en een API-key voor een taalmodel (OpenAI, Anthropic of Google), of een lokaal model via Ollama op dezelfde VPS. OpenHands ondersteunt tientallen model-backends, dus de keuze is aan u. Als u nog nooit containers heeft ingesteld, dan behandelt de basisprincipes van Docker op een VPS de kennis die in deze gids wordt verondersteld.

Installeren met Docker

OpenHands wordt geleverd als twee images: de application image die u uitvoert, en een agent-server image die wordt opgehaald om de sandbox van elke taak te draaien. Voer het als volgt uit, waarbij u de huidige tags uit de documentatie van het project gebruikt:

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

Twee details besparen u een uur aan verwarring. De app image en de agent-server image hebben met opzet verschillende versienummers; probeer deze dus niet gelijk te maken. Gebruik de agent-server tag die in de documentatie bij uw app-versie hoort. Let ook op het gebruik van -p 127.0.0.1:3000:3000 in plaats van -p 3000:3000. Deze enkele wijziging is het verschil tussen een Web UI die alleen u kunt bereiken en een interface die voor het hele internet toegankelijk is, waar het volgende gedeelte over gaat.

Houd de Web UI af van het publieke internet

OpenHands serveert de interface op poort 3000. Deze interface bestuurt een agent die code uitvoert. Het publiceren hiervan op het internet geeft iedereen die de interface vindt een externe toegangsweg tot een proces dat commando's uitvoert. Bind de interface aan loopback, zoals het bovenstaande run-commando doet, en bereik de interface vanaf uw laptop via een SSH-tunnel:

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

Open vervolgens http://127.0.0.1:3000 op uw eigen machine. Het verkeer loopt via uw bestaande SSH-sessie en er luistert niets nieuws op het publieke internet. Voor een permanente configuratie kunt u het beter achter een VPN plaatsen. Hoe dan ook: plaats een firewall met een default-deny beleid voor de machine zodat er niets per ongeluk wordt blootgesteld. Houd er rekening mee dat een firewall die alleen IPv4 dekt, hetzelfde poort open laat staan op IPv6; dit is de IPv6 firewall gap waar veel mensen de fout in gaan.

Isoleer de model-key en eventuele repo-credentials

OpenHands heeft een API-key nodig voor het model en vaak een token om te clonen en te pushen naar uw repositories. Beide kunnen geld kosten en handelen als u. Behandel deze daarom als wachtwoorden. Bewaar ze in een omgevingsbestand dat alleen door het juiste account gelezen kan worden. Gebruik nooit het run-commando om ze mee te geven, omdat ze dan in uw shell-geschiedenis en de proceslijst terechtkomen. Bewaar ze ook nooit in een bestand binnen een git-repository.

Draai het op een machine die u kunt weggooien

Omdat de controller de Docker socket moet bezitten, kunt u OpenHands niet volledig isoleren van de host. De enige echte oplossing is isolatie door plaatsing: draai OpenHands op een dedicated VPS waar geen andere belangrijke gegevens op staan. Draai het niet op de server waar ook uw database of uw website op draait. Maak een snapshot voordat u begint, en bouw de machine opnieuw op vanuit die snapshot in plaats van te vertrouwen op een machine waarop een week lang door een agent gegenereerde code is gedraaid. Een goedkope, vervangbare VPS met één doel is de juiste omgeving.

Beveilig de machine

De rest is standaard serverhygiëne. Dit is hier belangrijker dan gebruikelijk omdat de werklast risicovoller is dan normaal. Maak een onbevoegde admin-gebruiker aan in plaats van als root te werken, zie services draaien als een onbevoegde gebruiker. Verander SSH naar authenticatie via alleen SSH-keys. Voer vervolgens de onderstaande checklist uit en bewaar deze op een plek waar u hem later weer ziet.

Om de werking te begrijpen in plaats van alleen de commando's uit te voeren, kunt u kijken naar het bouwen van uw eigen AI agent op een VPS. Voor een platform met minder code is self-hosting Dify een toegankelijker alternatief.

FAQ

Is OpenHands veilig om op een server te draaien?

Dat kan met zorg, maar het is risicovoller dan een gewone webapplicatie. De agent schrijft en voert code uit en de controller bezit de host Docker socket, wat effectief root-rechten op de machine geeft. Draai het op een dedicated, vervangbare VPS zonder andere waardevolle gegevens, houd de Web UI op loopback achter een SSH-tunnel of VPN, isoleer de keys en beveilig de machine. Draai het niet naast uw belangrijke services.

Waarom heeft OpenHands de Docker socket nodig?

OpenHands voert elke taak uit in een nieuwe sandbox-container. De agent vraagt de host Docker daemon om deze containers aan te maken door /var/run/docker.sock in de controller te mounten. Dit geeft de controller-container controle over Docker op de host. Dit is krachtig en risicovol, waardoor de host zelf moet worden behandeld als een systeem dat onbetrouwbare code uitvoert.

Kan OpenHands een lokaal model gebruiken in plaats van een betaalde API?

Ja. OpenHands ondersteunt lokale modellen via Ollama of vLLM. U kunt het dus volledig zelf hosten zonder kosten per token en zonder dat data uw server verlaat. U heeft een machine nodig met voldoende geheugen voor een krachtig programmeermodel; dit is dezelfde hardware-vraagstuk als in de Ollama-gids.

Moet ik OpenHands op mijn hoofdserver draaien?

Nee. Omdat de agent code genereert en de Docker socket bezit, moet u het op een aparte VPS draaien die u bereid bent opnieuw te installeren. Het draaien op dezelfde machine als een database, een website of andere services betekent dat een fout van de agent, of een bug in de software, bij zaken kan komen die de agent nooit had mogen aanraken.