Tutorial: OpenHands in container Docker per esperimenti di ricerca riproducibili

Ricerca & Università

Gruppi di ricerca che vogliono sperimentare agent autonomi in un ambiente isolato, con vincoli espliciti sulle risorse e sull’accesso ai dati originali.

Scopri →

Note preliminari

Contenuto fornito “as-is”. Prima di usare OpenHands su dati reali:

• Lavorate in un container con volumi mount mirati: l’agente ha accesso al file system del container.
• Backup di dataset e codice prima di ogni sessione.
• Non inserite secrets nelle variabili d’ambiente passate al container a meno che siano davvero necessarie. Preferite file di config montati in read-only e ruotati dopo l’uso.
• OpenHands è un agente autonomo che esegue codice: il perimetro Docker è l’ultima linea di difesa. Un --privileged o un --network host vanificano l’isolamento; evitateli.
• Per dati regolati (personali, sanitari) usate un modello locale e disattivate l’accesso di rete del container una volta scaricate le immagini.

Cosa è OpenHands

OpenHands (github.com/All-Hands-AI/OpenHands), inizialmente pubblicato come OpenDevin il 12 marzo 2024 e rinominato OpenHands il 26 agosto 2024 (annuncio di Graham Neubig, v0.9.0), è un progetto open source MIT che fornisce una piattaforma per agent capaci di scrivere codice, navigare file system, usare browser e terminale. L’architettura è pensata per far eseguire l’agente dentro un sandbox, tipicamente un container Docker, mentre un frontend web (o una CLI) permette all’operatore di osservare e indirizzare.

La differenza operativa rispetto a un assistente IDE è il grado di autonomia: OpenHands può pianificare una sequenza di passi e eseguirli senza chiedere approval su ognuno, nei limiti della sandbox configurata. Per un contesto di ricerca il paradigma è attraente se accoppiato a un perimetro rigoroso.

Caso d’uso: prima pulizia di un dataset scientifico in sandbox

Scenario: un ricercatore riceve un dataset CSV di 5 GB con schema eterogeneo (colonne numeriche con separatori inconsistenti, date in più formati). Vuole un primo round di pulizia ripetibile, documentato, senza rischio di alterare i file originali.

1. Struttura di progetto

~/exp-openhands/
├── input/              # dati sorgente, montati read-only
│   └── measurements.csv
├── workspace/          # working dir dell'agente, writable
└── logs/               # trascript e report della sessione

mkdir -p ~/exp-openhands/{input,workspace,logs}
cp /data/raw/measurements.csv ~/exp-openhands/input/
chmod -R a-w ~/exp-openhands/input      # dati read-only anche nel container

2. Avvio di OpenHands in Docker

Sintassi indicativa — la release corrente di OpenHands può cambiare i nomi dei flag; fate riferimento alla documentazione della versione installata.

docker run --rm -it \
  --name openhands \
  --network openhands-net \
  -p 3000:3000 \
  -v ~/exp-openhands/input:/workspace/input:ro \
  -v ~/exp-openhands/workspace:/workspace/work \
  -v ~/exp-openhands/logs:/workspace/logs \
  -e LLM_BASE_URL=http://ollama:11434/v1 \
  -e LLM_API_KEY=ollama \
  -e LLM_MODEL=openai/deepseek-coder-v2:16b \
  docker.all-hands.dev/all-hands-ai/openhands:latest

Punti chiave della configurazione:

• input montato con :ro — l’agente non può sovrascrivere i dati sorgente.
• workspace è l’unica directory scrivibile: qui finiscono script, dataset derivati, plot.
• logs separato per gli artefatti di sessione — facile da cancellare se contiene PII.
• Modello via endpoint locale (Ollama su rete Docker openhands-net): nessun traffico verso provider esterni.
• Nessun --privileged e nessun --network host: l’agente vive in una rete Docker dedicata.

3. Prompt di sessione

Nella UI web su http://localhost:3000:

“In /workspace/input/measurements.csv (solo lettura) è presente un dataset tabellare. Crea uno script /workspace/work/clean.py che: (a) legga il file riconoscendo automaticamente il separatore; (b) normalizzi le date in formato ISO 8601; (c) converta colonne numeriche eliminando caratteri di migliaia; (d) salvi l’output come /workspace/work/measurements_cleaned.parquet; (e) scriva in /workspace/logs/cleaning_report.md un riepilogo con numero di righe in ingresso, righe scartate e motivazione. Non modificare nulla in /workspace/input.”

OpenHands pianifica l’esecuzione. Mentre agisce, controllate nel pannello laterale i comandi che sta impartendo e i file che sta creando.

4. Verifica dei risultati

Dopo il termine:

ls -la ~/exp-openhands/workspace/
cat ~/exp-openhands/logs/cleaning_report.md
python3 -c "import pandas as pd; print(pd.read_parquet('$HOME/exp-openhands/workspace/measurements_cleaned.parquet').info())"

Lo script clean.py prodotto è l’artefatto riproducibile. Committatelo nel repo del progetto: la pulizia non è più “magia di una sessione”, è un passo documentato.

5. Chiusura della sessione

docker stop openhands
# I volumi mount restano: i risultati sono sul filesystem host.
# Se i logs contengono PII, cancellateli:
#   shred -u ~/exp-openhands/logs/*

Limiti e avvertenze

• La sandbox non è un confinement completo: Docker è una sandbox pragmatica, non una VM isolata. Un agente con accesso a Docker socket o a una rete condivisa con altri servizi espande la superficie. Per livelli di rischio più alti, eseguite OpenHands in una VM dedicata o in un runner CI effimero.
• Il modello può generare codice “plausibile” ma errato: il riepilogo in cleaning_report.md non va preso come ground truth. Confrontate i conteggi con una query indipendente sul dataset originale prima di accettare la pulizia.
• Modelli locali 7B–14B sono modesti su data cleaning articolato: per dataset complessi potreste dover iterare più volte, correggendo manualmente lo script. Non è uno strumento di automazione da “fire-and-forget”.
• Versioni in rapido movimento: nomi dei flag, variabili d’ambiente e struttura dei container OpenHands hanno cambiato più volte nel 2024. Fissate un tag di immagine esplicito (evitate :latest per sessioni che devono essere riproducibili tra mesi).

Link: github.com/All-Hands-AI/OpenHands — all-hands.dev

Stefano Noferi — Founder e CEO/CTO di noze
Tech Entrepreneur — AI Governance & Security Architect