Come installare OpenCode su un VPS

Cos'è OpenCode e cosa stai configurando

OpenCode è un agente di coding AI open source progettato per il terminale. Si avvia all'interno di una directory di progetto. Il software legge il codice, propone modifiche, modifica i file ed esegue comandi tramite un'interfaccia utente da terminale (TUI). È distribuito con licenza MIT, si connette a oltre 75 provider di modelli e, con circa 165.000 stelle su GitHub a metà 2026, è l'agente di coding open source con il maggior numero di stelle. Per eseguire OpenCode su un VPS, è necessario installarlo sotto un utente non privilegiato dedicato, inserire la chiave API del modello in un file privato e avviarlo all'interno di tmux per mantenere attiva la sessione in caso di disconnessione. Questa guida esegue esattamente queste operazioni, in questo ordine.

Una nota sul nome evita confusione. Il repository canonico è anomalyco/opencode, gestito dal team Anomaly (precedentemente noto come SST), mentre il progetto si trovava originariamente su sst/opencode. Esiste anche un repository più vecchio e non correlato chiamato opencode-ai/opencode su GitHub; verifica di consultare la documentazione del progetto corretto. Il sito ufficiale è opencode.ai.

Perché eseguire OpenCode su un VPS

Una sessione di un agente di coding è lunga. OpenCode può impiegare molti minuti per completare un refactoring o una suite di test. Se viene eseguito sul laptop, la chiusura del coperchio o la perdita della connessione Wi-Fi interrompono la sessione durante il compito. Su un VPS all'interno di tmux, l'agente continua a lavorare dopo la disconnessione; è possibile ricollegarsi in seguito per leggere i risultati. Questo approccio è identico a eseguire Claude Code su un VPS con tmux ed è il principale vantaggio operativo derivante dallo spostamento di un agente dal proprio laptop.

La seconda ragione riguarda l'ubicazione. Un VPS è vicino al codice che si distribuisce: il repository, i tool di build, il database di test e spesso l'ambiente di staging risiedono già lì o nelle immediate vicinanze. Un agente che modifica il codice ed esegue i test lavora meglio sulla macchina dove i test vengono effettivamente eseguiti. Poiché il server è sotto il proprio controllo, è possibile fornire all'agente un ambiente isolato, come descritto nella sezione successiva.

Se si sta ancora scegliendo uno strumento, eseguire un agente AI di coding su un VPS confronta le varie opzioni disponibili, inclusi Aider e Goose.

Assegna a OpenCode un utente dedicato

Ecco il punto di partenza: un agente di coding modifica file ed esegue comandi. Questo è il suo compito, ma rappresenta anche un rischio. OpenCode eseguirà build, test e qualsiasi comando shell necessario per il task; il giudizio del modello è accurato, ma non perfetto. L'account con cui l'agente opera definisce il limite massimo di potenziale danno di un comando errato. Non eseguire l'agente come root e non utilizzare lo stesso utente con cui si amministra il server.

A differenza di un agente in background, OpenCode è interattivo; pertanto, il suo utente necessita di una shell reale e di una home directory:

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Mantieni i progetti su cui deve lavorare sotto /home/opencode, clonati tramite tale utente. Non assegnare all'account privilegi sudo. Se l'agente esegue un comando distruttivo, potrà danneggiare solo ciò che è di proprietà di questo singolo account; il principio è lo stesso di eseguire i servizi come utente non privilegiato. Lavora all'interno di un repository git: un repository trasforma ogni modifica errata in un git revert invece di una perdita di dati.

Install OpenCode

Il progetto documenta due modalità di installazione. L'uso dello script di installazione è il metodo più rapido; eseguendolo come utente opencode, tutti i file rimarranno nella home directory di tale utente:

curl -fsSL https://opencode.ai/install | bash

Si applica la consuetudine curl | bash standard: su un server critico, scaricare prima lo script, leggerlo e poi eseguirlo. Dopo l'installazione, avviare una nuova shell affinché le modifiche al PATH apportate dall'installer siano effettive, quindi verificare il funzionamento del binario:

opencode --version

Se si preferisce un package manager e Node.js è già presente sul sistema, il metodo npm installa lo stesso strumento a livello di sistema, aggiungendo il binario opencode al PATH per ogni utente:

sudo npm install -g opencode-ai

In entrambi i casi, il controllo è identico: opencode --version stampa il numero di versione. Un errore command not found dopo l'installazione tramite script indica che la shell corrente non ha ancora letto il PATH aggiornato; in questo caso, effettuare il logout e il login come utente opencode.

Inserire la API key in un file privato

OpenCode richiede una chiave per il provider di modelli utilizzato. Poiché la chiave può consumare il credito associato, deve essere trattata come una password. Creare un file con permessi 600, leggibile solo dall'utente opencode. Conservare la chiave in questo file per evitare di inserirla nei comandi e salvarla nella cronologia della shell:

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Inserire la variabile del provider nel file, ad esempio ANTHROPIC_API_KEY=... o l'equivalente per il proprio provider, poiché OpenCode utilizza le variabili d'ambiente standard. Caricare il file nella shell prima di avviare l'agent:

set -a; source ~/opencode.env; set +a

OpenCode offre un'alternativa interattiva: il comando /connect all'interno della TUI guida l'utente nell'aggiunta di un provider e salva le credenziali in ~/.local/share/opencode/auth.json nella home directory dell'utente. Se si utilizza questo metodo, verificare che il file sia privato con chmod 600 ~/.local/share/opencode/auth.json. Entrambi i metodi evitano di esporre la chiave nelle righe di comando; scegliere un metodo e mantenerlo costante.

Avvia OpenCode all'interno di tmux

tmux è l'elemento fondamentale per l'uso del VPS, poiché una sessione tmux rimane attiva anche dopo la chiusura della connessione SSH. Avviane una, accedi alla cartella del progetto e lancia l'agent:

tmux new -s opencode
cd ~/my-project
opencode

Dovresti vedere l'apertura della TUI con un prompt in basso e il nome del progetto nell'interfaccia. Inserisci un comando in linguaggio naturale e l'agent inizierà a leggere i file e a proporre modifiche. Per uscire, stacca la sessione con Ctrl-b seguito da d; l'agent continuerà a lavorare anche con il laptop chiuso. Per riagganciare la sessione in seguito, usa:

tmux attach -t opencode

La sessione, la conversazione e ogni task in esecuzione rimarranno esattamente dove li hai lasciati. Questo processo sopravvive alle disconnessioni, ma non al riavvio del server; pertanto, dopo un reboot, è necessario avviare una nuova sessione tmux seguendo la stessa procedura.

Configura un model

OpenCode è agnostico rispetto al provider. Utilizza l'AI SDK e il catalogo Models.dev per supportare oltre 75 provider; lo stesso strumento funziona con Anthropic, OpenAI, Google e decine di altri, inclusi i server locali. La procedura rapida consiste nell'usare il comando /connect all'interno della TUI, che elenca i provider e gestisce le credenziali. Per una configurazione riproducibile e committabile, inserisci un opencode.json nella root del progetto e imposta il model come provider/model-id:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514"
}

Un model locale funziona tramite lo stesso file, poiché qualsiasi server compatibile con OpenAI può essere dichiarato come provider. Se utilizzi Ollama sullo stesso VPS, la configurazione punta alla sua API locale e il nome del model è quello indicato da ollama list sul sistema:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

È consigliabile adottare un'abitudine specifica fin dall'inizio. OpenCode include due agent che si alternano con il tasto Tab: Build, l'agent predefinito con accesso completo, e Plan, che disabilita la possibilità di apportare modifiche. Avvia un nuovo task in modalità Plan, lascia che legga il codice e proponga un approccio, e passa alla modalità Build solo quando approvi il piano. Su un server, un primo passaggio in sola lettura è una misura di sicurezza economica.

L'ambito di impatto, in sintesi

Un agente di coding non è passivo; è necessario specificare chiaramente cosa include e cosa non include questa configurazione. Include il rischio di danneggiamento dei file: l'utente opencode possiede solo la propria home directory e nient'altro, quindi le modifiche e le eliminazioni si fermano a quel limite. Include il rischio di esposizione delle credenziali: la chiave è salvata in un singolo file con modalità 600, in un unico account. Non include le azioni che l'account può legittimamente eseguire; se la directory del progetto contiene credenziali per il deploy in produzione, l'agente può utilizzarle. Mantenete tali credenziali completamente al di fuori dell'account dell'agente.

A differenza di un gateway agent come OpenClaw, OpenCode è un programma terminale interattivo, non un daemon. Non apre alcuna porta in ascolto e non ha servizi a lunga esecuzione; pertanto, non è necessario scrivere un'unità systemd né configurare firewall per l'agente stesso. Il contenimento è garantito dall'account utente e dalla directory del progetto; per questo motivo, la prima sezione di questa guida è la più importante.

Il sistema richiede comunque la manutenzione standard, poiché un VPS per il coding è comunque un server pubblico: SSH con accesso tramite chiave e login root disabilitato, come descritto in SSH hardening on a VPS, un firewall con policy default-deny e aggiornamenti periodici. Verificate inoltre l'output dell'agente. Leggete i diff prima di eseguire il push, esattamente come fareste con una pull request di un nuovo collaboratore, poiché siete voi a distribuire il risultato finale.

Infine, mantenete il tool aggiornato. OpenCode rilascia aggiornamenti frequenti che contengono correzioni essenziali per un programma che esegue comandi sul server. L'aggiornamento utilizza lo stesso metodo dell'installazione: eseguite lo script di installazione come utente opencode, oppure eseguite sudo npm update -g opencode-ai se l'installazione è avvenuta tramite npm, quindi verificate la nuova versione con opencode --version. Un minuto di manutenzione periodica è più economico che debuggare comportamenti già risolti da una build di mesi fa.

FAQ

OpenCode può utilizzare un modello locale invece di un'API a pagamento?

Sì. OpenCode considera qualsiasi server compatibile con OpenAI come un provider. Un modello servito da Ollama sullo stesso VPS è quindi compatibile: dichiara il provider in opencode.json con l'indirizzo locale baseURL e il nome del modello riportato da Ollama. Il limite è l'hardware: un modello adatto al coding richiede molta memoria. Verifica le risorse del server prima di scaricare il modello.

Come posso mantenere OpenCode in esecuzione dopo aver chiuso il laptop?

Eseguilo all'interno di tmux sul VPS. Avvia l'agent in una sessione nominata con tmux new -s opencode, stacca la sessione con Ctrl-b poi d; la sessione rimarrà attiva sul server dopo la chiusura della connessione SSH. Riconnetti la sessione in qualsiasi momento con tmux attach -t opencode per ritrovare la conversazione e i task in corso. Un riavvio del server termina la sessione; in tal caso, avvia una nuova sessione dopo il reboot.

È sicuro lasciare che OpenCode esegua comandi sul mio VPS?

Il rischio è gestibile con le giuste restrizioni. Assegna a OpenCode un utente dedicato non privilegiato senza permessi sudo. Mantieni i progetti in git per rendere reversibili ogni modifica. Salva la chiave API in un file con permessi 600. Usa il Plan agent per una prima analisi in sola lettura prima di autorizzare il Build agent a modificare i file. In questo modo l'agent può danneggiare solo i file di proprietà del proprio account, lasciando il resto del server protetto.

Qual è la differenza tra OpenCode e Claude Code?

OpenCode è open source (MIT) e agnostico rispetto al provider: si connette a oltre 75 provider di modelli, inclusi quelli locali, tramite un'unica interfaccia. Claude Code è l'agent terminale di Anthropic, progettato per i modelli Anthropic. Se necessiti di uno strumento unico per molti provider, o di uno stack completamente self-hosted con un modello locale, OpenCode è la scelta corretta. Entrambi funzionano correttamente su un VPS all'interno di tmux con la stessa configurazione di utente non privilegiato.