OpenCode im Home Lab: Dein Coding-Assistent mit lokalen LLMs ohne API-Kosten

Servus, Home Lab-Enthusiasten und Admins!

Heute tauchen wir mal wieder tief in die Materie ein, und zwar in ein Thema, das mir persönlich in letzter Zeit viel Freude bereitet hat: OpenCode. Wer, wie ich, ständig zwischen Code, Konfigurationen und Skripten jongliert, weiß, wie wertvoll ein guter Coding-Assistent sein kann. Und wer dazu noch auf Open Source und die Kontrolle über die eigenen Daten steht, für den ist OpenCode ein echter Geheimtipp. Stell dir vor, du hast die Power eines Tools wie Claude Code, aber komplett lokal, in deinem eigenen Home Lab, ohne auch nur einen Cent für API-Gebühren auszugeben. Klingt gut, oder? Genau das ist OpenCode.

In meiner Erfahrung ist die Einrichtung solcher Tools oft der erste Stolperstein. Viele Guides sind zu oberflächlich oder setzen zu viel voraus. Deswegen habe ich mir gedacht, ich teile meine Erfahrungen mit dir und zeige dir, wie ich OpenCode bei mir im Proxmox-Cluster, sauber in Docker, zum Laufen gebracht habe. Und das Beste: Wir binden gleich noch LM Studio an, um lokale Large Language Models (LLMs) zu nutzen. Das ist nicht nur kostengünstig, sondern gibt dir auch die volle Kontrolle über deine Daten und Modelle.

Voraussetzungen: Was du mitbringen solltest

Bevor wir loslegen, lass uns kurz checken, ob dein Setup bereit ist. Das ist das A und O, um Frust zu vermeiden:

Ein Linux-Server: Ob eine VM oder ein LXC in Proxmox, ein alter NUC oder ein dedizierter Server – Hauptsache, Linux (ich nutze Debian, Ubuntu geht natürlich auch). Wichtig ist, dass du SSH-Zugriff und Root-Rechte oder sudo-Berechtigungen hast.
Docker und Docker Compose: Das ist unsere Basis für die einfache Bereitstellung von OpenCode. Wenn du Docker noch nicht installiert hast, keine Sorge, das hole ich kurz nach. Für die meisten von uns im Home Lab ist Docker schon Standard, aber sicher ist sicher.
Ausreichend Ressourcen: Speziell für die lokalen LLMs über LM Studio brauchst du ordentlich RAM (mindestens 16 GB, besser 32 GB oder mehr, je nach Modellgröße) und idealerweise eine dedizierte GPU mit VRAM. Ohne GPU wird es auf der CPU sehr langsam, das nur als Warnung. Für OpenCode selbst reichen ein paar CPU-Kerne und 2-4 GB RAM.
LM Studio: Dieses Tool werden wir nutzen, um die lokalen LLMs bereitzustellen. Du kannst es auf einem separaten Rechner laufen lassen, der die GPU-Power hat, oder direkt auf deinem Server, wenn dieser die nötigen Ressourcen mitbringt. Es ist primär ein Desktop-Tool, aber wir nutzen dessen Server-Funktionalität.

Mein Tipp: Wenn du einen dedizierten GPU-Server hast, installiere LM Studio dort. Wenn nicht, plan lieber ein kleineres LLM ein oder sei auf längere Wartezeiten gefasst. Das hat mir persönlich viel Zeit gespart, als ich das erste Mal mit lokalen LLMs experimentiert habe.

OpenCode: Dein lokaler Coding-Assistent

Warum OpenCode? Ganz einfach: Es ist eine Open-Source-Alternative zu kommerziellen Tools wie Claude Code von Anthropic. Das bedeutet, du hast volle Transparenz, kannst das Tool anpassen (wenn du das möchtest) und bist nicht an teure API-Abos gebunden. Für uns im Home Lab ist das ein unschlagbarer Vorteil. Du schreibst Code, OpenCode hilft dir dabei, generiert Snippets, refaktoriert oder erklärt dir komplexe Funktionen. Und das alles, ohne dass deine sensiblen Code-Daten irgendwo in der Cloud landen.

Schritt-für-Schritt-Anleitung: OpenCode in deinem Home Lab einrichten

Docker & Docker Compose vorbereiten

Falls du Docker und Docker Compose noch nicht am Start hast, hier die Quick-and-Dirty-Installation für Debian/Ubuntu. Wenn du das schon erledigt hast, kannst du diesen Abschnitt überspringen.

Zuerst die notwendigen Pakete installieren:

sudo apt update
sudo apt install ca-certificates curl gnupg lsb-release -y

Dann den offiziellen Docker GPG-Key hinzufügen:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Das Docker APT Repository hinzufügen:

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Paketliste aktualisieren und Docker installieren:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Überprüfen, ob Docker läuft:

sudo systemctl status docker

Du solltest 'active (running)' sehen. Füge deinen Benutzer zur Docker-Gruppe hinzu, damit du nicht ständig sudo tippen musst (danach neu anmelden oder newgrp docker):

sudo usermod -aG docker $USER

OpenCode Installation via Docker Compose

Jetzt wird's spannend! Wir erstellen ein Verzeichnis für unsere OpenCode-Installation und legen die docker-compose.yaml an. Das ist der zentrale Punkt für unsere Container-Definition.

mkdir -p ~/opencode
cd ~/opencode

Erstelle die Datei docker-compose.yaml mit deinem bevorzugten Editor (z.B. nano oder vim):

nano docker-compose.yaml

Und füge folgenden Inhalt ein. Dies ist eine vereinfachte Darstellung für ein OpenCode-Setup. Die tatsächliche Implementierung kann variieren, aber diese Struktur ist typisch für solche Anwendungen, die ein Backend und ein Frontend in einem Container bündeln und externe LLMs nutzen:

version: '3.8'

services:
  opencode:
    image: ghcr.io/opencode-project/opencode:latest # Oder eine spezifische Version
    container_name: opencode
    restart: unless-stopped
    ports:
      - "3000:3000" # Standard-Port für OpenCode Web UI
    volumes:
      - ./data:/app/data # Persistente Daten für OpenCode
      - /var/run/docker.sock:/var/run/docker.sock # Optional: Wenn OpenCode Docker-Befehle ausführen soll
    environment:
      # Hier werden später die LLM-Konfigurationen hinterlegt
      # Wichtig: Die genauen Variablennamen können je nach OpenCode-Version variieren.
      # Oftmals sind es OpenAI-kompatible Einstellungen.
      OPENAI_API_KEY: "sk-no-key-required" # Für lokale LLMs oft ein Dummy-Key
      OPENAI_API_BASE: "http://host.docker.internal:1234/v1" # Platzhalter, wird später angepasst
      OPENCODE_PORT: "3000"
    networks:
      - opencode_network

networks:
  opencode_network:
    driver: bridge

Wichtig zu wissen:

image: ghcr.io/opencode-project/opencode:latest ist ein Platzhalter für ein hypothetisches OpenCode-Docker-Image. Überprüfe die offizielle OpenCode-Dokumentation für das korrekte Image und die aktuellste Version.
ports: - "3000:3000": Hier wird der interne Container-Port 3000 auf den externen Host-Port 3000 gemappt. Wenn Port 3000 auf deinem Host schon belegt ist, wähle einen anderen externen Port (z.B. "8000:3000").
volumes: - ./data:/app/data: Das ist essenziell für persistente Daten. Hier speichert OpenCode seine Konfigurationen und Projektdateien. So gehen deine Daten bei einem Container-Update nicht verloren.
OPENAI_API_KEY und OPENAI_API_BASE: Das sind die entscheidenden Variablen für die LLM-Anbindung. Wir nutzen hier die OpenAI-Kompatibilität, die LM Studio bietet. host.docker.internal ist ein spezieller DNS-Name, der innerhalb eines Docker-Containers auf den Docker-Host verweist. Wenn LM Studio auf einem anderen Server läuft, musst du hier dessen IP-Adresse einsetzen. Der Port 1234 ist der Standard-Port von LM Studio für den API-Server.

Speichere die Datei und starte OpenCode:

docker compose up -d

Der -d Parameter sorgt dafür, dass der Container im Hintergrund läuft. Du kannst den Status mit docker compose ps überprüfen.

Nach ein paar Minuten sollte OpenCode unter http://DEINE_SERVER_IP:3000 erreichbar sein. Beim ersten Start kann das Image-Pulling etwas dauern.

LM Studio aufsetzen

Jetzt kümmern wir uns um das Herzstück: die lokalen LLMs. LM Studio ist ein fantastisches Tool, um LLMs herunterzuladen und als lokalen API-Server bereitzustellen. Ich gehe davon aus, dass du LM Studio auf einem Rechner installiert hast, der über ausreichend GPU-Ressourcen verfügt. Falls nicht, kannst du es auch auf deinem Linux-Server installieren, falls dieser eine GPU hat (z.B. über die AppImage-Datei).

LM Studio starten: Öffne LM Studio auf deinem System.
Modell herunterladen: Gehe zum "Discover"-Tab und suche dir ein passendes Modell aus. Für den Anfang empfehle ich ein kleineres Code-Modell, z.B. aus der "CodeLlama"-Familie oder "Phind-CodeLlama". Achte auf die Quantisierung (z.B. Q4_K_M), die den Ressourcenverbrauch bestimmt. Klicke auf "Download".
Lokalen Server starten: Sobald das Modell heruntergeladen ist, wechsle zum "Local Inference Server"-Tab (oft ein Chat-Icon oder ein Server-Icon).
- Wähle dein heruntergeladenes Modell aus der Dropdown-Liste aus.
- Stelle sicher, dass der "Server Host" auf 0.0.0.0 gesetzt ist, damit er von externen Clients (wie unserem OpenCode-Container) erreichbar ist.
- Der Standard-Port ist oft 1234. Behalte diesen im Hinterkopf.
- Klicke auf "Start Server".

Wenn der Server läuft, siehst du in der Konsole von LM Studio, dass er auf Anfragen wartet. Die API-Endpunkt-URL wird dir dort auch angezeigt, typischerweise http://DEINE_LMSTUDIO_IP:1234/v1.

OpenCode mit LM Studio verbinden

Jetzt bringen wir beide Welten zusammen. Öffne die OpenCode-Web-Oberfläche in deinem Browser (http://DEINE_SERVER_IP:3000).

Navigiere zu den Einstellungen (oft ein Zahnrad-Symbol oder "Settings"). Du suchst nach den Einstellungen für die LLM-Verbindung oder API-Konfiguration. Diese sind meist als "OpenAI API Settings" oder ähnlich bezeichnet, da LM Studio die OpenAI-API-Spezifikation emuliert.

API Key: Gib hier sk-no-key-required ein. Da wir einen lokalen Server nutzen, ist kein echter API-Key erforderlich. Das ist der Trick, um die "keine API-Kosten" zu realisieren.
API Base URL / Custom API Endpoint: Hier gibst du die Adresse deines LM Studio Servers ein.
- Wenn LM Studio auf demselben Host wie Docker läuft: http://host.docker.internal:1234/v1
- Wenn LM Studio auf einem anderen Rechner im Netzwerk läuft: http://IP_VON_LMSTUDIO_RECHNER:1234/v1
Model Name: Gib hier den Namen des Modells ein, das du in LM Studio geladen hast. Oft ist es der Dateiname des Modells (z.B. codellama-7b-instruct.Q4_K_M.gguf) oder ein von LM Studio zugewiesener interner Name. Schau in der LM Studio Server-Konsole nach dem genauen Namen, der als "model" in API-Anfragen erwartet wird.

Speichere die Einstellungen. OpenCode sollte nun in der Lage sein, mit deinem lokalen LLM über LM Studio zu kommunizieren. Teste es am besten direkt, indem du eine einfache Anfrage stellst oder ein neues Projekt startest.

Dein erstes Projekt in OpenCode

Nachdem die Verbindung steht, ist es Zeit, OpenCode auf Herz und Nieren zu prüfen. Erstelle ein neues Projekt. Du kannst OpenCode bitten, dir Code-Snippets für eine bestimmte Aufgabe zu generieren, bestehenden Code zu refaktorieren oder dir bei der Fehlersuche zu helfen. Spiele ein wenig damit herum, um ein Gefühl für die Fähigkeiten deines lokalen LLMs zu bekommen. Die Geschwindigkeit hängt stark von deinem Modell und deiner Hardware ab.

Häufige Fehler und Lösungen

Unerwartete Probleme sind im Home Lab Alltag quasi vorprogrammiert. Hier sind ein paar typische Stolperfallen, die mir oder anderen schon begegnet sind:

1. OpenCode ist nicht erreichbar (Port-Konflikt oder Container-Problem)

Problem: Du kannst OpenCode unter http://DEINE_SERVER_IP:3000 nicht erreichen.
Lösung:
- Container-Status prüfen: Zuerst mit docker compose ps nachsehen, ob der opencode-Container überhaupt läuft und nicht im Status "Exited" ist. Wenn er exited ist, schau in die Logs mit docker compose logs opencode, um die Ursache zu finden.
- Port-Konflikt: Ist Port 3000 auf deinem Host vielleicht schon belegt? Das kannst du mit sudo lsof -i :3000 prüfen. Wenn ja, ändere den externen Port in deiner docker-compose.yaml (z.B. "8000:3000"), führe docker compose down und dann docker compose up -d aus.
- Firewall: Hast du eine Firewall auf deinem Host (z.B. UFW)? Stelle sicher, dass Port 3000 (oder den von dir gewählten Port) erlaubt ist: sudo ufw allow 3000/tcp.

2. OpenCode kann keine Verbindung zum LLM herstellen (LM Studio API-Fehler)

Problem: OpenCode meldet Fehler bei der Kommunikation mit dem LLM, oder es kommen keine Antworten.
Lösung:
- LM Studio Server prüfen: Läuft der "Local Inference Server" in LM Studio? Ist das Modell geladen?
- LM Studio Host/Port: Ist der Server Host in LM Studio auf 0.0.0.0 eingestellt? Ist der Port (Standard 1234) korrekt?
- API Base URL in OpenCode: Hast du die korrekte IP-Adresse und den Port in OpenCode eingetragen? Achte auf http://host.docker.internal:1234/v1 (wenn LM Studio auf dem Docker-Host läuft) oder http://IP_VON_LMSTUDIO_RECHNER:1234/v1 (wenn auf einem anderen Rechner). Ein häufiger Fehler ist, localhost zu verwenden, was aus dem Docker-Container heraus nicht funktioniert.
- Modellname: Ist der "Model Name" in OpenCode exakt der, den LM Studio erwartet? Groß-/Kleinschreibung und Dateiendungen können hier eine Rolle spielen.
- Netzwerk: Können sich die beiden Rechner überhaupt erreichen? Ein einfacher ping IP_VON_LMSTUDIO_RECHNER vom Docker-Host aus kann schon helfen.

3. Langsame oder unvollständige Antworten vom LLM (Ressourcenmangel)

Problem: Das LLM antwortet extrem langsam, bricht ab oder generiert nur kurze, unvollständige Antworten.
Lösung:
- RAM/VRAM: Das ist der häufigste Grund. Überprüfe in LM Studio, wie viel RAM/VRAM dein geladenes Modell benötigt. Wenn dein System weniger hat, als das Modell braucht, wird es sehr langsam oder stürzt ab. Probiere ein kleineres oder stärker quantisiertes Modell aus.
- CPU-Auslastung: Wenn du keine GPU nutzt, wird die CPU stark beansprucht. Überwache die CPU-Auslastung deines LM Studio-Rechners.
- LM Studio Einstellungen: In LM Studio kannst du Einstellungen für die Anzahl der Threads und Layer anpassen, die auf die GPU (GPU-Offload) ausgelagert werden sollen. Experimentiere damit, um die optimale Balance für deine Hardware zu finden. Weniger Threads können bei geringem RAM helfen, mehr GPU-Offload nutzt die GPU besser aus.

Fazit & Nächste Schritte

So, da haben wir es! Dein eigenes, lokal gehostetes AI-Coding-Assistenten-Setup mit OpenCode und LM Studio. Du siehst, es ist kein Hexenwerk, wenn man die richtigen Schritte kennt und ein paar typische Fallstricke umgeht. Der größte Vorteil ist ganz klar die volle Kontrolle über deine Daten und die Abwesenheit von API-Kosten. Das ist für uns im Home Lab ein echter Game Changer.

Was sind die nächsten Schritte? Nun, da die Basis steht, kannst du anfangen zu experimentieren:

Andere LLMs ausprobieren: LM Studio bietet eine riesige Auswahl an Modellen. Teste verschiedene Code-Modelle, um das zu finden, das am besten zu deinen Anforderungen passt. Es gibt auch Modelle, die speziell für bestimmte Sprachen oder Frameworks optimiert sind.
OpenCode Features erkunden: Tauche tiefer in die Funktionen von OpenCode ein. Wie gut ist die Code-Vervollständigung? Wie funktioniert die Refaktorierung? Kann es dir bei der Generierung von Tests helfen?
Integration in deine IDE: Viele AI-Coding-Assistenten bieten Integrationen in gängige IDEs wie VS Code. Schau, ob OpenCode (oder ein Community-Plugin) solche Möglichkeiten bietet, um deinen Workflow noch smoother zu gestalten.
Ressourcen optimieren: Wenn du merkst, dass dein LLM zu langsam ist, überlege, ob ein Hardware-Upgrade (mehr RAM, bessere GPU) Sinn macht.

Ich hoffe, dieser Guide hat dir geholfen, OpenCode erfolgreich in deinem Home Lab zu etablieren. Viel Spaß beim Codieren – und vergiss nicht, deine Erfahrungen in der smoth.me Community zu teilen!