KoboldCpp für lokale LLM-Inferenz auf einem VPS betreiben

Kurz gesagt. KoboldCpp ist ein kostenloses Ein-Datei-Programm, das GGUF-Sprachmodelle auf deinem eigenen Server ausführt und über eine Weboberfläche und eine API bereitstellt. Auf einem VPS lädst du eine Binärdatei und eine Modelldatei herunter und startest sie in tmux. Ein reiner CPU-Server mit 11 GiB RAM führt ein Testmodell mit 0,5 Milliarden Parametern aus. Die geschätzte Obergrenze liegt bei 7 bis 8 Milliarden Parametern.

Wofür wird KoboldCpp verwendet?

KoboldCpp führt Open-Weight-Sprachmodelle auf Hardware aus, die du selbst kontrollierst. Meist dient es zum Schreiben von Geschichten, für Rollenspiele und Chats sowie als Backend für andere KI-Tools. Es baut auf llama.cpp auf, der C++-Inferenz-Engine hinter vielen lokalen LLM-Tools, und ist vom ursprünglichen KoboldAI-Projekt inspiriert. Ein Entwickler namens Concedo (auf GitHub: LostRuins) pflegt es unter der AGPLv3-Lizenz.

Das Programm besteht aus einer einzigen, eigenständigen Datei und lädt GGUF-Modelldateien. Mitgeliefert wird KoboldAI Lite, eine Browseroberfläche mit Story-, Chat-, Instruct- und Adventure-Modus. Dazu kommt eine OpenAI-kompatible API, sodass Tools wie SillyTavern oder deine eigenen Skripte KoboldCpp als Backend nutzen können. Funktionen für Bilder, Sprache und Musik gibt es ebenfalls. Sie sind optional und kommen in dieser Anleitung nicht vor.

Auf einem VPS bekommst du einen dauerhaft erreichbaren, privaten Endpunkt. KoboldCpp lässt das Modell auf deinem eigenen Server laufen. Der AI-Horde-Worker, der deine Rechenleistung mit anderen Nutzern teilt, ist optional und muss ausdrücklich aktiviert werden. Ein kleines Team kann sich eine Instanz teilen, weil KoboldCpp eingehende Anfragen in eine Warteschlange stellt.

Was brauchst du vorab?

Du brauchst einen Linux-VPS, einen SSH-Client auf deinem Rechner und etwa 1 GB freien Speicherplatz für die Binärdatei und das Testmodell.

• Getestete Umgebung: Ubuntu 24.04 mit 6 vCPUs und 11 GiB RAM, KoboldCpp 1.122.1.
• Zugang: ein Root-Login. Wenn du einen normalen Benutzer verwendest, setze in Schritt 3 sudo vor den apt-Befehl.
• SSH-Client: Die Schritte mit dem Hinweis „auf deinem PC“ nutzen PowerShell unter Windows. Terminals unter macOS und Linux funktionieren genauso.

Der RAM entscheidet, welche Modelle passen, denn die Modelldatei muss samt Platz für den Kontext in den Arbeitsspeicher passen. Diese Anleitung beginnt mit einem Modell mit 0,5 Milliarden Parametern als schnellem Smoke-Test. Als Schätzung gilt: Ein Modell mit 7 bis 8 Milliarden Parametern bei 4-Bit-Quantisierung ist auf 11 GiB die realistische Grenze. Die Textgenerierung auf der CPU ist langsam. Betrachte dieses Setup deshalb als Möglichkeit, den Stack auszuprobieren, nicht als Chat-Dienst für viele Nutzer.

So richtest du KoboldCpp auf einem VPS ein

Du richtest KoboldCpp in acht Schritten ein: verbinden, Ressourcen prüfen, Tools installieren, Binärdatei und Modell herunterladen, in tmux starten, prüfen und die Weboberfläche über einen SSH-Tunnel öffnen.

Schritt 1: Verbinden (auf deinem PC). Führe ssh root@YOUR_SERVER_IP aus und tippe beim Fingerprint-Prompt yes. Wenn SSH warnt, dass sich die Remote-Host-Identifikation geändert hat, passiert das nach einer Neuinstallation des VPS. Entferne dann zuerst den alten Schlüssel und verbinde dich erneut:

ssh-keygen -R YOUR_SERVER_IP
ssh root@YOUR_SERVER_IP

Schritt 2: Ressourcen prüfen (auf dem VPS). Der Befehl zeigt Arbeitsspeicher, Festplattenplatz und CPU-Anzahl:

free -h && df -h / && nproc

Schritt 3: Tools installieren und Ordner anlegen.

apt update && apt install -y curl tmux
mkdir -p ~/koboldcpp/models && cd ~/koboldcpp

Schritt 4: KoboldCpp herunterladen. Die Release-Notes zu KoboldCpp 1.122.1 listen drei Linux-Builds. Diese Anleitung nutzt den CPU-Build mit etwa 130 MB.

curl -fLo koboldcpp https://github.com/LostRuins/koboldcpp/releases/latest/download/koboldcpp-linux-x64-nocuda
chmod +x koboldcpp

Neuere Releases können Flags ändern. Um die getestete Version festzuhalten, ersetze latest/download in der Adresse durch download/v1.122.1.

Schritt 5: Testmodell herunterladen. Das Modell ist Qwen2.5-0.5B-Instruct in der Quantisierung Q4_K_M. Auf Hugging Face enthält die Seitenadresse einer Datei /blob/, und das ist eine Vorschauseite. Ersetze /blob/ durch /resolve/, um den direkten Download-Link zu erhalten:

curl -fLo models/test.gguf "https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf"
ls -lh models

Die Auflistung sollte test.gguf mit etwa 469M zeigen. Eine Datei mit nur wenigen Kilobyte bedeutet, dass du eine /blob/-Seite heruntergeladen hast.

Schritt 6: KoboldCpp in tmux starten. Die tmux-Sitzung hält KoboldCpp am Laufen, auch wenn du SSH schließt.

tmux new -s kobold
./koboldcpp --model ./models/test.gguf --usecpu --host 127.0.0.1 --port 5001 --contextsize 2048

Die Flags erfüllen fünf Aufgaben: --model nennt die GGUF-Datei, --usecpu hält die Berechnung auf dem Prozessor, --host legt die Listening-Adresse fest, --port den Port, und --contextsize 2048 begrenzt den Speicher für den Kontext, der standardmäßig bei 16.384 liegt. Setze --host immer. In Version 1.122.1 nahm ein Start ohne dieses Flag auch Verbindungen auf der Netzwerkadresse des Servers an, obwohl das Log localhost ausgibt. Wenn das Modell bereit ist, endet das Log so:

Load Text Model OK: True
Please connect to custom endpoint at http://127.0.0.1:5001

Schritt 7: Sitzung trennen und prüfen. Drücke Ctrl+B, lass beide Tasten los und drücke dann D. KoboldCpp läuft im Hintergrund weiter. Prüfe anschließend, ob es antwortet:

curl http://localhost:5001/api/extra/version

Die Antwort beginnt mit {"result": "KoboldCpp", "version": "1.122.1" und enthält danach weitere Felder.

Schritt 8: Weboberfläche öffnen (auf deinem PC). Öffne in einem neuen PowerShell-Fenster einen SSH-Tunnel. Er leitet Port 5001 auf deinem Rechner an den privaten Port auf dem Server weiter:

ssh -L 5001:localhost:5001 root@YOUR_SERVER_IP

Lass dieses Fenster geöffnet und rufe dann http://localhost:5001 im Browser auf.

Wie nutzt und beendest du den laufenden Server?

Du erreichst den Server über drei Adressen auf deinem Tunnel und verwaltest ihn mit tmux. http://localhost:5001/ öffnet KoboldAI Lite, http://localhost:5001/lcpp/ die mitgelieferte llama.cpp-Oberfläche und http://localhost:5001/api die API-Dokumentation. Um die Generierung zu testen, wähle unter Basic Settings im Dropdown Format den Eintrag Instruct und sende einen kurzen Prompt. Das Log nennt außerdem eine OpenAI-kompatible API unter /v1/, die diese Anleitung nicht testet.

Braucht KoboldCpp eine CPU oder eine GPU?

KoboldCpp läuft allein auf der CPU, aber eine GPU beschleunigt die Generierung, sobald die Modelle groß werden. Auf der CPU liegen die Modellgewichte im Arbeitsspeicher, und der Prozessor liest sie für jedes Token. Beim GPU-Offloading wandern Schichten in den VRAM der Karte, wo Parallelhardware sie deutlich schneller verarbeitet.

Drei Flags steuern das. --usecpu hält alles auf dem Prozessor, --usecuda oder --usevulkan aktiviert die GPU-Beschleunigung, und --gpulayers legt fest, wie viele Schichten auf die Karte wandern. Laut --help in Version 1.122.1 ist der Standardwert für --gpulayers -1, dann wählt KoboldCpp automatisch. Starte auf der CPU, wenn dein Modell klein und quantisiert ist und du mit langsamen Antworten leben kannst. Wechsle zu einer GPU, wenn du Antworten willst, die sich interaktiv anfühlen, oder ein größeres Modell brauchst.

Dimensioniere den Server nach dem geplanten Modell, denn Modelldatei und Kontext müssen in den Speicher passen. Das KoboldCpp-Wiki nennt eine Faustregel für 4-Bit-quantisierte Modelle bei 2.048 Token Kontext: mindestens 8 GB RAM für ein Modell mit 7 Milliarden Parametern, 16 GB für 13 Milliarden, 32 GB für 30 Milliarden und 64 GB für 65 Milliarden. Der Standardkontext in Version 1.122.1 beträgt 16.384, also lass Spielraum oder senke --contextsize. Für ein reines CPU-Setup eignen sich Cloud VPS gut. Wähle nach RAM. Nimm Performance VPS, wenn du NVMe-Speicher für schnelleres Laden der Modelle willst, oder Max Performance VPS für dedizierte Ressourcen und eine gleichmäßigere Generierungsgeschwindigkeit. Mehr Kerne helfen ebenfalls, weil das Wiki empfiehlt, die Thread-Anzahl nahe an der Zahl der physischen Kerne zu setzen.

Für größere Modelle oder schnellere Antworten kombiniert der GPU VPS eine dedizierte NVIDIA RTX PRO 6000 (96 GB VRAM, CUDA-kompatibel) mit 18 vCPUs und 96 GB RAM. Die Gewichte liegen so im VRAM statt im Arbeitsspeicher. Als Schätzung braucht ein Modell mit 70 Milliarden Parametern bei 4-Bit-Quantisierung etwa 40 GB für die Gewichte plus Speicher für den Kontext, passt also auf diese eine Karte.

Was tun, wenn etwas schiefgeht?

Die meisten Probleme betreffen SSH, Modell-Downloads oder Speicher. Die Tabelle deckt die Fälle ab, die beim Testen aufgetreten sind.

Wie geht es weiter?

Probiere ein größeres Modell aus, bis zur Grenze deines RAM, und vergleiche seine Antworten mit dem Testmodell. Die Geschwindigkeit sinkt mit wachsender Modellgröße. Miss also, wie lange eine Antwort dauert, bevor du dich auf ein Modell festlegst. Wenn du den Port öffnest, statt einen Tunnel zu nutzen, setze --password und beschränke den Port in der Contabo Firewall auf deine eigene IP-Adresse. KoboldCpp als systemd-Dienst zu betreiben ist ebenfalls möglich, wird in dieser Anleitung aber nicht behandelt.

FAQ: KoboldCpp selbst hosten