Note preliminari
Il contenuto di questo tutorial è fornito “as-is”, senza garanzie. Prima di eseguirlo in produzione:
- Provate su una VM o un server di laboratorio isolato.
- Effettuate un backup di file, configurazioni e database coinvolti (es.
/etc, home utenti, dump DB). - Non inserite secrets (password, token API, chiavi SSH, dati personali) nei prompt, nei file di configurazione versionati o nei log dell’agente.
- Un agente con endpoint cloud invia porzioni del vostro ambiente a un provider terzo: per dati regolati usate modelli locali (Ollama) o endpoint self-hosted.
- L’ecosistema agentic evolve rapidamente: verificate le release notes della versione che installate.
Cosa è opencode
opencode è un agent da terminale pubblicato dal team SST come progetto open source con licenza MIT (opencode.ai). La caratteristica che ci interessa per l’ops remoto è che è una CLI a sé stante, installabile in un binario, capace di operare nella directory di lavoro corrente della sessione. Quando lanciato dentro una sessione SSH, l’agente eredita l’ambiente del server remoto: legge file locali al server, esegue comandi locali al server, non tocca la workstation dell’operatore.
Il modello di interazione è quello di un REPL con approval esplicito per le azioni che modificano lo stato del sistema. opencode supporta provider cloud (Anthropic, OpenAI, ecc.) e runtime locali compatibili OpenAI API (Ollama, vLLM).
Caso d’uso: triage di un server Linux gestito
Scenario tipico di un MSP: riceviamo un alert di degrado su un server cliente. Vogliamo effettuare un primo triage guidato — log recenti, stato dei servizi, aggiornamenti pendenti — senza copiare manualmente decine di comandi e incollare output in una chat.
1. Connessione e installazione controllata
ssh operatore@srv-cliente.example
# Installazione per utente, senza toccare il sistema:
curl -fsSL https://opencode.ai/install | bash -s -- --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
opencode --versionL’installer scrive in $HOME/.local/bin: non richiede sudo, non modifica pacchetti di sistema, e lascia una traccia pulita. Chi preferisce pacchettizzare può scaricare il binario dai release tag e distribuirlo via Ansible.
2. Configurare un endpoint senza esporre secrets
La chiave API non va messa in plaintext in un file committato. Opzioni:
# Variabile d'ambiente, scoped alla sessione corrente:
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
# Oppure endpoint locale via Ollama, senza chiavi:
export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
export OPENAI_API_KEY="ollama"Per ambienti regolati raccomandiamo la seconda opzione: l’agente parla con un modello in esecuzione sullo stesso host o su un nodo interno, e nessun dato lascia l’infrastruttura.
3. Aprire una working directory di lavoro
mkdir -p ~/ops-session && cd ~/ops-session
opencodeLa directory ~/ops-session è un workspace vuoto dedicato: l’agente scriverà eventuali note, script temporanei o report qui, senza contaminare /etc o le home degli utenti.
4. Prompt concreti e verificabili
All’interno del REPL, prompt mirati ottengono output utili:
- “Raccogli gli ultimi 200 errori di journalctl delle ultime 24 ore, raggruppali per unit e riassumi i top 5 problemi ricorrenti.”
- “Verifica quali pacchetti hanno aggiornamenti di sicurezza disponibili con
apt list --upgradablee mostra solo quelli marcati -security.” - “Controlla lo stato di
nginx.service,postgresql.serviceeredis.service, e se uno è failed mostra le ultime 50 righe di log relative.”
opencode proporrà i comandi prima di eseguirli. In MSP è opportuno mantenere l’approval manuale su ogni comando: lanciare direttamente in “auto” espone a cambi di stato involontari.
5. Interventi con diff e backup
Per modifiche a file di configurazione, un prompt del tipo:
“Proponi un diff su /etc/nginx/sites-available/api.conf che abiliti il gzip solo per MIME type application/json e text/css. Mostrami prima il diff, non scrivere nulla.”
Approccio consigliato:
- Far produrre solo il diff senza applicare.
- Copia manuale di
api.confinapi.conf.bak.$(date +%F). - Approvare l’applicazione del diff.
nginx -tprima del reload.
Il git init in una directory come /etc non è universalmente accettabile su server di produzione, ma un backup datato dei file toccati è un minimo irrinunciabile.
Limiti e cose da non fare
- Non lasciare opencode in background con auto-approve: su un server produzione è una superficie di attacco involontaria.
- Non inserire mai chiavi SSH, password di database, token cloud nei prompt. L’agente li rispedirà al provider LLM.
- Non usare endpoint cloud per host con dati personali (sanitari, PA) senza una valutazione DPIA esplicita: preferire Ollama locale.
- I log della sessione opencode (
~/.local/share/opencode/nelle versioni correnti) vanno considerati sensibili quanto i log di shell e rimossi dopo la sessione se contengono dettagli di clienti.
Cosa porta via un MSP
Usato in questo modo, opencode diventa uno strumento di assistenza al triage, non un sostituto dell’operatore. Il valore è nella sintesi veloce di log, nella generazione di diff proposti che restano a revisione umana, e nella riproducibilità (il transcript della sessione è un audit trail leggibile). Da evitare l’uso in modalità autonoma: è un collaboratore con approval, non un runbook.
Link: opencode.ai — github.com/sst/opencode