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 innerhalb eines Projektverzeichnisses. Dort liest er Ihren Code, schlägt Änderungen vor, bearbeitet Dateien und führt Befehle aus. Die Bedienung erfolgt über eine textbasierte Terminal-Oberfläche (TUI). OpenCode steht unter der MIT-Lizenz und kann mit mehr als 75 Modellanbietern verbunden werden. Mit etwa 165,000 GitHub-Sternen Mitte 2026 ist OpenCode der quelloffene Coding-Agent mit den meisten Sternen. Um OpenCode auf einem VPS auszuführen, installieren Sie es unter einem dedizierten Benutzer ohne privilegierte Rechte. Den API-Schlüssel für das Modell speichern Sie in einer privaten Datei. Anschließend starten Sie OpenCode innerhalb von tmux, damit die Sitzung bei einem Verbindungsabbruch erhalten bleibt. Diese Anleitung führt Sie genau in dieser Reihenfolge durch die Einrichtung.

Ein Hinweis zur Namensgebung 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 existiert außerdem ein älteres, unabhängiges Repository namens opencode-ai/opencode. 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 erhält einen eigenen Benutzer

Der ehrliche Ausgangspunkt ist: Ein Coding-Agent bearbeitet Dateien und führt Befehle aus. Das ist seine Aufgabe und zugleich das Risiko. 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 perfekt. Das Benutzerkonto, unter dem der Agent läuft, begrenzt, worauf ein schädlicher Befehl zugreifen kann. Führen Sie OpenCode daher nicht als root und nicht als denselben Benutzer aus, der den Server administriert.

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

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

Legen Sie die Projekte, an denen OpenCode arbeiten soll, unter /home/opencode ab und klonen Sie sie mit diesem Benutzer. Vergeben Sie für dieses Konto keine sudo-Rechte. Wenn der Agent einen destruktiven Befehl ausführt, kann er nur die Daten zerstören, die diesem Konto gehören. Das entspricht derselben Überlegung wie beim Ausführen von Diensten als unprivilegierter Benutzer. Arbeiten Sie außerdem innerhalb eines git-Repositorys. Ein Repository macht aus einer fehlerhaften Änderung ein git revert statt eines Verlusts.

OpenCode installieren

Das Projekt dokumentiert zwei Installationsmethoden. 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 Server, der Ihnen wichtig ist, zuerst herunter. Lesen Sie es. 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 die Binärdatei antwortet:

opencode --version

Wenn Sie einen Paketmanager bevorzugen und Node.js bereits auf dem System installiert ist, installiert der npm-Weg dasselbe Tool systemweit. Dadurch befindet sich die opencode-Binärdatei für alle Benutzer im PATH:

sudo npm install -g opencode-ai

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

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.

Auf ein Modell verweisen

OpenCode ist unabhängig vom Provider. Es verwendet das AI SDK und den Models.dev-Katalog, um mehr als 75 Provider zu unterstützen. Dadurch funktioniert dasselbe Tool mit Anthropic, OpenAI, Google und Dutzenden weiteren Anbietern, einschließlich lokaler Server. Der schnellste Weg ist der Befehl /connect in der TUI. Er listet Provider auf und übernimmt die Zugangsdaten. Für eine Konfiguration, die Sie in das Repository aufnehmen 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-4-20250514"
}

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

{
  "$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 Arbeitsweise sollten Sie von Anfang an übernehmen. OpenCode enthält zwei Agents, zwischen denen Sie mit der Tab-Taste wechseln: Build ist der Standard-Agent mit vollständigem Zugriff. Plan deaktiviert dagegen die Möglichkeit, Änderungen vorzunehmen. 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. Auf einem Server ist ein schreibgeschützter erster Durchlauf eine einfache zusätzliche Absicherung. Claude Code behandelt dieselbe Entscheidung als Berechtigungsmodi statt als Agents. Die Umstellung auf den Auto-Modus als Standard ist lesenswert, wenn Sie beide Tools verwenden. Der Modus, mit dem eine Sitzung startet, bestimmt, wie viel ein nicht überwachter Agent ändern kann.

Die Reichweite eines Fehlers, ehrlich betrachtet

Ein Coding-Agent arbeitet nicht passiv. Beschreiben Sie deshalb klar, was diese Einrichtung begrenzt und was nicht. Sie begrenzt Dateischäden: Der Benutzer opencode besitzt sein eigenes Home-Verzeichnis und sonst nichts. Änderungen und Löschungen enden daher an dieser Grenze. Sie begrenzt jedoch keinen Zugriff auf Anmeldedaten, den das Konto rechtmäßig besitzt. Wenn das Projektverzeichnis Zugangsdaten für Produktions-Deployments enthält, kann der Agent sie verwenden. Bewahren Sie solche Zugangsdaten vollständig außerhalb des Kontos des Agenten auf.

Im Gegensatz zu einem Gateway-Agenten wie OpenClaw ist OpenCode ein interaktives Terminalprogramm und kein Daemon. Es öffnet keinen Listening-Port und stellt keinen dauerhaft laufenden Dienst bereit. Daher müssen Sie weder eine systemd-Unit für den Agenten erstellen noch einen Port für ihn in der Firewall freigeben. Die Begrenzung erfolgt durch das Benutzerkonto und das Projektverzeichnis. Deshalb ist der erste Abschnitt dieses Leitfadens besonders wichtig.

Auch der Server selbst benötigt die übliche Absicherung, denn ein Coding-VPS ist weiterhin ein öffentlicher Server: SSH nur mit Schlüsseln und deaktivierter root-Anmeldung, wie unter SSH-Härtung auf einem VPS beschrieben, eine Firewall mit standardmäßig verweigertem Zugriff und regelmäßige Updates. Prüfen Sie außerdem die vom Agenten erzeugten Änderungen. Lesen Sie die Diffs, bevor Sie sie pushen, genauso wie einen Pull Request eines neuen Mitwirkenden. Sie sind für das Deployment des Ergebnisses verantwortlich.

Halten Sie schließlich auch das Tool selbst aktuell. OpenCode veröffentlicht häufig neue Versionen. Diese Updates enthalten wichtige Fehlerbehebungen für ein Programm, das Befehle auf Ihrem Server ausführt. Verwenden Sie zum Aktualisieren denselben Weg wie bei der Installation: Führen Sie das Installationsskript erneut als Benutzer opencode aus oder verwenden Sie sudo npm update -g opencode-ai, wenn Sie die Installation über npm vorgenommen haben. Bestätigen Sie anschließend mit opencode --version die neue Version. Eine gelegentliche Minute für Wartung ist günstiger, als Verhalten einer mehrere Monate alten Version zu debuggen, das in der Zwischenzeit bereits behoben wurde.

FAQ

Kann OpenCode statt einer kostenpflichtigen API ein lokales Modell verwenden?

Ja. OpenCode behandelt jeden OpenAI-kompatiblen Server als Provider. Daher funktioniert auch ein Modell, das Ollama auf demselben VPS bereitstellt: 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 ausreichend gut ist, benötigt viel Arbeitsspeicher. Dimensionieren Sie den Server daher für das Modell, bevor Sie es herunterladen.

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

Führen Sie OpenCode auf dem VPS innerhalb von tmux aus. Starten Sie den Agenten mit tmux new -s opencode in einer benannten Sitzung. Trennen Sie die Sitzung mit Ctrl-b und anschließend d. Die Sitzung läuft dann auf dem Server weiter, nachdem Ihre SSH-Verbindung beendet wurde. Mit tmux attach -t opencode können Sie jederzeit erneut eine Verbindung herstellen. Die Unterhaltung und alle laufenden Aufgaben sind dann weiterhin vorhanden. Ein Neustart des Servers beendet die Sitzung. Starten Sie danach eine neue Sitzung.

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

Das lässt sich kontrollieren, wenn Sie OpenCode einschränken. Verwenden Sie für OpenCode einen eigenen Benutzer ohne privilegierte Rechte und ohne sudo. Legen Sie die Projekte in git ab, damit jede Änderung rückgängig gemacht werden kann. Speichern Sie den API-Schlüssel in einer Datei mit dem Modus 600. Verwenden Sie den Plan-Agenten zunächst für eine schreibgeschützte Prüfung, bevor Sie dem Build-Agenten Änderungen erlauben. Der Agent kann dann nur die Dateien und Ressourcen beschädigen, die dem eigenen Benutzer gehören. Der restliche Server bleibt außerhalb seiner Reichweite.

Was ist der Unterschied zwischen OpenCode und Claude Code?

OpenCode ist Open Source (MIT) und unabhängig vom Provider. Über eine einheitliche Schnittstelle stellt es Verbindungen zu mehr als 75 Modell-Providern her, darunter auch lokalen Providern. Claude Code ist der eigene Terminal-Agent von Anthropic und auf die Modelle von Anthropic ausgerichtet. Wenn Sie ein Werkzeug für viele Provider oder einen vollständig selbst gehosteten Stack mit einem lokalen Modell benötigen, ist OpenCode die passende Lösung. Beide Anwendungen laufen auf einem VPS innerhalb von tmux gut und können mit derselben Einrichtung eines unprivilegierten Benutzers betrieben werden.