Installare OpenHands su VPS con Docker

Cos'è OpenHands e il rischio principale da comprendere

OpenHands, precedentemente OpenDevin, è un agente autonomo per l'ingegneria del software. Fornisci un compito in linguaggio naturale e l'agente pianifica il lavoro, scrive codice, esegue comandi, legge l'output e itera fino al completamento del compito. Si esegue su un server personale tramite Docker puntando a un modello linguistico. Su un VPS, diventa un agente di coding operativo anche quando non sei connesso.

Un fattore determina l'intera configurazione. OpenHands non si limita a suggerire codice, ma lo esegue; per farlo, il container controller monta il Docker socket dell'host su /var/run/docker.sock per creare container sandbox per ogni task. Qualsiasi processo con accesso al Docker socket può avviare un nuovo container che monti l'intero filesystem dell'host; di conseguenza, l'accesso al socket equivale a avere privilegi root sulla macchina. Tratta quindi l'istanza OpenHands come un server che esegue codice non fidato. Ogni scelta di hardening descritta di seguito deriva da questo principio.

Requisiti

È necessario un VPS con Ubuntu 24.04 e un Docker Engine recente, almeno 4 GB di RAM e una API key per un modello linguistico (OpenAI, Anthropic o Google), oppure un modello locale servito da Ollama sullo stesso VPS. OpenHands supporta decine di backend per i modelli. Se non hai mai configurato container, le basi di Docker su un VPS coprono gli argomenti necessari per questa guida.

Installazione con Docker

OpenHands è distribuito con due immagini: l'immagine dell'applicazione da eseguire e l'immagine agent-server che viene scaricata per gestire il sandbox di ogni task. Eseguilo come indicato sotto, sostituendo i tag attuali con quelli presenti 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 errori comuni. Le immagini app e agent-server hanno intenzionalmente numeri di versione differenti; non cercare di farli corrispondere: usa il tag agent-server accoppiato alla versione della tua app indicato nella documentazione. Nota inoltre l'uso di -p 127.0.0.1:3000:3000 invece di -p 3000:3000. Questa singola modifica determina se l'interfaccia Web sarà accessibile solo localmente o tramite internet, come spiegato nella sezione successiva.

Mantenere la Web UI isolata da internet

OpenHands pubblica la sua interfaccia sulla porta 3000. Tale interfaccia controlla un agente che esegue codice; pubblicizzarla su internet permette a chiunque trovi l'indirizzo di eseguire comandi da remoto. Vincola l'interfaccia al loopback, come nel comando di esecuzione sopra, e connettiti dal tuo laptop tramite un tunnel SSH:

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

Successivamente, apri http://127.0.0.1:3000 sulla tua macchina locale. Il traffico passerà attraverso la tua sessione SSH esistente e non ci saranno nuovi servizi esposti su internet. Per una configurazione permanente, utilizza una VPN. In entrambi i casi, configura un firewall con policy "default-deny" per evitare esposizioni accidentali. Ricorda che un firewall configurato solo per IPv4 lascia la stessa porta aperta su IPv6, creando il gap del firewall IPv6 che causa molti problemi di sicurezza.

Isolare la chiave del modello e le credenziali del repository

OpenHands richiede una API key per il modello e spesso un token per clonare e caricare codice sui tuoi repository. Entrambi possono generare costi o agire a tuo nome; trattali come password. Conservali in un file di ambiente leggibile solo dall'account corretto. Non inserirli mai nel comando di esecuzione (verrebbero salvati nella cronologia della shell e nella lista dei processi) e non salvarli mai in file all'interno di un repository git.

Eseguire l'agente su un server sacrificabile

Poiché il controller deve contenere il Docker socket, non è possibile isolare completamente OpenHands dall'host. La mitigazione efficace è l'isolamento tramite posizionamento: esegui OpenHands su un VPS dedicato che non contenga altri dati importanti, non sul server che ospita il tuo database o il tuo sito web. Effettua uno snapshot prima di iniziare e ricostruisci il sistema da quello snapshot invece di fidarti di una macchina che ha eseguito codice generato dall'agente per una settimana. Un VPS economico, dedicato e sacrificabile è l'ambiente ideale.

Hardening del server

Il resto consiste in standard di igiene del server. La sicurezza è qui più critica che di solito perché il carico di lavoro è più rischioso. Crea un utente amministratore non privilegiato invece di operare come root, seguendo le indicazioni su eseguire servizi come utente non privilegiato. Configura SSH per l'autenticazione tramite chiavi sole. Esegui quindi la checklist riportata sotto e conservala per consultazioni future.

Per comprendere i componenti interni invece di limitarti all'esecuzione, consulta costruire il proprio agente AI su un VPS; per una piattaforma con meno necessità di programmazione, self-hosting Dify offre un approccio più semplice.

FAQ

È sicuro eseguire OpenHands su un server?

Può esserlo, se gestito con cautela, ma è più rischioso di una normale web app perché scrive ed esegue codice e il controller possiede il Docker socket dell'host, che equivale a root sulla macchina. Eseguilo su un VPS dedicato e sacrificabile senza altri dati preziosi, mantieni la Web UI su loopback tramite tunnel SSH o VPN, isola le chiavi e proteggi il server. Non eseguirlo insieme ai tuoi servizi critici.

Perché OpenHands ha bisogno del Docker socket?

OpenHands esegue ogni task in un nuovo container sandbox e richiede al daemon Docker dell'host di creare tali container montando /var/run/docker.sock nel controller. Questo conferisce al container controller il controllo di Docker sull'host; tale potere è rischioso, pertanto l'host deve essere trattato come un sistema che esegue codice non fidato.

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

Sì. OpenHands supporta modelli locali serviti da Ollama o vLLM. È possibile eseguire il sistema interamente in locale, senza costi per token e senza inviare dati al di fuori del server. È necessaria una macchina con memoria sufficiente per un modello di coding performante, secondo le specifiche indicate nella guida di Ollama.

Devo eseguire OpenHands sul mio server principale?

No. Poiché esegue codice generato dall'agente e possiede il Docker socket, deve essere mantenuto su un VPS separato e dedicato che sia pronto per essere ricostruito. Eseguirlo insieme a database, siti web o altri servizi significa che un errore dell'agente, o un bug nel sistema, può compromettere risorse a cui non dovrebbe avere accesso.