Come eseguire OpenCode su un VPS con tmux

Che cos'è OpenCode e cosa configurerai

OpenCode è un agente di codifica AI open source progettato per il terminale. Viene avviato all'interno di una directory di progetto e legge il codice, propone modifiche, modifica i file ed esegue comandi, tutto tramite un'interfaccia utente del terminale (TUI). È distribuito con licenza MIT, si connette a più di 75 provider di modelli e, con circa 165,000 stelle su GitHub a metà del 2026, è l'agente di codifica open source con più stelle. Per eseguire OpenCode su un VPS, installalo con un utente dedicato senza privilegi, inserisci la chiave API del modello in un file privato e avvialo all'interno di tmux, in modo che la sessione sopravviva all'interruzione della connessione. Questa guida esegue esattamente queste operazioni, in quest'ordine.

Una precisazione sui nomi evita confusione. Il repository canonico è anomalyco/opencode, gestito dal team Anomaly, precedentemente noto come SST, e il progetto si trovava in precedenza all'indirizzo sst/opencode. Su GitHub esiste anche un repository distinto e non correlato denominato opencode-ai/opencode, quindi verifica di consultare la documentazione del progetto corretto. Il sito ufficiale è opencode.ai.

Perché eseguire OpenCode su un VPS

Una sessione con un agente di coding può durare a lungo. 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 interrompe la sessione durante l'attività. Su un VPS, all'interno di tmux, l'agente continua a lavorare dopo la disconnessione. In seguito puoi riconnetterti per leggere ciò che ha fatto. È lo stesso approccio descritto in eseguire Claude Code su un VPS con tmux e rappresenta il principale vantaggio pratico dello spostamento dell'agente dal laptop.

Il secondo motivo riguarda la posizione. Un VPS è vicino al codice che distribuisci: il repository, gli strumenti di build, il database di test e spesso anche l'ambiente di staging si trovano già sul server o nelle sue vicinanze. Un agente che modifica il codice ed esegue i test funziona meglio sulla macchina in cui i test vengono effettivamente eseguiti. Inoltre, poiché il server è sotto il tuo controllo, puoi assegnare intenzionalmente all'agente un ambiente isolato, come descritto nella sezione successiva.

Se devi ancora scegliere uno strumento, eseguire un agente di coding basato sull'AI su un VPS confronta le principali alternative, tra cui Aider e Goose.

Assegna a OpenCode un utente dedicato

Il punto di partenza è questo: un agente di coding modifica file ed esegue comandi. Questo è il suo compito, ma anche il rischio. OpenCode eseguirà build, test e i comandi shell necessari per l'attività; il giudizio del modello è buono, ma non perfetto. L'account con cui l'agente viene eseguito determina il limite massimo di ciò che un comando dannoso può raggiungere. Non eseguirlo quindi come root e non usare lo stesso utente che amministra il server.

A differenza di un agente in background, OpenCode è interattivo. Il suo utente deve quindi disporre di una shell reale e di una directory home:

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

Mantieni i progetti su cui deve lavorare sotto /home/opencode e clona i repository con quell'utente. Non concedere all'account alcun diritto sudo. Se l'agente esegue un comando distruttivo, può eliminare soltanto ciò che appartiene a questo account. È lo stesso principio di eseguire i servizi con un utente non privilegiato. Lavora inoltre all'interno di un repository git: un repository trasforma ogni modifica errata in un git revert anziché in una perdita.

Installare OpenCode

Il progetto documenta due modalità di installazione. Lo script di installazione è il metodo più rapido e, eseguendolo come utente opencode, tutti i file restano nella home di quell'utente:

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

Qui vale la consueta buona pratica di curl | bash, come in ogni altro caso: su un server importante, scarica prima lo script, leggilo e solo dopo eseguilo. Al termine dell'installazione, avvia una nuova shell affinché diventi effettiva la modifica al PATH apportata dall'installer, quindi verifica che il binario restituisca una risposta:

opencode --version

Se preferisci un package manager e Node.js è già installato sul server, il metodo npm installa lo stesso strumento a livello di sistema. Il binario opencode sarà quindi disponibile nel PATH per tutti gli utenti:

sudo npm install -g opencode-ai

In entrambi i casi, il controllo è identico: opencode --version visualizza un numero di versione. Un command not found dopo l'installazione tramite script indica che la shell corrente non ha ancora ricaricato il PATH aggiornato. Disconnettiti e accedi nuovamente come utente opencode.

Inserire la chiave API in un file privato

OpenCode richiede una chiave per il provider del modello utilizzato. Questa chiave può generare costi, quindi va trattata come una password. Create un file leggibile soltanto dall'utente opencode, con modalità 600, e conservatevi la chiave invece di inserirla nei comandi, dove finirebbe nella cronologia della shell:

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

Inserite nel file la variabile del provider, ad esempio ANTHROPIC_API_KEY=... o l'equivalente previsto dal provider, perché OpenCode utilizza le variabili d'ambiente standard dei provider. Caricate il file nella shell prima di avviare l'agent:

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

OpenCode offre anche un'alternativa interattiva: il comando /connect all'interno della TUI guida l'utente nell'aggiunta di un provider e salva la credenziale in ~/.local/share/opencode/auth.json nella home dell'utente. Se scegliete questa modalità, verificate che il file sia privato con chmod 600 ~/.local/share/opencode/auth.json. Entrambe le modalità impediscono che la chiave compaia nelle righe di comando; sceglietene una e usatela sempre.

Avvia OpenCode all’interno di tmux

tmux rende davvero utile la configurazione sul VPS, perché una sessione tmux continua a funzionare quando la connessione SSH termina. Avviane una, spostati nel progetto e avvia l’agente:

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

Dovresti vedere la TUI con un prompt in fondo e il nome del progetto nell’interfaccia. Assegna un’attività in linguaggio naturale: l’agente inizierà a leggere i file e a proporre modifiche. Quando vuoi uscire, esegui il detach con Ctrl-b quindi d; l’agente continuerà a lavorare anche con il laptop chiuso. Puoi ricollegarti in seguito con:

tmux attach -t opencode

La sessione, la conversazione e le eventuali attività in esecuzione saranno esattamente nello stato in cui le hai lasciate. Questo resiste alle disconnessioni, ma non al riavvio del server; dopo un riavvio devi quindi avviare una nuova sessione tmux nello stesso modo. Puoi anche aprire una seconda finestra tmux ed eseguire un altro agente accanto al primo. Le sessioni OpenCode restano però indipendenti, mentre le sessioni Claude Code sullo stesso server possono inviarsi messaggi, offrendo un modo diverso di suddividere un’attività in due.

Indicare il modello

OpenCode è indipendente dal provider. Usa AI SDK e il catalogo Models.dev per supportare più di 75 provider. Lo stesso strumento funziona quindi con Anthropic, OpenAI, Google e decine di altri provider, inclusi i server locali. Il percorso più rapido è il comando /connect all'interno della TUI. Il comando elenca i provider e gestisce le credenziali. Per una configurazione riproducibile e archiviabile nel repository, crea un file opencode.json nella directory radice del progetto e imposta il modello con provider/model-id:

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

Un modello locale usa lo stesso file, perché qualsiasi server compatibile con OpenAI può essere dichiarato come provider. Se esegui un modello con Ollama sullo stesso VPS, la configurazione punta alla relativa API locale. Il nome del modello corrisponde a quello mostrato da ollama list sul tuo 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" } }
    }
  }
}

Conviene adottare fin dall'inizio una modalità operativa integrata. OpenCode include due agenti, tra i quali puoi passare con il tasto Tab: Build, l'agente predefinito con accesso completo, e Plan, che disabilita la possibilità di apportare modifiche. Inizia una nuova attività in Plan. Lascia che legga il codice e proponga un approccio. Passa a Build solo dopo aver approvato il piano. Su un server, una prima analisi in sola lettura riduce il rischio con un costo minimo. Claude Code presenta la stessa scelta come modalità di autorizzazione anziché come agenti. Se usi entrambi gli strumenti, conviene leggere il passaggio alla modalità automatica come impostazione predefinita, perché la modalità con cui inizia una sessione determina quanto un agente non supervisionato può modificare.

Il perimetro del danno, in pratica

Un coding agent non è passivo. È quindi importante chiarire cosa contiene questa configurazione e cosa non contiene. Contiene i danni ai file: l'utente opencode è proprietario della propria home e di nient'altro, quindi le modifiche e le eliminazioni si fermano a quel confine. Contiene l'esposizione delle credenziali: la chiave si trova in un solo file con modalità 600, associato a un solo account. Non contiene ciò che l'account può legittimamente utilizzare. Se la directory del progetto contiene credenziali per il deployment in produzione, l'agent può usarle. Mantienile quindi completamente fuori dall'account dell'agent.

A differenza di un gateway agent come OpenClaw, OpenCode è un programma interattivo da terminale, non un daemon. Non apre porte in ascolto e non dispone di un servizio a esecuzione prolungata. Non è quindi necessario creare un'unità systemd né configurare una regola firewall per una porta dell'agent. Il contenimento è affidato all'account utente e alla directory del progetto. Per questo la prima sezione di questa guida è quella più importante.

Anche il server che lo ospita richiede la gestione standard, perché un VPS per il coding è comunque un server pubblico: SSH con accesso tramite sole chiavi e login root disabilitato, come descritto in Hardening di SSH su un VPS, un firewall con criterio default-deny e aggiornamenti regolari. Devi inoltre verificare ciò che produce l'agent. Leggi le differenze prima di inviarle, come leggeresti una pull request di un nuovo collaboratore, perché sei tu a eseguire il deployment del risultato.

Infine, mantieni aggiornato lo strumento. OpenCode pubblica spesso nuove release e gli aggiornamenti includono correzioni importanti per un programma che esegue comandi sul server. L'aggiornamento usa lo stesso metodo con cui hai eseguito l'installazione: esegui nuovamente lo script di installazione come utente opencode oppure esegui sudo npm update -g opencode-ai se hai installato tramite npm. Verifica quindi la nuova versione con opencode --version. Un minuto di manutenzione ogni tanto costa meno del troubleshooting di un comportamento già corretto in una build vecchia di mesi.

FAQ

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

Sì. OpenCode tratta qualsiasi server compatibile con OpenAI come un provider, quindi funziona anche con un modello fornito da Ollama sullo stesso VPS: dichiarare il provider in opencode.json usando il baseURL locale e il nome del modello riportato da Ollama. Il limite è l'hardware, perché un modello abbastanza valido per attività di sviluppo reali richiede molta memoria. Dimensionare quindi il server in base al modello prima di scaricarlo.

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

Eseguirlo all'interno di tmux sul VPS. Avviare l'agente in una sessione denominata con tmux new -s opencode, scollegarsi con Ctrl-b seguito da d; la sessione continuerà a essere eseguita sul server dopo la chiusura della connessione SSH. È possibile ricollegarsi in qualsiasi momento con tmux attach -t opencode: la conversazione e le attività in esecuzione saranno ancora disponibili. Un riavvio del server termina la sessione, quindi dopo il riavvio è necessario avviarne una nuova.

È sicuro consentire a OpenCode di eseguire comandi sul mio VPS?

È gestibile se lo si limita correttamente. Assegnare a OpenCode un utente non privilegiato dedicato, senza sudo, mantenere i progetti in git per rendere reversibile ogni modifica, archiviare la chiave API in un file con modalità 600 e usare l'agente Plan per una prima analisi in sola lettura prima di consentire all'agente Build di modificare qualsiasi elemento. In questo modo l'agente potrà danneggiare soltanto le risorse di proprietà del proprio account, mentre il resto del server rimarrà fuori dalla sua portata.

Qual è la differenza tra OpenCode e Claude Code?

OpenCode è open source (MIT) e indipendente dal provider. Si connette a più di 75 provider di modelli, inclusi quelli locali, tramite un'unica interfaccia. Claude Code è l'agente da terminale di Anthropic, progettato per i modelli di Anthropic. Se serve uno strumento unico per più provider o uno stack completamente self-hosted con un modello locale, OpenCode è la scelta adatta. Entrambi funzionano bene su un VPS all'interno di tmux, usando la stessa configurazione con un utente non privilegiato.