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 opdrachten uitvoert, allemaal vanuit een terminal user interface (TUI). Het project is MIT-gelicentieerd, maakt verbinding met meer dan 75 modelproviders en is met ongeveer 219.000 GitHub-sterren per oktober 2026 de open-source codeeragent met de meeste GitHub-sterren die er bestaat. Om OpenCode op een VPS uit te voeren, installeert u het onder een toegewezen gebruiker zonder privileges, plaatst u uw model-API-sleutel in een privébestand en start u het binnen tmux zodat de sessie actief blijft wanneer uw verbinding wordt verbroken. Deze handleiding doet precies dat, 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 bevond zich voorheen op sst/opencode. Er bestaat op GitHub ook een oudere, niet-gerelateerde repository genaamd opencode-ai/opencode, die inmiddels is gearchiveerd; controleer dus 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 eerlijke uitgangspunt: een coding agent bewerkt bestanden en voert commando's uit. Dat is zijn taak, maar het vormt ook het risico. OpenCode voert builds, tests en alle shell-commando's uit die de taak vereist, en het oordeel van het model is goed, maar niet perfect. Het account waaronder de agent draait, bepaalt de grens van wat een foutief commando kan bereiken. Draai de agent daarom niet als root en gebruik niet hetzelfde account als dat waarmee u de server beheert.

In tegenstelling tot een achtergrondproces is OpenCode interactief, dus heeft de gebruiker 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 volgt dezelfde logica als het draaien van services als een gebruiker zonder privileges. Werk daarnaast binnen een git-repository en commit uw wijzigingen voordat u de agent een taak geeft. Een foutieve bewerking in gecommitteerd werk is dan slechts een git revert of git restore verwijderd van herstel, in plaats van een definitief verlies. Wijzigingen die u nooit heeft gecommit, zijn niet beschermd.

OpenCode installeren

Het project documenteert verschillende installatiemethoden, waarvan er twee geschikt zijn voor een server. Het installatiescript is de snelste methode; 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 vervolgens of het binaire bestand reageert:

opencode --version

Geeft u de voorkeur aan een pakketbeheerder en is Node.js al aanwezig op het systeem, dan installeert de npm-methode dezelfde tool in de globale prefix van npm:

sudo npm install -g opencode-ai

Bij een systeembrede Node.js is die prefix meestal /usr/local of /usr, waarvan de bin-directory in de PATH van elke gebruiker staat. Een versiebeheerder of een aangepaste prefix plaatst het binaire bestand ergens anders; voer daarom eerst npm prefix -g uit als u wilt dat opencode wordt gevonden door de opencode-gebruiker.

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

Beide commando's installeren de OpenCode 1.x-lijn, die nog steeds releases uitbrengt (1.19.3 op 16 oktober 2026), en deze handleiding beschrijft die lijn. OpenCode 2 is inmiddels beschikbaar als een afzonderlijke installatie, via https://opencode.ai/v2/install of het npm-pakket @opencode/cli, en werkt anders: een gedeelde achtergrondserver per gebruikersaccount beheert sessies, rechten en tool-executie, en de terminal maakt hiermee verbinding. De migratiehandleiding adviseert om een via een pakketbeheerder geïnstalleerde 1.x-versie te verwijderen voordat versie 2 wordt geïnstalleerd, omdat beide gebruikmaken van het opencode-commando.

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 het aan een model

OpenCode is provider-agnostisch. Het gebruikt 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 route 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-5-5"
}

Kies een model dat uw provider nog aanbiedt: Anthropic heeft claude-sonnet-4-20250514 op 15 juni 2026 uitgefaseerd, dus configuraties die dit nog benoemen, falen.

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 wat ollama list op uw systeem weergeeft:

{
  "$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 het waard om vanaf dag één toe te passen. OpenCode levert twee agents waar u tussen schakelt met de Tab-toets: Build, de standaardagent met volledige toegang, en Plan, een beperkte agent voor analyse die weigert bestanden buiten zijn eigen plan-directory te bewerken zonder toestemming te vragen. Plan is echter niet strikt alleen-lezen, omdat het nog steeds shell-commando's kan uitvoeren, en een shell-commando kan bestanden wijzigen. Start een nieuwe taak in Plan, laat het de code lezen en een aanpak voorstellen, en schakel pas over naar Build wanneer u akkoord bent met het plan. Als u wilt dat die eerste fase echt alleen-lezen is, blokkeer dan bewerkingen en shell-commando's voor Plan in opencode.json, omdat OpenCode deny behandelt als een blokkering van de actie, terwijl ask u alleen om goedkeuring vraagt:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

Op een server is een eerste fase die niets kan wijzigen een goedkope verzekering. Claude Code kadert dezelfde beslissing in als permissiemodi 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 impact van een incident

Een coding agent is niet passief. Geef daarom duidelijk aan wat deze configuratie wel en niet bevat. Het bevat risico op bestandsschade: de opencode gebruiker is eigenaar van de eigen home-directory en niets anders, waardoor bewerkingen en verwijderingen bij die grens stoppen. Het bevat risico op blootstelling van inloggegevens: de key bevindt zich in één bestand met mode 600, binnen één account. Het bevat niet de beperkingen van wat het account legitiem kan doen; als de projectdirectory dus productie-deploy-credentials bevat, kan de agent deze gebruiken. Houd dergelijke gegevens volledig buiten het account van de agent.

In tegenstelling tot een gateway-agent zoals OpenClaw, is OpenCode 1.x een interactief terminalprogramma en geen daemon. Standaard opent het geen luisterende poort (alleen de --port, --hostname of --mdns flags zorgen ervoor dat de TUI luistert) en er is geen langlopende service, dus er is geen systemd-unit om te schrijven en geen poort om te firewalled voor de agent zelf. OpenCode 2 verandert dit met een gedeelde achtergrondserver; controleer dit punt dus opnieuw voordat u migreert. De isolatie wordt gevormd door het gebruikersaccount en de projectdirectory, wat de reden is dat het eerste deel van deze handleiding het meest cruciaal is.

De omgeving eromheen vereist nog steeds de standaard zorg, aangezien een coding VPS nog steeds een publieke server is: SSH alleen via keys met root-login uitgeschakeld, zoals in SSH-verharding op een VPS, een default-deny firewall en periodieke updates. Controleer bovendien 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 regelmatig updates uit en deze bevatten fixes die belangrijk zijn voor een programma dat opdrachten op uw server uitvoert. Het bijwerken 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. Beide methoden houden u op de 1.x-lijn; overstappen naar OpenCode 2 is een afzonderlijke migratie. 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 een provider. Een model dat door Ollama op dezelfde VPS wordt aangeboden, werkt dus ook: specificeer de provider in opencode.json met de lokale baseURL en de modelnaam die Ollama rapporteert. Het knelpunt is de hardware; een model dat geschikt is voor serieus programmeerwerk vereist aanzienlijk geheugen. Stem de servercapaciteit daarom af op het model voordat u het 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, koppel los met Ctrl-b gevolgd door d. 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 steeds 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 proces isoleert. Geef OpenCode een toegewezen gebruiker zonder privileges (geen sudo), beheer projecten in git en voer voor elke taak een commit uit zodat een foutieve wijziging kan worden teruggedraaid. Sla de API-sleutel op in een bestand met modus 600 en gebruik de Plan-agent voor een eerste controle voordat u de Build-agent wijzigingen laat doorvoeren. Stel bewerkingen en shell-commando's in op deny voor Plan als u wilt dat die fase strikt alleen-lezen is. De agent kan dan alleen schade toebrengen aan bestanden die eigendom zijn van zijn eigen account; de rest van de server blijft buiten bereik.

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 goed op een VPS binnen tmux met dezelfde configuratie voor een gebruiker zonder privileges.