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 a supporto 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). Va usato con approval: è un collaboratore che chiede conferma prima di agire.
Link: opencode.ai — github.com/sst/opencode