Come installare OpenHands su un VPS con Docker

Che cos'è OpenHands e il rischio principale da comprendere

OpenHands, precedentemente chiamato OpenDevin, è un agente autonomo per l'ingegneria del software. Gli assegni un'attività in linguaggio naturale e l'agente pianifica il lavoro, scrive il codice, esegue i comandi, legge l'output e ripete il ciclo finché l'attività non è completata. Lo esegui sul tuo server con Docker e lo colleghi a un modello linguistico. Su un VPS diventa un agente di sviluppo che lavora anche quando non sei presente.

Un aspetto deve guidare l'intera configurazione. OpenHands non si limita a suggerire codice: lo esegue. Per farlo, il container controller monta il socket Docker dell'host in /var/run/docker.sock, così può avviare container sandbox per ogni attività. Qualsiasi processo in grado di comunicare con il socket Docker può avviare un nuovo container che monta l'intero filesystem dell'host. L'accesso al socket equivale quindi, di fatto, all'accesso root sulla macchina. Considera perciò il server OpenHands come un server che esegue codice non attendibile, perché è esattamente ciò che fa. Tutte le misure di hardening descritte di seguito derivano da questo principio.

Cosa serve

Ti serve un VPS con Ubuntu 24.04, una versione recente di Docker Engine, almeno 4 GB di RAM e una chiave API per un modello linguistico (OpenAI, Anthropic o Google), oppure un modello locale fornito da Ollama sullo stesso VPS. OpenHands supporta decine di backend per modelli, quindi la scelta dipende da te. Se non hai mai configurato container, le nozioni di base su Docker in un VPS coprono i prerequisiti di questa guida.

Installare con Docker

OpenHands viene distribuito come due immagini: l'immagine dell'applicazione che si esegue e un'immagine agent-server che viene scaricata per eseguire il sandbox di ogni attività. Eseguirlo in questo modo, sostituendo i tag correnti indicati nella documentazione del progetto:

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

Due dettagli evitano un'ora di confusione. L'immagine dell'applicazione e quella agent-server hanno intenzionalmente numeri di versione diversi. Non cercare quindi di renderli uguali: usa il tag agent-server associato dalla documentazione alla versione dell'applicazione. Nota inoltre -p 127.0.0.1:3000:3000 invece di -p 3000:3000. Questa singola modifica determina se la Web UI è raggiungibile soltanto da te oppure dall'intera Internet. La sezione successiva tratta proprio questo aspetto.

Mantieni la Web UI fuori da Internet pubblico

OpenHands espone la propria interfaccia sulla porta 3000. L’interfaccia controlla un agent che esegue codice; pubblicarla su Internet consente quindi a chiunque la individui di raggiungere da remoto un processo che esegue comandi. Associala all’interfaccia di loopback, come nel comando di esecuzione precedente, e raggiungila dal laptop tramite un tunnel SSH:

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

Apri quindi http://127.0.0.1:3000 sul tuo computer. Il traffico passa attraverso la sessione SSH esistente e nessun nuovo servizio resta in ascolto su Internet pubblico. Non tutti gli agent richiedono una porta: le sessioni Claude Code sullo stesso VPS comunicano tra loro tramite il terminale, quindi l’unico servizio esposto è SSH. La stessa pratica, basata su loopback e tunnel, è utile per ogni dashboard di agent che ospiti; raggiungere tramite tunnel l’interfaccia di scansione di open-kritt funziona nello stesso modo, ma sulla porta 5173. Per una configurazione più stabile, usa invece una VPN. In ogni caso, applica al server un firewall con criterio predefinito di negazione, così nulla viene esposto per errore. Ricorda inoltre che un firewall configurato soltanto per IPv4 lascia la stessa porta aperta su IPv6: è il problema del firewall IPv6 che causa problemi a molti amministratori.

Isolare la chiave del modello e le credenziali dei repository

OpenHands richiede una chiave API per il modello e spesso anche un token per clonare e inviare modifiche ai repository. Entrambi possono generare costi e agire a tuo nome, quindi trattali come password. Conservali in un file di ambiente leggibile soltanto dall’account autorizzato. Non inserirli mai nel comando di avvio, dove finirebbero nella cronologia della shell e nell’elenco dei processi. Non salvarli mai in un file all’interno di un repository git. Se conservi gli originali in un password manager self-hosted, proteggi adeguatamente anche quel server. I punti deboli di un vault sono infatti il token amministrativo e il file di backup, non gli elementi crittografati in sé, come illustrato dalla procedura di hardening di Vaultwarden.

Eseguilo su un server usa e getta

Poiché il controller deve avere accesso al socket Docker, non puoi isolare completamente OpenHands dal relativo host. La mitigazione corretta consiste nell’isolarlo tramite il posizionamento: esegui OpenHands su un VPS dedicato che non contenga altri dati o servizi importanti, non sul server che esegue anche il database o il sito web. Crea uno snapshot prima di iniziare e ricrea il server da quello snapshot, invece di continuare a utilizzare un server su cui è stato eseguito per una settimana codice scritto dall’agente. Un VPS economico, usa e getta e dedicato a un unico scopo è la soluzione più adatta. In questo caso il posizionamento è l’unico parametro di controllo realmente disponibile in OpenHands. Se vuoi controllare anche quanto l’agente può fare prima di fermarsi per chiedere conferma, le modalità di autorizzazione di Claude Code mostrano come funziona questo secondo livello di controllo su un server non monitorato.

Metti in sicurezza il server

Il resto riguarda le normali attività di sicurezza del server. In questo caso sono ancora più importanti, perché il carico di lavoro comporta rischi maggiori. Crea un utente amministratore senza privilegi invece di lavorare come root, seguendo eseguire i servizi con un utente senza privilegi. Configura quindi SSH per usare esclusivamente l'autenticazione tramite chiave. Esegui infine la checklist seguente e conservala in un punto in cui potrai consultarla di nuovo.

Per comprendere i vari componenti, invece di limitarti a eseguire i comandi, consulta creare il proprio agente AI su un VPS. Se preferisci una piattaforma che richiede meno codice, self-hosting di Dify offre un punto di partenza più semplice.

FAQ

OpenHands è sicuro da eseguire su un server?

Può esserlo, se configurato con attenzione, ma è più rischioso di una normale applicazione web perché scrive ed esegue codice e il suo controller contiene il socket Docker dell'host, che di fatto equivale all'accesso root sulla macchina. Eseguilo su un VPS dedicato e ricreabile, che non contenga altri dati importanti; mantieni la sua interfaccia Web in ascolto su loopback e accedivi tramite un tunnel SSH o una VPN, isola le relative chiavi e applica un hardening al sistema. Non eseguirlo insieme ai servizi importanti.

Perché OpenHands richiede il socket Docker?

OpenHands esegue ogni attività in un container sandbox appena creato e chiede al daemon Docker dell'host di creare tali container montando /var/run/docker.sock nel controller. In questo modo il container del controller ottiene il controllo di Docker sull'host. Si tratta di un accesso potente e rischioso, quindi l'host deve essere trattato come un sistema che esegue codice non attendibile.

OpenHands può usare un modello locale invece di un'API a pagamento?

Sì. OpenHands supporta i modelli locali forniti da Ollama o vLLM, quindi puoi eseguirlo interamente in modalità self-hosted, senza costi per token e senza che i dati lascino il server. Serve una macchina con memoria sufficiente per un modello di coding adeguato. È lo stesso criterio di dimensionamento descritto nella guida a Ollama.

Devo eseguire OpenHands sul server principale?

No. Poiché esegue codice scritto dall'agente e contiene il socket Docker, tienilo su un VPS separato e dedicato, che tu sia disposto a ricreare. Eseguirlo insieme a un database, a un sito web o agli altri servizi significa che un errore dell'agente, oppure un suo bug, può raggiungere risorse che non dovrebbe mai poter utilizzare.