OpenCode auf einem VPS installieren und sicher betreiben

Was OpenCode ist und was Sie einrichten

OpenCode ist ein quelloffener KI-Coding-Agent für das Terminal. Sie starten ihn in einem Projektverzeichnis. Er liest Ihren Code, schlägt Änderungen vor, bearbeitet Dateien und führt Befehle aus. Das geschieht vollständig in einer Terminal-Benutzeroberfläche (TUI). OpenCode steht unter der MIT-Lizenz und unterstützt mehr als 75 Modellanbieter. Mit etwa 219,000 GitHub-Sternen im Oktober 2026 ist es der quelloffene Coding-Agent mit den meisten Sternen. Um OpenCode auf einem VPS auszuführen, installieren Sie es unter einem dedizierten unprivilegierten Benutzer. Den API-Schlüssel für das Modell legen Sie in einer privaten Datei ab. Anschließend starten Sie OpenCode in tmux, damit die Sitzung bei einem Verbindungsabbruch bestehen bleibt. Diese Anleitung führt genau diese Schritte in dieser Reihenfolge aus.

Ein Hinweis zur Benennung verhindert Verwechslungen. Das kanonische Repository ist anomalyco/opencode. Es wird vom Anomaly-Team gepflegt, das zuvor als SST bekannt war. Das Projekt befand sich früher unter sst/opencode. Auf GitHub gibt es außerdem ein älteres, nicht verwandtes Repository namens opencode-ai/opencode. Es ist inzwischen archiviert. Prüfen Sie daher, ob Sie die Dokumentation des richtigen Projekts lesen. Die offizielle Website ist opencode.ai.

Warum OpenCode auf einem VPS ausführen

Eine Coding-Agent-Sitzung dauert lange. OpenCode kann viele Minuten damit verbringen, ein Refactoring oder eine Testsuite zu bearbeiten. Wenn der Agent auf Ihrem Laptop läuft, beendet ein geschlossenes Display oder eine unterbrochene WLAN-Verbindung die Sitzung mitten in der Arbeit. In tmux auf einem VPS arbeitet der Agent weiter, nachdem Sie die Verbindung getrennt haben. Später können Sie die Sitzung erneut verbinden und die Ergebnisse prüfen. Dieses Vorgehen entspricht dem Muster Claude Code auf einem VPS mit tmux ausführen. Es ist der größte praktische Vorteil, einen Agenten nicht auf dem Laptop auszuführen.

Der zweite Grund ist der Standort. Ein VPS befindet sich nahe an dem Code, den Sie bereitstellen. Das Repository, die Build-Tools, die Testdatenbank und häufig auch die Staging-Umgebung liegen bereits dort oder in derselben Umgebung. Ein Agent, der Code bearbeitet und Tests ausführt, funktioniert am besten auf der Maschine, auf der diese Tests tatsächlich laufen. Da Sie den Server kontrollieren, können Sie dem Agenten gezielt eine abgeschottete Umgebung bereitstellen. Das wird im nächsten Abschnitt beschrieben.

Wenn Sie noch ein Tool auswählen, vergleicht einen Coding-KI-Agenten auf einem VPS ausführen weitere Lösungen, darunter Aider und Goose.

OpenCode einen eigenen Benutzer zuweisen

Dies ist der Ausgangspunkt: Ein Coding-Agent bearbeitet Dateien und führt Befehle aus. Das ist seine Aufgabe, aber auch das Risiko. OpenCode führt Builds, Tests und beliebige Shell-Befehle aus, die für die Aufgabe erforderlich sind. Das Urteilsvermögen des Modells ist gut, aber nicht perfekt. Das Benutzerkonto, unter dem der Agent läuft, begrenzt den Zugriffsbereich eines fehlerhaften Befehls. Führen Sie ihn daher nicht als root aus und verwenden Sie nicht denselben Benutzer, der den Server verwaltet.

Im Gegensatz zu einem Hintergrunddienst ist OpenCode interaktiv. Der Benutzer benötigt daher 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. Erteilen Sie dem Konto keine sudo-Rechte. Wenn der Agent einen destruktiven Befehl ausführt, kann er nur das zerstören, was diesem Konto gehört. Dies folgt derselben Logik wie Dienste als privilegierter Benutzer ausführen. Arbeiten Sie zudem innerhalb eines git-Repositorys und führen Sie einen Commit durch, bevor Sie dem Agenten eine Aufgabe übergeben. Eine fehlerhafte Änderung an committeten Arbeiten ist dann nur einen git revert oder git restore entfernt, anstatt einen Datenverlust darzustellen. Änderungen, die Sie nie committet haben, sind nicht geschützt.

OpenCode installieren

Das Projekt dokumentiert mehrere Installationsarten. Zwei davon eignen sich für einen Server. Das Installationsskript ist der schnellste Weg. Wenn Sie es als Benutzer opencode ausführen, bleibt alles im Home-Verzeichnis dieses Benutzers:

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

Die übliche curl | bash-Regel gilt auch hier: Laden Sie das Skript auf einem wichtigen Server zuerst herunter, lesen Sie es und führen Sie es erst danach aus. Starten Sie nach der Installation eine neue Shell, damit die vom Installer vorgenommene PATH-Änderung wirksam wird. Prüfen Sie anschließend, ob das Binary antwortet:

opencode --version

Wenn Sie einen Paketmanager bevorzugen und Node.js bereits auf dem Server installiert ist, installiert der npm-Weg dasselbe Tool in das globale npm-Präfix:

sudo npm install -g opencode-ai

Bei einer systemweit installierten Node.js-Version ist dieses Präfix normalerweise /usr/local oder /usr. Deren bin-Verzeichnis steht im PATH jedes Benutzers. Ein Versionsmanager oder ein benutzerdefiniertes Präfix legt das Binary an einem anderen Ort ab. Führen Sie daher zuerst npm prefix -g aus, wenn opencode für den Benutzer opencode gefunden werden muss.

In beiden Fällen ist die Prüfung gleich: opencode --version gibt eine Versionsnummer aus. Ein command not found nach der Installation mit dem Skript bedeutet, dass die aktuelle Shell den aktualisierten PATH noch nicht eingelesen hat. Melden Sie sich daher als Benutzer opencode ab und wieder an.

Beide Befehle installieren die OpenCode-1.x-Reihe. Diese veröffentlicht weiterhin Releases (1.19.3 am 16. Oktober 2026). Diese Anleitung beschreibt diese Reihe. OpenCode 2 ist inzwischen als separate Installation verfügbar: über https://opencode.ai/v2/install oder das npm-Paket @opencode/cli. Es funktioniert anders. Ein gemeinsamer Hintergrundserver pro Benutzerkonto verwaltet Sitzungen, Berechtigungen und Toolausführung. Das Terminal verbindet sich mit diesem Server. Die Migrationsanleitung empfiehlt, eine paketverwaltete 1.x-Installation vor der Installation von Version 2 zu entfernen, weil beide den Befehl opencode verwenden.

Legen Sie den API-Schlüssel in einer privaten Datei ab

OpenCode benötigt einen Schlüssel für den verwendeten Modellanbieter. Mit diesem Schlüssel können Kosten entstehen. Behandeln Sie ihn daher wie ein Passwort. Erstellen Sie eine Datei, die nur der Benutzer opencode lesen kann, und setzen Sie den Modus auf 600. Speichern Sie den Schlüssel dort, anstatt ihn in Befehle einzugeben, wo er in Ihrer Shell-History landen würde:

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

Tragen Sie die Variable Ihres Anbieters ein, zum Beispiel ANTHROPIC_API_KEY=... oder das entsprechende Gegenstück Ihres Anbieters. OpenCode verwendet die standardmäßigen Umgebungsvariablen der Anbieter. Laden Sie die Datei in Ihre Shell, bevor Sie den Agent starten:

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

OpenCode bietet außerdem eine interaktive Alternative: Mit dem Befehl /connect innerhalb der TUI fügen Sie einen Anbieter schrittweise hinzu. Die Zugangsdaten werden unter ~/.local/share/opencode/auth.json im Home-Verzeichnis des Benutzers gespeichert. Wenn Sie diesen Weg verwenden, prüfen Sie mit chmod 600 ~/.local/share/opencode/auth.json, ob die Datei privat ist. Beide Wege halten den Schlüssel aus Ihren Befehlszeilen heraus. Wählen Sie einen Weg und bleiben Sie dabei.

OpenCode in tmux starten

tmux macht das VPS-Setup besonders nützlich, weil eine tmux-Sitzung weiterläuft, wenn Ihre SSH-Verbindung endet. Starten Sie eine Sitzung, wechseln Sie in Ihr Projektverzeichnis und starten Sie den Agenten:

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

Die TUI sollte sich mit einer Eingabeaufforderung am unteren Rand und dem Namen Ihres Projekts in der Oberfläche öffnen. Beschreiben Sie die Aufgabe in normaler Sprache. Der Agent beginnt dann, Dateien zu lesen und Änderungen vorzuschlagen. Wenn Sie die Sitzung verlassen möchten, lösen Sie die Verbindung mit Ctrl-b und anschließend d. Der Agent arbeitet weiter, auch wenn Ihr Laptop geschlossen ist. Mit folgendem Befehl stellen Sie die Verbindung später wieder her:

tmux attach -t opencode

Die Sitzung, die Unterhaltung und alle laufenden Aufgaben befinden sich genau an der Stelle, an der Sie sie verlassen haben. Das übersteht Verbindungsabbrüche, aber keinen Serverneustart. Nach einem Neustart müssen Sie daher auf dieselbe Weise eine neue tmux-Sitzung starten. Sie können auch ein zweites tmux-Fenster öffnen und neben dem ersten einen weiteren Agenten ausführen. OpenCode-Sitzungen bleiben jedoch voneinander unabhängig, während Claude-Code-Sitzungen auf demselben Server sich gegenseitig Nachrichten senden können. Das ist eine andere Möglichkeit, eine Aufgabe in zwei Teile aufzuteilen.

Mit einem Modell verbinden

OpenCode ist unabhängig vom Anbieter. Es verwendet das AI SDK und den Models.dev-Katalog, um mehr als 75 Anbieter zu unterstützen. Dasselbe Tool funktioniert daher mit Anthropic, OpenAI, Google und Dutzenden weiteren Anbietern, einschließlich lokaler Server. Der schnellste Weg führt über den Befehl /connect innerhalb der TUI. Dieser listet Anbieter auf und verwaltet die Zugangsdaten. Für eine Konfiguration, die Sie versionieren und reproduzieren können, legen Sie eine opencode.json im Projektstammverzeichnis an und setzen das Modell als provider/model-id:

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

Wählen Sie ein Modell, das Ihr Anbieter weiterhin bereitstellt. Anthropic hat claude-sonnet-4-20250514 am 15. Juni 2026 eingestellt. Konfigurationen, die dieses Modell weiterhin angeben, schlagen daher fehl.

Ein lokales Modell funktioniert über dieselbe Datei, weil jeder OpenAI-kompatible Server als Anbieter definiert werden kann. Wenn Sie ein Modell mit Ollama auf demselben VPS bereitstellen, verweist die Konfiguration auf dessen lokale API. Der Modellname entspricht dem Wert, den 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" } }
    }
  }
}

Eine integrierte Funktion sollten Sie von Anfang an verwenden. OpenCode enthält zwei Agents, zwischen denen Sie mit der Tab-Taste wechseln: Build ist der Standard-Agent mit vollständigem Zugriff. Plan ist ein eingeschränkter Agent für Analysen. Er verweigert Dateibearbeitungen außerhalb seines eigenen Planverzeichnisses, ohne vorher nachzufragen. Plan ist jedoch nicht strikt schreibgeschützt. Er kann weiterhin Shell-Befehle ausführen, und ein Shell-Befehl kann Dateien ändern. Starten Sie eine neue Aufgabe in Plan. Lassen Sie den Agent den Code lesen und einen Ansatz vorschlagen. Wechseln Sie erst zu Build, wenn Sie dem Plan zustimmen. Wenn dieser erste Durchlauf tatsächlich schreibgeschützt sein soll, verweigern Sie Plan in opencode.json Dateiänderungen und Shell-Befehle. OpenCode behandelt deny als Blockierung der Aktion. ask fordert Sie dagegen nur zur Genehmigung auf:

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

Auf einem Server ist ein erster Durchlauf ohne Änderungsmöglichkeit eine einfache Sicherheitsmaßnahme. Claude Code beschreibt dieselbe Entscheidung als Berechtigungsmodi statt als Agents. Sein Wechsel in den automatischen Modus als Standard ist lesenswert, wenn Sie beide Tools verwenden. Der Modus, in dem eine Sitzung startet, bestimmt, wie viel ein nicht überwachter Agent ändern kann.

Der Schadensradius, ehrlich gesagt

Ein Coding-Agent ist nicht passiv. Beschreiben Sie daher klar, was dieses Setup enthält und was nicht. Es enthält das Risiko von Dateischäden: Der Benutzer opencode besitzt nur sein eigenes Home-Verzeichnis und nichts weiter. Änderungen und Löschungen enden also an dieser Grenze. Es enthält das Risiko der Offenlegung von Zugangsdaten: Der Schlüssel befindet sich in einer einzigen Datei mit dem Modus 600 in einem einzigen Account. Es enthält nicht die Einschränkung dessen, was der Account rechtmäßig tun kann. Wenn das Projektverzeichnis also Zugangsdaten für Produktions-Deployments enthält, kann der Agent diese verwenden. Halten Sie solche Daten vollständig aus dem Account des Agenten fern.

Im Gegensatz zu einem Gateway-Agenten wie OpenClaw ist OpenCode 1.x ein interaktives Terminalprogramm, kein Daemon. Standardmäßig öffnet es keinen Port (nur die Flags --port, --hostname oder --mdns veranlassen die TUI dazu, auf einem Port zu lauschen) und es gibt keinen dauerhaft laufenden Dienst. Daher gibt es keine systemd-Unit zu schreiben und keinen Port für den Agenten selbst in der Firewall freizugeben. OpenCode 2 ändert dies mit seinem gemeinsam genutzten Hintergrundserver. Überprüfen Sie diesen Punkt daher erneut, bevor Sie migrieren. Die Eingrenzung erfolgt über den Benutzeraccount und das Projektverzeichnis. Deshalb ist der erste Abschnitt dieser Anleitung der wichtigste.

Die Umgebung erfordert dennoch die übliche Sorgfalt, da ein Coding-VPS weiterhin ein öffentlicher Server ist: SSH nur mit Schlüsseln und deaktiviertem root-Login, wie unter SSH-Härtung auf einem VPS beschrieben, eine Firewall mit Default-Deny-Richtlinie und regelmäßige Updates. Überprüfen Sie zudem, was der Agent produziert. Lesen Sie seine Diffs, bevor Sie diese pushen, genau wie Sie einen Pull Request eines neuen Mitwirkenden lesen würden, da Sie die Person sind, die das Ergebnis bereitstellt.

Halten Sie das Tool schließlich aktuell. OpenCode veröffentlicht häufig Updates, und diese enthalten Korrekturen, die für ein Programm, das Befehle auf Ihrem Server ausführt, wichtig sind. Die Aktualisierung erfolgt auf demselben Weg, über den Sie die Installation durchgeführt haben: Führen Sie das Installationsskript erneut als Benutzer opencode aus oder führen Sie sudo npm update -g opencode-ai aus, falls Sie über npm installiert haben. Bestätigen Sie anschließend die neue Version mit opencode --version. Beide Wege halten Sie auf der 1.x-Linie; der Wechsel zu OpenCode 2 ist eine separate Migration. Eine Minute Wartung hin und wieder ist günstiger als das Debuggen von Verhalten, das in einem Monate alten Build bereits behoben wurde.

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 ebenfalls: Geben Sie den Provider in opencode.json mit der lokalen baseURL und dem von Ollama gemeldeten Modellnamen an. Der Haken ist die Hardware, da ein für echte Programmieraufgaben geeignetes Modell erheblichen Arbeitsspeicher benötigt. Dimensionieren Sie den Server daher für das Modell, bevor Sie es herunterladen.

Wie halte ich OpenCode am Laufen, nachdem ich meinen Laptop geschlossen habe?

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

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

Es ist handhabbar, wenn Sie es isolieren. Geben Sie OpenCode einen dedizierten, unprivilegierten Benutzer ohne sudo-Rechte, verwalten Sie Projekte in git und führen Sie vor jeder Aufgabe einen Commit durch, damit fehlerhafte Änderungen rückgängig gemacht werden können. Speichern Sie den API-Key in einer Datei mit dem Modus 600 und nutzen Sie den Plan-Agenten für einen ersten Durchlauf, bevor Sie den Build-Agenten Änderungen vornehmen lassen. Setzen Sie für den Plan-Agenten die Bearbeitungen und Shell-Befehle auf deny, falls dieser Durchlauf strikt schreibgeschützt sein soll. Der Agent kann dann nur beschädigen, was seinem eigenen Benutzerkonto gehört; der Rest des Servers bleibt geschützt.

Was ist der Unterschied zwischen OpenCode und Claude Code?

OpenCode ist Open Source (MIT) und providerunabhängig; es verbindet sich über eine Schnittstelle mit mehr als 75 Modell-Providern, einschließlich lokaler Instanzen. Claude Code ist der eigene Terminal-Agent von Anthropic, der auf Anthropic-Modelle ausgelegt ist. Wenn Sie ein Werkzeug für viele Provider oder einen vollständig selbst gehosteten Stack mit einem lokalen Modell suchen, ist OpenCode die richtige Wahl. Beide laufen gut auf einem VPS innerhalb von tmux mit derselben Einrichtung für unprivilegierte Benutzer.