OpenHands zelf hosten op een VPS: handleiding

Wat OpenHands is, en het voornaamste risico om te begrijpen

OpenHands, voorheen OpenDevin, is een autonome software-engineering agent. U geeft de agent een taak in natuurlijke taal, waarna deze het werk plant, code schrijft, commando's uitvoert, de output leest en iteraties uitvoert totdat de taak is voltooid. U draait de software op uw eigen server met Docker en koppelt deze aan een taalmodel. Op een VPS fungeert het als een programmeer-agent die doorwerkt terwijl u afwezig bent.

Eén feit moet de basis vormen van uw gehele configuratie. OpenHands suggereert niet alleen code, maar voert deze ook uit. Om dit te doen, koppelt de controller-container de Docker-socket van de host op /var/run/docker.sock, zodat deze voor elke taak sandbox-containers kan starten. Alles wat met de Docker-socket kan communiceren, is in staat een nieuwe container te starten die uw volledige host-bestandssysteem koppelt; dit betekent dat toegang tot de socket effectief gelijkstaat aan root-toegang op de machine. Behandel de OpenHands-omgeving daarom als een server die niet-vertrouwde code uitvoert, want dat is precies wat er gebeurt. Elke hieronder genoemde beveiligingsmaatregel vloeit voort uit dit uitgangspunt.

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-sleutel voor een taalmodel (OpenAI, Anthropic of Google), of een lokaal model dat wordt aangeboden via Ollama op dezelfde VPS. OpenHands ondersteunt tientallen model-backends, dus de keuze is aan u. Als u nog nooit eerder containers heeft opgezet, behandelt de basis van Docker op een VPS de voorkennis waar deze handleiding vanuit gaat.

Installatie met Docker

OpenHands wordt geleverd als twee images: de applicatie-image die u uitvoert en een agent-server-image die wordt opgehaald om de sandbox van elke taak uit te voeren. Voer het als volgt uit en vervang de tags door de actuele versies uit de documentatie van het project:

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 bewust verschillende versienummers; probeer deze dus niet gelijk te trekken: gebruik de agent-server-tag die in de documentatie bij uw app-versie hoort. Let ook op de -p 127.0.0.1:3000:3000 in plaats van -p 3000:3000. Dat ene verschil bepaalt of de Web UI alleen voor u toegankelijk is of voor het hele internet, waar het volgende gedeelte over gaat.

Houd de Web UI buiten het publieke internet

OpenHands serveert de interface op poort 3000. Die interface bestuurt een agent die code uitvoert. Het publiceren ervan op het internet geeft iedereen die de interface vindt een pad naar een proces dat commando's uitvoert. Bind de interface aan loopback, zoals het bovenstaande run-commando doet, en benader deze 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 verloopt via uw bestaande SSH-sessie en er luistert niets nieuws op het publieke internet. Niet elke agent heeft een poort nodig: Claude Code-sessies op dezelfde VPS communiceren met elkaar via de terminal, dus het enige dat u ooit blootstelt is SSH zelf. Het is aan te raden om de gewoonte van loopback-en-tunnel toe te passen op elk agent-dashboard dat u host; het benaderen van de scanning UI van open-kritt via een tunnel werkt op dezelfde manier, alleen op poort 5173. Voor een meer permanente opstelling kunt u de service achter een VPN plaatsen. Plaats in ieder geval een default-deny firewall voor de server zodat er niets per ongeluk wordt blootgesteld. Onthoud dat een firewall die alleen IPv4 dekt, dezelfde poort openlaat op IPv6; dit is het IPv6 firewall-gat waar velen in trappen.

Isoleer de modelsleutel en eventuele repository-referenties

OpenHands heeft een API-sleutel nodig voor het model, en vaak een token om naar uw repositories te pushen en deze te klonen. Beide kunnen geld kosten en acties namens u uitvoeren, dus behandel ze als wachtwoorden. Bewaar ze in een omgevingsbestand dat alleen door het juiste account kan worden gelezen. Plaats ze nooit in het uitvoercommando, omdat ze dan in uw shell-geschiedenis en de proceslijst terechtkomen, en bewaar ze nooit in een bestand binnen een git-repository. Als u de originelen in een zelfgehoste wachtwoordmanager bewaart, beveilig die server dan ook. De zwakke punten van een kluis zijn namelijk het admin-token en het back-upbestand, en niet de versleutelde items zelf, zoals de Vaultwarden hardening pass beschrijft.

Draai het op een systeem dat u kunt weggooien

Omdat de controller toegang moet hebben tot de Docker-socket, kunt u OpenHands niet volledig isoleren van de host. De enige eerlijke beperking van risico's is isolatie door plaatsing: draai OpenHands op een toegewezen VPS waar verder niets op staat dat voor u van belang is, en niet op de server die ook uw database of website host. Maak een snapshot voordat u begint en herbouw de server vanaf dat snapshot in plaats van te vertrouwen op een systeem dat een week lang door een agent geschreven code heeft uitgevoerd. Een goedkope, vervangbare VPS voor één enkel doel is de juiste omgeving hiervoor. Plaatsing is de enige knop die OpenHands u hier echt biedt. Als u liever ook controleert hoeveel de agent mag doen voordat deze stopt om toestemming te vragen, laten de permissiemodi van Claude Code zien hoe die tweede hendel eruitziet op een server die door niemand in de gaten wordt gehouden.

De server beveiligen

De rest is standaard serverhygiëne, wat hier belangrijker is dan gebruikelijk omdat de werklast risicovoller is dan normaal. Maak een admin-gebruiker zonder privileges aan in plaats van als root te werken, volgens services draaien als een gebruiker zonder privileges. Schakel SSH over naar authenticatie uitsluitend via sleutels. Loop daarna de onderstaande checklist na en bewaar deze op een plek waar u deze later weer kunt inzien.

Om de onderliggende onderdelen te begrijpen in plaats van ze alleen uit te voeren, raadpleeg uw eigen AI-agent bouwen op een VPS; voor een platform met minder code is Dify zelf hosten een toegankelijker startpunt.

FAQ

Is OpenHands veilig om op een server te draaien?

Dat kan, mits u voorzichtig bent. Het is risicovoller dan een standaard webapplicatie omdat het code schrijft en uitvoert, en de controller toegang heeft tot de Docker-socket van de host, wat in de praktijk gelijkstaat aan root-rechten op de machine. Draai het op een toegewezen, vervangbare VPS waar verder geen waardevolle gegevens op staan, houd de webinterface op loopback achter een SSH-tunnel of VPN, isoleer de sleutels en beveilig de server. Draai het niet naast uw belangrijke services.

Waarom heeft OpenHands de Docker-socket nodig?

OpenHands voert elke taak uit in een nieuwe sandbox-container en vraagt de Docker-daemon van de host om die containers aan te maken door /var/run/docker.sock te mounten in de controller. Hierdoor krijgt de controller-container controle over Docker op de host. Dit is krachtig en risicovol, waardoor de host zelf moet worden behandeld als een machine die niet-vertrouwde code uitvoert.

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

Ja. OpenHands ondersteunt lokale modellen die worden aangeboden door Ollama of vLLM. U kunt het dus volledig zelf hosten zonder kosten per token en zonder dat er gegevens uw server verlaten. U heeft een machine nodig met voldoende geheugen voor een capabel programmeermodel; dit is dezelfde capaciteitsvraag als behandeld in de Ollama-handleiding.

Moet ik OpenHands op mijn hoofdserver draaien?

Nee. Omdat het door een agent geschreven code uitvoert en toegang heeft tot de Docker-socket, moet u het op een aparte VPS met één enkel doel draaien die u zonder problemen opnieuw kunt installeren. Het combineren met een database, een website of uw andere services betekent dat een fout van de agent, of een bug in de software, toegang kan krijgen tot zaken die nooit voor de agent bedoeld waren.