OpenHands auf Proxmox betreiben

Was dieser Artikel über OpenHands auf Proxmox behandelt

• Was OpenHands ist und wofür es sich eignet.
• Wie man OpenHands auf Proxmox VE in einem LXC oder einer VM installiert.
• Welche Ressourcen benötigt werden.
• Wie man OpenHands mit lokalen oder gehosteten LLMs verbindet.
• Wichtige Sicherheitsaspekte und typische Stolpersteine.

Einleitung: OpenHands auf Proxmox

OpenHands ist ein Open-Source-Framework für KI-gestützte Softwareentwicklung. Es ermöglicht Agenten, die Dateien lesen, Code schreiben, Befehle ausführen und mit Versionskontrolle arbeiten können. Wer OpenHands auf Proxmox betreibt, profitiert von Isolation, Snapshots und einfacher Ressourcenverwaltung. Ein eigener LXC oder eine VM trennt OpenHands vom Rest des Netzwerks.

OpenHands kann mit lokalen Modellen über Ollama oder mit gehosteten APIs wie OpenAI, Anthropic und vielen weiteren verbunden werden. Da die Agenten wirklich Code ausführen, ist eine isolierte Umgebung besonders wichtig.

Was ist OpenHands?

OpenHands ist ein Coding-Agenten-Framework. Es bietet:

• Code-Bearbeitung: Agenten können Dateien lesen und verändern.
• Shell-Ausführung: Befehle in einer Sandbox ausführen.
• Versionskontrolle: Arbeit mit Git-Repositories.
• LLM-Anbindung: Verbindung zu vielen Providern über LiteLLM.
• Web-Interface: Browserbasierte Oberfläche für die Interaktion.
• Erweiterbarkeit: Unterstützung für MCP-Server und Skills.

OpenHands richtet sich an Entwickler, die wiederkehrende Coding-Aufgaben automatisieren wollen, zum Beispiel Refactoring, Bugfixes oder Dokumentation.

LXC oder VM?

LXC

• Vorteile: Wenig Overhead, schneller Start, einfache Verwaltung.
• Nachteile: Teilt den Kernel mit dem Host, Docker im LXC braucht Rechte.
• Empfohlen für: Eigener LXC mit Docker-Socket-Zugriff und begrenztem Dateisystemzugriff.

VM

• Vorteile: Eigener Kernel, bessere Isolation, einfacherer Docker-Betrieb.
• Nachteile: Mehr Overhead.
• Empfohlen für: Höhere Sicherheit und GPU-Passthrough.

Für den Anfang reicht ein LXC. Wer maximal isolieren will oder eine GPU durchreichen möchte, nimmt eine VM.

Hardware-Anforderungen

• CPU: 4 vCPUs minimum, 8 vCPUs empfohlen.
• RAM: 8 GB minimum, 16 GB empfohlen, 32 GB für grössere Modelle.
• Disk: 40 GB minimum, 80 GB empfohlen, da Docker-Images und Modelle Platz brauchen.
• GPU: Optional, beschleunigt die LLM-Inferenz.
• Netzwerk: Internetzugriff für Docker-Images und API-Provider.

Voraussetzungen

• Proxmox VE mit LXC- oder VM-Support.
• Ubuntu 24.04 LTS als Gast.
• Docker und Docker Compose installiert.
• Ein LLM-Provider oder lokale Ollama-Instanz.
• Optional: Tailscale oder VPN für sicheren Fernzugriff.

Installation in einem LXC

1. LXC erstellen

pct create 400 ubuntu-24.04-standard_24.04-1_amd64.tar.zst \
  --hostname openhands \
  --storage local-zfs \
  --rootfs 80 \
  --memory 16384 \
  --cores 4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

Falls Docker im LXC genutzt werden soll, muss das Container-Profil keyctl=1 und nesting=1 haben:

pct set 400 --features keyctl=1,nesting=1

2. Docker installieren

pct start 400
pct exec 400 -- bash
apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
usermod -aG docker root

3. OpenHands mit Docker starten

mkdir -p ~/.openhands /projects
docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -v /projects:/projects \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

OpenHands ist dann unter http://<lxc-ip>:3000 erreichbar.

Installation mit uv

Alternativ kann OpenHands mit uv direkt installiert werden:

apt install -y pipx
pipx install uv
uv tool install openhands --python 3.12

Starten:

openhands serve

Diese Variante läuft ohne Docker, verzichtet aber auf die Sandbox-Isolation.

LLM-Anbindung

Ollama lokal

Wenn Ollama in einem anderen LXC oder auf dem gleichen Host läuft, verbinde OpenHands über die interne IP:

http://192.168.1.50:11434

Wähle in den OpenHands-Einstellungen als Provider ollama und als Modell zum Beispiel qwen2.5-coder:14b oder codestral.

Externer Provider

Für OpenAI, Anthropic, DeepSeek oder OpenRouter hinterlege den API-Key in den Einstellungen. LiteLLM übernimmt die Kommunikation.

Workspace und Projekte

Das Verzeichnis /projects im Container wird in OpenHands als Arbeitsbereich genutzt. Du kannst Repositories klonen oder Dateien hochladen. Der Agent arbeitet dann in diesem Verzeichnis.

cd /projects
git clone https://github.com/DEIN_BENUTZERNAME/repo.git

Sicherheit

OpenHands kann Shell-Befehle ausführen. Daher ist Vorsicht geboten:

• Isolierter LXC oder VM: Kein direkter Zugriff auf den Proxmox-Host.
• Sandbox aktivieren: Docker-Container für Agenten nutzen.
• Dateisystemeinschränkung: Nur /projects und benötigte Pfade mounten.
• Keine Root-Rechte: OpenHands nicht als root ausführen.
• Netzwerk abgrenzen: Tailscale oder Firewall regeln den Zugriff.
• API-Keys schützen: In .env-Datei oder Secret-Manager ablegen.
• Snapshots vor wichtigen Aufgaben: Zustand sichern.

Integration in den Workflow

• Git einrichten: Name und E-Mail im Container konfigurieren.
• SSH-Keys: Für den Zugriff auf private Repositories.
• VS Code Tunnel: Für direkte Bearbeitung des Agenten-Outputs.
• CI-Integration: Ergebnisse in GitHub Actions oder GitLab CI weiterverarbeiten.

Typische Stolpersteine

• Docker-Socket-Fehler: LXC braucht nesting=1 und Docker-Rechte.
• Zu wenig RAM: Agent-Server-Images sind gross, 8 GB reichen kaum.
• Falsches Modell: Nicht jedes Modell eignet sich für Coding-Agenten.
• Keine GPU: Längere Wartezeiten bei grösseren Modellen.
• Fehlende Netzwerkisolation: Container können externe Dienste kontaktieren.
• Falsche Ollama-URL: /v1-Endpoint verwenden, wenn OpenHands OpenAI-kompatibel anspricht.

Weiterführende Links und Infos

• BotServ.de OpenClaw auf Proxmox
• BotServ.de Proxmox Backups und Restore
• BotServ.de Proxmox Grundlagen
• BotServ.de Tailscale Grundlagen
• BotServ.de Ollama verwalten

FAQ: OpenHands auf Proxmox

Brauche ich eine GPU? Nein, aber für grössere Modelle oder schnelle Antworten ist sie sehr hilfreich.

Kann ich OpenHands in Docker auf Proxmox laufen lassen? Ja, entweder im LXC mit Docker oder direkt in einer VM.

Ist OpenHands sicher? Nur, wenn es isoliert und mit Sandbox läuft. Shell-Zugriff ist immer ein Risiko.

Welches Modell eignet sich am besten? Coding-Modelle wie Qwen 2.5 Coder, DeepSeek-Coder oder Codestral.

Kann OpenHands mit Git arbeiten? Ja, es kann Repos klonen, Änderungen vornehmen und Commits erstellen.

Quellen und weiterführende Literatur

• OpenHands Docs: https://docs.openhands.dev/
• OpenHands GitHub: https://github.com/All-Hands-AI/OpenHands
• LiteLLM: https://docs.litellm.ai/

Zusammenfassung: OpenHands auf Proxmox

OpenHands ist ein leistungsfähiges Coding-Agenten-Framework, das sich gut in einem Proxmox-LXC oder einer VM isoliert betreiben lässt. Wichtig sind ausreichend RAM, Docker-Sandbox, korrekte LLM-Anbindung und starke Netzwerk- sowie Dateisystemabgrenzung. Wer OpenHands mit Ollama oder einem günstigen externen Provider kombiniert, bekommt einen eigenständigen Assistenten für Entwicklungsaufgaben, der im eigenen Netzwerk bleibt.