OpenCode installeren op een VPS: stappenplan

Wat OpenCode is en wat u instelt

OpenCode is een open-source AI-codeeragent die is gebouwd voor de terminal. U start deze in een projectmap, waarna de agent uw code leest, wijzigingen voorstelt, bestanden bewerkt en commando's uitvoert, allemaal vanuit een terminal user interface (TUI). Het is gelicentieerd onder de MIT-licentie, maakt verbinding met meer dan 75 modelproviders en is met ongeveer 165,000 GitHub-sterren halverwege 2026 de meest gewaardeerde open-source codeeragent die er bestaat. Om OpenCode op een VPS te draaien, installeert u het onder een specifieke gebruiker zonder privileges, plaatst u uw model-API-key in een privébestand en start u het binnen tmux, zodat de sessie actief blijft wanneer uw verbinding wordt verbroken. Deze handleiding doorloopt precies dit proces, in die volgorde.

Eén opmerking over de naamgeving voorkomt verwarring. De canonieke repository is anomalyco/opencode, onderhouden door het Anomaly-team (voorheen bekend als SST), en het project was voorheen te vinden op sst/opencode. Er bestaat op GitHub ook een oudere, niet-gerelateerde repository genaamd opencode-ai/opencode, dus controleer of u de documentatie van het juiste project leest. De officiële website is opencode.ai.

Waarom OpenCode op een VPS draaien

Een sessie met een coding agent duurt lang. OpenCode kan vele minuten bezig zijn met een refactor of een testsuite. Als dit op uw laptop draait, beëindigt een dichtgeklapt scherm of een wegvallende wifi-verbinding de sessie midden in de taak. Op een VPS binnen tmux blijft de agent doorwerken nadat u de verbinding verbreekt, en kunt u later opnieuw koppelen om te zien wat er is uitgevoerd. Dit volgt hetzelfde patroon als Claude Code op een VPS met tmux draaien, en het is de grootste verbetering in gebruiksgemak bij het verplaatsen van een agent vanaf uw laptop.

De tweede reden is de locatie. Een VPS staat dicht bij de code die u implementeert: de repository, de build-tools, de testdatabase en vaak de staging-omgeving bevinden zich daar of in de nabijheid. Een agent die code bewerkt en tests uitvoert, werkt het beste op de machine waar die tests daadwerkelijk draaien. En omdat de server een machine is die u beheert, kunt u de agent doelbewust een geïsoleerde omgeving geven, wat in de volgende sectie wordt behandeld.

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

Geef OpenCode een eigen gebruiker

Dit is het uitgangspunt: een coding agent bewerkt bestanden en voert commando's uit. Dat is de taak, maar het vormt 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. Het account waaronder de agent draait, bepaalt de limiet van wat een foutief commando kan bereiken. Draai de agent daarom niet als root en niet als de gebruiker die de server beheert.

In tegenstelling tot een achtergrond-agent 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

Houd de projecten waaraan de agent moet werken onder /home/opencode en laat deze door die gebruiker clonen. Geef het 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 redenering als bij het draaien van services als een gebruiker zonder privileges. Werk daarnaast binnen een git-repository, omdat een repository elke ongewenste wijziging verandert in een git revert in plaats van in dataverlies.

OpenCode installeren

Het project documenteert twee installatiemethoden. Het installatiescript is de snelste optie, en door dit uit te voeren als de opencode-gebruiker blijft alles binnen de home-directory van die gebruiker:

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

De gebruikelijke curl | bash-gewoonte is hier net zo van toepassing als overal elders: download op een server die u belangrijk vindt eerst het script, lees het door en voer het daarna pas uit. Start na de installatie een nieuwe shell zodat de wijziging in de PATH die het installatieprogramma doorvoert van kracht wordt, en controleer daarna of het binaire bestand reageert:

opencode --version

Als u de voorkeur geeft aan een pakketbeheerder en Node.js al op de machine aanwezig is, installeert de npm-methode dezelfde tool systeembreed, waardoor het opencode binaire bestand voor elke gebruiker in de PATH wordt geplaatst:

sudo npm install -g opencode-ai

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

Plaats de API-sleutel in een privébestand

OpenCode heeft een sleutel nodig voor de modelprovider die u gebruikt. Omdat deze sleutel kosten kan genereren, moet u deze als een wachtwoord behandelen. Maak een bestand aan dat alleen leesbaar is voor de gebruiker opencode, met modus 600. Sla de sleutel hierin op in plaats van deze in commando's te typen, waar deze in uw shell-geschiedenis terecht zou komen:

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

Plaats de variabele van uw provider in dit bestand, bijvoorbeeld ANTHROPIC_API_KEY=... of het equivalent voor uw provider, aangezien OpenCode de standaard omgevingsvariabelen van providers herkent. Laad het bestand in uw shell voordat u de agent start:

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

OpenCode biedt ook een interactief alternatief: het commando /connect binnen de TUI leidt u door het proces van het toevoegen van een provider en slaat de inloggegevens op in ~/.local/share/opencode/auth.json in de home-directory van de gebruiker. Als u deze methode gebruikt, controleer dan met chmod 600 ~/.local/share/opencode/auth.json of het bestand privé is. Beide methoden houden de sleutel uit uw commandoregel; kies er een en wees consistent.

Start OpenCode binnen tmux

tmux maakt de VPS-configuratie waardevol, omdat een tmux-sessie actief blijft wanneer uw SSH-verbinding wordt verbroken. Start een sessie, ga naar uw projectmap en start de agent:

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

U ziet de TUI openen met een prompt onderaan en uw projectnaam in de interface. Geef een taak op in begrijpelijke taal; de agent begint vervolgens met het lezen van bestanden en het voorstellen van wijzigingen. Wanneer u wilt afsluiten, detacht u de sessie met Ctrl-b gevolgd door d. De agent blijft doorwerken terwijl uw laptop is gesloten. Maak later opnieuw verbinding met:

tmux attach -t opencode

De sessie, het gesprek en eventuele actieve taken bevinden zich exact in de staat waarin u ze heeft achtergelaten. Dit overleeft het verbreken van verbindingen, maar niet het herstarten van de server. Na een reboot start u daarom op dezelfde wijze een nieuwe tmux-sessie. Niets belet u om een tweede tmux-venster te openen en een andere agent naast de eerste te draaien. OpenCode-sessies blijven echter onafhankelijk van elkaar, terwijl Claude Code-sessies op dezelfde machine berichten naar elkaar kunnen sturen. Dit is een andere methode om een taak in tweeën te splitsen.

Koppel 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 in de TUI, dat providers weergeeft en de inloggegevens afhandelt. Voor een configuratie die u kunt vastleggen en reproduceren, plaatst u een opencode.json in de hoofdmap van het project 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 gedeclareerd. Als u een model serveert met Ollama op dezelfde VPS, wijst de configuratie naar de lokale API en is de modelnaam gelijk aan wat ollama list op uw systeem toont:

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

Het is raadzaam om vanaf de eerste dag één ingebouwde gewoonte aan te nemen. OpenCode levert twee agents waartussen u schakelt met de Tab-toets: Build, de standaardagent met volledige toegang, en Plan, die de mogelijkheid om wijzigingen aan te brengen uitschakelt. Start een nieuwe taak in Plan, laat de agent de code lezen en een aanpak voorstellen, en schakel pas over naar Build wanneer u akkoord bent met het plan. Op een server is een eerste doorloop in alleen-lezenmodus een goedkope verzekering. Claude Code hanteert voor dezelfde beslissing toestemmingsmodi in plaats van agents, en de overstap naar de automatische modus als standaard is het lezen waard als u beide tools gebruikt, omdat de modus waarin een sessie start bepaalt hoeveel een onbewaakte agent kan wijzigen.

De blast radius, eerlijk gezegd

Een coding agent is niet passief, dus wees duidelijk over wat deze configuratie wel en niet bevat. Het bevat wel bestandsschade: de opencode gebruiker is eigenaar van de eigen home-directory en niets anders, dus bewerkingen en verwijderingen stoppen bij die grens. Het bevat wel blootstelling van inloggegevens: de key bevindt zich in één bestand met mode 600, in één account. Het bevat niet wat het account legitiem kan doen; als de projectdirectory dus productie-deploy-credentials bevat, kan de agent deze gebruiken. Houd die 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 langlopende service, dus er is geen systemd unit om te schrijven en geen poort om te firewalled voor de agent zelf. De isolatie wordt gevormd door het gebruikersaccount en de projectdirectory, en daarom is het eerste deel van deze handleiding het meest belangrijk.

De omgeving eromheen vereist nog steeds de standaardzorg, omdat een coding VPS nog steeds een publieke server is: SSH alleen met keys en uitgeschakelde root-login, zoals in SSH hardening op een VPS, een default-deny firewall en routinematige updates. Controleer ook wat de agent produceert. Lees de diffs voordat u ze pusht, op dezelfde manier als u een pull request van een nieuwe bijdrager zou lezen, omdat u degene bent die het resultaat implementeert.

Houd tot slot de tool zelf actueel. OpenCode brengt vaak releases uit en updates bevatten fixes die van belang zijn voor een programma dat commando's op uw server uitvoert. Het updaten verloopt via dezelfde route als de installatie: voer het installatiescript opnieuw uit als de opencode gebruiker, of voer sudo npm update -g opencode-ai uit als u via npm heeft geïnstalleerd, en bevestig daarna de nieuwe versie met opencode --version. Een minuut onderhoud op zijn tijd is goedkoper dan het debuggen van gedrag dat in een maandenoude build al is verholpen.

FAQ

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

Ja. OpenCode behandelt elke OpenAI-compatibele server als provider, dus een model dat door Ollama op dezelfde VPS wordt aangeboden werkt: specificeer de provider in opencode.json met de lokale baseURL en de modelnaam die Ollama rapporteert. De beperking is de hardware, aangezien een model dat geschikt is voor serieus programmeerwerk aanzienlijk geheugen vereist; stem de servergrootte af op het model voordat u dit downloadt.

Hoe houd ik OpenCode actief nadat ik mijn laptop afsluit?

Draai het binnen tmux op de VPS. Start de agent in een benoemde sessie met tmux new -s opencode, ontkoppel met Ctrl-b gevolgd door d, en de sessie blijft op de server actief nadat uw SSH-verbinding is verbroken. Koppel op elk gewenst moment opnieuw met tmux attach -t opencode; het gesprek en eventuele actieve taken zijn dan nog aanwezig. Een herstart van de server beëindigt de sessie, dus start na een reboot een nieuwe sessie.

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

Dit is beheersbaar als u het isoleert. Geef OpenCode een toegewezen gebruiker zonder privileges en zonder sudo-rechten, beheer projecten in git zodat elke wijziging terugdraaibaar is, sla de API-sleutel op in een bestand met modus 600, en gebruik de Plan-agent voor een eerste controle in alleen-lezenmodus voordat u de Build-agent wijzigingen laat doorvoeren. De agent kan dan alleen schade toebrengen aan bestanden die eigendom zijn van het eigen account, terwijl de rest van de server buiten bereik blijft.

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 modelproviders, inclusief lokale modellen. Claude Code is de eigen terminal-agent van Anthropic, gebouwd rond de modellen van Anthropic. Als u één tool wilt gebruiken voor meerdere providers, of een volledig zelfgehoste stack met een lokaal model, dan is OpenCode de juiste keuze; beide draaien uitstekend op een VPS binnen tmux met dezelfde configuratie voor een gebruiker zonder privileges.