OpenCode installeren op een VPS

Wat OpenCode is en wat u installeert

OpenCode is een open-source AI-coding agent voor de terminal. U start de agent in een projectmap. De agent leest uw code, stelt wijzigingen voor, bewerkt bestanden en voert commando's uit via een terminal user interface (TUI). Het product heeft een MIT-licentie en maakt verbinding met meer dan 75 model providers. Met ongeveer 165.000 GitHub stars (medio 2026) is dit de meest gestarterde open-source coding agent. Om OpenCode op een VPS te draaien, installeert u het onder een specifieke unprivileged user. U plaatst uw model API key in een privaat bestand. Vervolgens start u de agent in tmux, zodat de sessie behouden blijft als de verbinding wegvalt. Deze handleiding beschrijft precies deze stappen, in deze volgorde.

Een opmerking over de naam voorkomt verwarring. Het officiële repository is anomalyco/opencode, beheerd door het Anomaly team (voorheen bekend als SST). Het project stond voorheen op sst/opencode. Er bestaat ook een ouder, niet-gerelateerd repository genaamd opencode-ai/opencode op GitHub. Controleer daarom of u de juiste documentatie leest. De officiële website is opencode.ai.

Waarom OpenCode op een VPS draaien

Een sessie van een coding agent duurt lang. OpenCode kan vele minuten bezig zijn met een refactor of een testsuite. Als dit op uw laptop draait, zorgt een dichtgeklapt scherm of een wegvallende Wi-Fi-verbinding ervoor dat de sessie halverwege de taak wordt afgebroken. Op een VPS binnen tmux blijft de agent doorwerken nadat u bent ontkoppeld. U kunt later opnieuw verbinden om het resultaat te bekijken. Dit is hetzelfde principe als Claude Code draaien op een VPS met tmux. Dit is het grootste voordeel voor het gebruiksgemak wanneer u een agent van uw laptop verplaatst.

De tweede reden is de locatie. Een VPS staat dicht bij de code die u deployt: de repository, de build tools, de testdatabase en vaak ook de staging environment staan al op die locatie of vlakbij. Een agent die code bewerkt en tests uitvoert, werkt het best op de machine waar die tests daadwerkelijk draaien. Omdat de server onder uw controle staat, kunt u de agent bewust een geïsoleerde omgeving geven, zoals in het volgende hoofdstuk wordt uitgelegd.

Als u nog een tool aan het kiezen bent, vergelijkt een coding AI agent draaien op een VPS het bredere veld, inclusief Aider en Goose.

Geef OpenCode een eigen gebruiker

Dit is het uitgangspunt: een coding agent bewerkt bestanden en voert commando's uit. Dit is de functie van de agent, maar ook het risico. OpenCode voert builds, tests en alle shell commando's uit die nodig zijn voor de taak. Het oordeel van het model is goed, maar niet perfect. De rechten van het account waarmee de agent werkt, bepalen de maximale impact van een foutief commando. Gebruik daarom geen root-account en gebruik niet hetzelfde account als dat van de serverbeheerder.

In tegenstelling tot een achtergrondagent is OpenCode interactief. De gebruiker heeft daarom een echte shell en een home directory nodig:

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

Plaats de projecten waaraan de agent moet werken onder /home/opencode en clone deze met die gebruiker. Geef dit account geen sudo-rechten. Als de agent een destructief commando uitvoert, kan deze alleen bestanden vernietigen die eigendom zijn van dit specifieke account. Dit is dezelfde reden waarom u services als een unprivileged user moet draaien. Werk ook binnen een git repository; een repository maakt van een foutieve bewerking een git revert in plaats van dataverlies.

OpenCode installeren

Het project beschrijft twee installatiemethoden. Het installatiescript is de snelste methode. Als u het script uitvoert als de opencode user, blijft alles binnen de home-directory van die user:

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

De gebruikelijke curl | bash werkwijze is hier van toepassing: download het script eerst naar een server waar u verantwoordelijk voor bent, lees het script, en voer het dan uit. Start na de installatie een nieuwe shell zodat de wijziging in de PATH door de installer actief wordt. Controleer daarna of het binaire bestand werkt:

opencode --version

Als u de voorkeur geeft aan een package manager en Node.js al op het systeem staat, installeert de npm-route dezelfde tool systeembreed. Hierdoor wordt het opencode binaire bestand aan de PATH toegevoegd voor elke user:

sudo npm install -g opencode-ai

In beide gevallen is de controle hetzelfde: opencode --version geeft een versienummer weer. Een command not found na de installatie via het script betekent dat de huidige shell de bijgewerkte PATH nog niet heeft ingelezen. Log in dit geval uit en opnieuw in als de opencode user.

Plaats de API-key in een privébestand

OpenCode heeft een sleutel nodig voor de gekozen modelprovider. Deze sleutel kan kosten met zich meebrengen, dus behandel deze als een wachtwoord. Maak een bestand aan met mode 600 dat alleen door de opencode-gebruiker gelezen kan worden. Bewaar de sleutel hierin in plaats van deze in commando's te typen, om te voorkomen dat de sleutel in de shell-geschiedenis terechtkomt:

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

Voeg de variabele van uw provider toe, bijvoorbeeld ANTHROPIC_API_KEY=... of het equivalent voor uw provider. OpenCode gebruikt de standaard omgevingsvariabelen van de provider. Laad het bestand in uw shell voordat u de agent start:

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

OpenCode biedt ook een interactieve optie: het /connect-commando binnen de TUI begeleidt u bij het toevoegen van een provider en slaat de gegevens op in ~/.local/share/opencode/auth.json in de home-directory van de gebruiker. Controleer bij deze methode of het bestand privé is met chmod 600 ~/.local/share/opencode/auth.json. Beide methoden zorgen ervoor dat de sleutel niet in de command-lines verschijnt; kies één methode en blijf consistent.

Start OpenCode binnen tmux

tmux is essentieel voor deze VPS-opstelling, omdat een tmux-sessie actief blijft wanneer de SSH-verbinding wordt verbroken. Start een sessie, navigeer naar uw project en start de agent:

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

De TUI wordt geopend met een prompt onderaan en uw projectnaam in de interface. Geef de agent een opdracht in gewone taal. De agent begint vervolgens bestanden te lezen en wijzigingen voor te stellen. Om de sessie te verlaten, gebruikt u Ctrl-b gevolgd door d. De agent werkt door, zelfs als uw laptop gesloten is. U kunt de sessie later opnieuw aansluiten met:

tmux attach -t opencode

De sessie, het gesprek en alle lopende taken bevinden zich nog op de plek waar u ze heeft achtergelaten. Dit blijft behouden bij verbindingsproblemen, maar niet bij een herstart van de server. Start na een herstart daarom op dezelfde wijze een nieuwe tmux-sessie.

Koppel het aan een model

OpenCode is provider-agnostisch. Het maakt gebruik van de AI SDK en de Models.dev catalogus om meer dan 75 providers te ondersteunen. Hierdoor werkt dezelfde tool met Anthropic, OpenAI, Google en tientallen anderen, inclusief lokale servers. De snelste methode is het /connect commando binnen de TUI. Dit commando toont een lijst met providers en verwerkt de credentials. Voor een configuratie die u kunt committen en reproduceren, plaatst u een opencode.json in de projectroot en stelt u het model in als provider/model-id:

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

Een lokaal model werkt via hetzelfde bestand, omdat elke OpenAI-compatibele server als provider kan worden opgegeven. Als u een model serveert met Ollama op dezelfde VPS, wijst de configuratie naar de lokale API. De modelnaam is dan de naam die ollama list op uw systeem aangeeft:

{
  "$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" } }
    }
  }
}

Eén ingebouwde gewoonte is vanaf de eerste dag aan te bevelen. OpenCode bevat twee agents die u met de Tab-toets kunt wisselen: Build, de standaard agent met volledige toegang, en Plan, waarbij de mogelijkheid om wijzigingen aan te brengen is uitgeschakeld. Start een nieuwe taak in Plan, laat de agent de code lezen en een aanpak voorstellen, en schakel pas over naar Build als u akkoord gaat met het plan. Op een server is een eerst een read-only ronde uitvoeren een goedkope verzekering.

De blast radius, eerlijk gezegd

Een coding agent is niet passief. Geef daarom duidelijk aan wat deze setup wel en niet bevat. Het bevat de mogelijkheid tot bestandsschade: de opencode user is eigenaar van de eigen home-directory en niets anders, dus wijzigingen en verwijderingen stoppen bij die grens. Het bevat het risico op blootstelling van credentials: de key staat in één bestand met mode 600, binnen één account. Het bevat niet de acties die het account legitiem kan uitvoeren. Als de projectdirectory dus credentials voor productie-deployments bevat, kan de agent deze gebruiken; houd deze volledig buiten het account van de agent.

In tegenstelling tot een gateway agent zoals OpenClaw, is OpenCode een interactief terminalprogramma en geen daemon. Het opent geen listening port en heeft geen long-running service. Er is dus geen systemd unit die geschreven moet worden en er is geen port die voor de agent zelf gefirewalled moet worden. De containment bestaat uit het user account en de projectdirectory. Daarom is de eerste sectie van deze gids de belangrijkste.

De beveiliging van de server vereist nog steeds standaard zorg, omdat een coding VPS nog steeds een publieke server is: SSH met alleen keys en root login uitgeschakeld, zoals beschreven in SSH hardening on a VPS, een default-deny firewall en regelmatige updates. Controleer ook wat de agent produceert. Lees de diffs voordat u deze pusht, op dezelfde manier als u een pull request van een nieuwe contributor zou lezen, aangezien u degene bent die het resultaat deployt.

Houd de tool zelf uiteindelijk up-to-date. OpenCode brengt regelmatig releases uit. Updates bevatten fixes die essentieel zijn voor een programma dat commando's uitvoert op uw server. Updaten gebeurt via dezelfde route als de installatie: voer het install script opnieuw uit als de opencode user, of voer sudo npm update -g opencode-ai uit als u via npm heeft geïnstalleerd, en bevestig de nieuwe versie met opencode --version. Een minuut onderhoud af en toe is goedkoper dan het debuggen van gedrag dat een oudere build al had opgelost.

FAQ

Kan OpenCode een lokaal model gebruiken in plaats van een betaalde API?

Ja. OpenCode behandelt elke OpenAI-compatibele server als een provider. Een model dat via Ollama op dezelfde VPS wordt aangeboden, werkt dus: declareer de provider in opencode.json met de lokale baseURL en de modelnaam die Ollama rapporteert. De beperkende factor is de hardware. Een model dat geschikt is voor serieus programmeerwerk vereist veel geheugen. Zorg dat de server groot genoeg is voor het model voordat u het downloadt.

Hoe blijf ik OpenCode gebruiken nadat ik mijn laptop heb afgesloten?

Draai het programma in tmux op de VPS. Start de agent in een benoemde sessie met tmux new -s opencode. Ontkoppel de sessie met Ctrl-b gevolgd door d. De sessie blijft dan doorlopen op de server nadat uw SSH-verbinding is verbroken. Koppel de sessie op elk gewenst moment opnieuw via tmux attach -t opencode; het gesprek en alle lopende taken zijn dan nog aanwezig. Een herstart van de server beëindigt de sessie. Start na een herstart een nieuwe sessie.

Is het veilig om OpenCode commando's te laten uitvoeren op mijn VPS?

Dit is beheersbaar mits u beperkingen oplegt. Geef OpenCode een toegewezen gebruiker zonder sudo-rechten. Bewaar projecten in git zodat elke wijziging ongedaan gemaakt kan worden. Sla de API-key op in een bestand met mode 600. Gebruik de Plan agent voor een eerste controle in read-only modus voordat u de Build agent toestemming geeft om wijzigingen aan te brengen. De agent kan dan alleen bestanden beschadigen die eigendom zijn van het eigen account; de rest van de server blijft onbereikbaar.

Wat is het verschil tussen OpenCode en Claude Code?

OpenCode is open source (MIT) en provider-agnostisch. Het maakt via één interface verbinding met meer dan 75 model-providers, inclusief lokale providers. Claude Code is de eigen terminal agent van Anthropic, gebouwd rond de modellen van Anthropic. Als u één tool wilt voor meerdere providers, of een volledig zelfgehoste stack met een lokaal model, dan is OpenCode de juiste keuze. Beide tools werken goed op een VPS binnen tmux met dezelfde configuratie met een gebruiker zonder privileges.