OpenCode auf VPS installieren und nutzen

Was OpenCode ist und was Sie einrichten

OpenCode ist ein Open-Source-KI-Coding-Agent für das Terminal. Sie starten ihn innerhalb eines Projektverzeichnisses. Er liest Ihren Code, schlägt Änderungen vor, bearbeitet Dateien und führt Befehle aus, alles über eine Terminal-Benutzeroberfläche (TUI). Das Projekt ist unter der MIT-Lizenz lizenziert und verbindet sich mit mehr als 75 Model-Providern. Mit etwa 165.000 GitHub-Sternen (Stand Mitte 2026) ist es der am häufigsten mit Sternen markierte Open-Source-Coding-Agent. Um OpenCode auf einem VPS auszuführen, installieren Sie es unter einem dedizierten, unprivilegierten Benutzer, speichern Ihren Model-API-Key in einer privaten Datei und starten es innerhalb von tmux, damit die Sitzung bei einem Verbindungsabbruch erhalten bleibt. Diese Anleitung führt genau diese Schritte in dieser Reihenfolge aus.

Ein Hinweis zur Benennung vermeidet Verwechslungen. Das offizielle Repository ist anomalyco/opencode, verwaltet vom Anomaly-Team (ehemals SST). Das Projekt befand sich früher unter sst/opencode. Ein älteres, nicht verwandtes Repository namens opencode-ai/opencode existiert ebenfalls auf GitHub; stellen Sie daher sicher, dass Sie die Dokumentation des richtigen Projekts lesen. Die offizielle Website ist opencode.ai.

Warum OpenCode auf einem VPS ausführen

Eine Session eines Coding-Agents dauert lange. OpenCode benötigt oft viele Minuten für ein Refactoring oder eine Test-Suite. Wenn der Agent auf Ihrem Laptop läuft, beendet ein zugeklappter Deckel oder eine getrennte Wi-Fi-Verbindung die Session während der Aufgabe. Auf einem VPS innerhalb von tmux arbeitet der Agent nach Ihrer Abmeldung weiter. Sie können die Session später wieder aufnehmen, um das Ergebnis zu lesen. Dies entspricht dem Vorgehen beim Ausführen von Claude Code auf einem VPS mit tmux. Dies ist der größte Vorteil für die Handhabung, wenn man einen Agenten vom lokalen Laptop auf einen Server verlagert.

Der zweite Grund ist der Standort. Ein VPS befindet sich in der Nähe des zu bereitstellenden Codes: Das Repository, die Build-Tools, die Test-Datenbank und oft auch die Staging-Umgebung befinden sich bereits dort oder in unmittelbarer Nähe. Ein Agent, der Code bearbeitet und Tests ausführt, arbeitet am effizientesten auf der Maschine, auf der auch die Tests tatsächlich laufen. Da Sie den Server kontrollieren, können Sie dem Agenten eine isolierte Umgebung zuweisen, wie im nächsten Abschnitt beschrieben.

Falls Sie noch bei der Auswahl eines Tools sind: Das Ausführen eines Coding-KI-Agenten auf einem VPS vergleicht verschiedene Optionen, einschließlich Aider und Goose.

Erstellen Sie einen eigenen Benutzer für OpenCode

Dies ist die grundlegende Ausgangslage: Ein Coding-Agent bearbeitet Dateien und führt Befehle aus. Das ist seine Aufgabe, stellt aber gleichzeitig ein Risiko dar. OpenCode führt Builds, Tests und alle Shell-Befehle aus, die für die Aufgabe erforderlich erscheinen. Die Einschätzung des Modells ist gut, aber nicht fehlerfrei. Die Berechtigungen des Benutzerkontos begrenzen den Schaden, den ein fehlerhafter Befehl anrichten kann. Führen Sie OpenCode daher nicht als root aus und nutzen Sie nicht dasselbe Konto, mit dem Sie den Server verwalten.

Im Gegensatz zu einem Hintergrund-Agenten ist OpenCode interaktiv. Daher benötigt der Benutzer eine echte Shell und ein Home-Verzeichnis:

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

Speichern Sie die Projekte, an denen der Agent arbeiten soll, unter /home/opencode und klonen Sie diese mit diesem Benutzer. Geben Sie dem Konto keine sudo-Rechte. Falls der Agent einen destruktiven Befehl ausführt, kann er nur die Daten zerstören, die diesem einen Konto gehören. Dies entspricht der Logik von Diensten, die als unprivilegierter Benutzer ausgeführt werden. Arbeiten Sie zudem innerhalb eines git-Repositorys, da ein Repository jede fehlerhafte Bearbeitung in einen git revert verwandelt, anstatt einen Datenverlust zu verursachen.

OpenCode installieren

Das Projekt beschreibt zwei Installationsmethoden. Das Installationsskript ist der schnellste Weg. Wenn Sie das Skript als opencode-User ausführen, verbleiben alle Dateien im Home-Verzeichnis dieses Users:

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

Es gilt die übliche curl | bash-Vorgehensweise: Laden Sie das Skript zuerst herunter, lesen Sie es durch und führen Sie es erst dann aus, wenn Sie einen Server verwalten. Starten Sie nach der Installation eine neue Shell, damit die vom Installer vorgenommene Änderung der PATH-Variable wirksam wird. Überprüfen Sie anschließend die Binärdatei:

opencode --version

Wenn Sie einen Paketmanager bevorzugen und Node.js bereits auf dem System installiert ist, installiert der npm-Weg dasselbe Tool systemweit. Dadurch wird die opencode-Binärdatei für jeden User in den PATH aufgenommen:

sudo npm install -g opencode-ai

In beiden Fällen ist die Überprüfung identisch: opencode --version gibt eine Versionsnummer aus. Ein command not found nach der Installation per Skript bedeutet, dass die aktuelle Shell die aktualisierte PATH-Variable noch nicht eingelesen hat. Melden Sie sich ab und als opencode-User wieder an.

Speichern Sie den API-Key in einer privaten Datei

OpenCode benötigt einen Key für den jeweils genutzten Model-Provider. Da dieser Key Kosten verursachen kann, behandeln Sie ihn wie ein Passwort. Erstellen Sie eine Datei mit der Berechtigung 600, auf die nur der Benutzer opencode zugreifen kann. Speichern Sie den Key dort, anstatt ihn direkt in Befehle einzugeben, damit er nicht in der Shell-History gespeichert wird:

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

Tragen Sie die entsprechende Variable Ihres Providers ein, zum Beispiel ANTHROPIC_API_KEY=... oder das Äquivalent für Ihren Anbieter, da OpenCode die Standard-Umgebungsvariablen der Provider erkennt. Laden Sie die Datei in Ihre Shell, bevor Sie den Agent starten:

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

OpenCode bietet eine interaktive Alternative: Der Befehl /connect innerhalb des TUI führt Sie durch die Einrichtung eines Providers und speichert die Anmeldedaten in ~/.local/share/opencode/auth.json im Home-Verzeichnis des Benutzers. Wenn Sie diesen Weg wählen, prüfen Sie mit chmod 600 ~/.local/share/opencode/auth.json, ob die Datei privat ist. Beide Methoden verhindern, dass der Key in der Befehlszeile erscheint; wählen Sie eine Methode und nutzen Sie diese konsistent.

Start OpenCode in tmux

tmux ist der Grund für das VPS-Setup, da eine tmux-Session weiterläuft, wenn die SSH-Verbindung endet. Starten Sie eine Session, navigieren Sie in Ihr Projekt und starten Sie den Agenten:

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

Das TUI sollte sich mit einer Eingabeaufforderung am unteren Rand und Ihrem Projektnamen in der Benutzeroberfläche öffnen. Geben Sie eine Aufgabe in natürlicher Sprache ein; der Agent beginnt dann, Dateien zu lesen und Änderungen vorzuschlagen. Um die Session zu verlassen, trennen Sie sie mit Strg-b gefolgt von d. Der Agent arbeitet weiter, auch wenn Ihr Laptop geschlossen ist. Später können Sie die Session so wieder aufnehmen:

tmux attach -t opencode

Die Session, der Chatverlauf und alle laufenden Aufgaben befinden sich exakt an der Stelle, an der Sie sie verlassen haben. Dies bleibt bei Verbindungsabbrüchen erhalten, jedoch nicht nach einem Neustart des Servers. Starten Sie nach einem Neustart daher eine neue tmux-Session auf die gleiche Weise.

Ein Modell auswählen

OpenCode ist unabhängig vom Provider. Es nutzt das AI SDK und den Models.dev Katalog, um mehr als 75 Provider zu unterstützen. Das Werkzeug funktioniert daher identisch mit Anthropic, OpenAI, Google und Dutzenden anderen, einschließlich lokaler Server. Der schnellste Weg ist der /connect Befehl innerhalb des TUI. Dieser listet die Provider auf und verwaltet die Anmeldedaten. Für eine reproduzierbare Konfiguration legen Sie eine opencode.json im Projektverzeichnis an und setzen das Modell als provider/model-id:

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

Ein lokales Modell funktioniert über dieselbe Datei, da jeder OpenAI-kompatible Server als Provider deklariert werden kann. Wenn Sie ein Modell mit Ollama auf demselben VPS bereitstellen, zeigt die Konfiguration auf dessen lokale API. Der Modellname entspricht dem, was ollama list auf Ihrem System ausgibt:

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

Ein integriertes Feature sollte von Beginn an genutzt werden. OpenCode enthält zwei Agenten, zwischen denen Sie mit der Tab-Taste wechseln können: Build ist der Standard-Agent mit vollem Zugriff, und Plan deaktiviert die Möglichkeit, Änderungen vorzunehmen. Starten Sie eine neue Aufgabe im Plan-Modus, lassen Sie den Code lesen und einen Ansatz vorschlagen, und wechseln Sie erst zu Build, wenn Sie dem Plan zustimmen. Auf einem Server bietet ein erster Durchlauf im Read-Only-Modus eine kostengünstige Absicherung.

Der Blast Radius

Ein Coding-Agent ist nicht passiv. Beschreiben Sie daher genau, was dieses Setup beinhaltet und was nicht. Es beinhaltet Dateischäden: Der Benutzer opencode besitzt nur sein eigenes Home-Verzeichnis und sonst nichts. Bearbeitungen und Löschungen sind auf diese Grenze beschränkt. Es beinhaltet die Offenlegung von Anmeldedaten: Der Key liegt in einer Datei mit der Mode 600 in einem Account. Es beinhaltet nicht die Berechtigungen, die der Account legitim ausführen kann. Wenn das Projektverzeichnis Anmeldedaten für das Production-Deployment enthält, kann der Agent diese verwenden. Halten Sie diese vollständig vom Account des Agenten fern.

Im Gegensatz zu einem Gateway-Agenten wie OpenClaw ist OpenCode ein interaktives Terminal-Programm und kein Daemon. Es öffnet keinen Listening-Port und hat keinen langlaufenden Service. Es ist daher keine systemd-Unit erforderlich und es muss kein Port für den Agenten selbst in der Firewall gesperrt werden. Die Isolation erfolgt über den Benutzeraccount und das Projektverzeichnis. Deshalb ist der erste Abschnitt dieses Leitfadens der wichtigste.

Der Server benötigt dennoch die Standard-Sicherheit: SSH nur mit Key-Authentifizierung und deaktiviertem Root-Login, wie in SSH-Härtung auf einem VPS, eine Default-Deny-Firewall und regelmäßige Updates. Überprüfen Sie zudem die Ergebnisse des Agenten. Lesen Sie die Diffs, bevor Sie sie pushen, genau wie Sie einen Pull Request eines neuen Mitwirkenden lesen würden, da Sie das Ergebnis bereitstellen.

Halten Sie das Tool selbst aktuell. OpenCode veröffentlicht häufig Updates, die Fehlerbehebungen für ein Programm enthalten, das Befehle auf Ihrem Server ausführt. Das Update erfolgt über denselben Weg wie die Installation: Führen Sie das Install-Script als Benutzer opencode erneut aus oder nutzen Sie sudo npm update -g opencode-ai, falls Sie über npm installiert haben. Bestätigen Sie die neue Version mit opencode --version. Ein paar Minuten Wartung sind günstiger als die Fehlersuche bei einem Verhalten, das eine ältere Version bereits behoben hat.

FAQ

Kann OpenCode ein lokales Modell anstelle einer kostenpflichtigen API verwenden?

Ja. OpenCode behandelt jeden OpenAI-kompatiblen Server als Provider. Ein von Ollama auf demselben VPS bereitgestelltes Modell funktioniert daher: Deklarieren Sie den Provider in opencode.json mit dem lokalen baseURL und dem von Ollama gemeldeten Modellnamen. Die Einschränkung ist die Hardware. Ein Modell, das für echte Programmieraufgaben geeignet ist, benötigt viel Arbeitsspeicher. Passen Sie die Servergröße an das Modell an, bevor Sie es herunterladen.

Wie lasse ich OpenCode weiterlaufen, nachdem ich meinen Laptop geschlossen habe?

Führen Sie es in tmux auf dem VPS aus. Starten Sie den Agenten in einer benannten Session mit tmux new -s opencode. Trennen Sie die Session mit Strg-b gefolgt von d. Die Session läuft auf dem Server weiter, nachdem Ihre SSH-Verbindung beendet wurde. Verbinden Sie sich jederzeit mit tmux attach -t opencode wieder; der Chatverlauf und alle laufenden Aufgaben sind weiterhin vorhanden. Ein Server-Reboot beendet die Session. Starten Sie nach einem Reboot eine neue Session.

Ist es sicher, OpenCode Befehle auf meinem VPS ausführen zu lassen?

Es ist kontrollierbar, wenn Sie die Berechtigungen einschränken. Geben Sie OpenCode einen dedizierten, unprivilegierten Benutzer ohne sudo-Rechte. Speichern Sie Projekte in git, damit jede Änderung rückgängig gemacht werden kann. Speichern Sie den API-Key in einer Datei mit dem Modus 600. Verwenden Sie den Plan-Agent für eine erste schreibgeschützte Analyse, bevor Sie den Build-Agenten Änderungen vornehmen lassen. Der Agent kann dann nur Dateien beschädigen, die seinem eigenen Account gehören; der Rest des Servers bleibt geschützt.

Was ist der Unterschied zwischen OpenCode und Claude Code?

OpenCode ist Open Source (MIT) und provider-agnostisch. Es verbindet sich über eine einzige Schnittstelle mit mehr als 75 Modell-Providern, einschließlich lokaler Anbieter. Claude Code ist der terminalbasierte Agent von Anthropic, der für Anthropic-Modelle entwickelt wurde. Wenn Sie ein Werkzeug für viele verschiedene Provider oder einen vollständig selbst gehosteten Stack mit einem lokalen Modell benötigen, ist OpenCode die richtige Wahl. Beide lassen sich gut auf einem VPS innerhalb von tmux mit demselben unprivilegierten Benutzer-Setup betreiben.