Hermes dokumentiert aktuell eine OpenAI-kompatible API, einen TUI-Gateway und ACP. Für dieses Dashboard ist die API-Variante der sauberste Start. Free Claude Code läuft lokal weiter; ein Mini-Bridge-Prozess nimmt die Chat-Nachricht entgegen, startet den CLI-Prozess und gibt JSON zurück. Wenn das zu hakelig ist, nimm OpenRouter als Fallback-Endpunkt.

# LAB.01 Agent OS: VPS Docker Deployment Guide (Free Claude Code & OpenRouter)

Diese Anleitung beschreibt, wie das Dashboard auf deinem VPS mit CloudPanel gehostet wird, die Claude-Bridge (mit integriertem Free Claude Code-Proxy) und Obsidian-Bridge in Docker-Containern gestartet werden und die bereits existierende Hermes-Instanz (Port 9119) angebunden wird.

---

## 1. Dashboard auf dem VPS einrichten (CloudPanel)

Da das Dashboard eine reine Frontend-Seite ist, kannst du es in CloudPanel als Static Website anlegen:

1. Logge dich in dein CloudPanel ein.
2. Gehe auf Sites -> Add Site -> Create a Static Website.
3. Gib deine Domain oder eine Subdomain ein (z. B. agentos.deine-domain.de oder nutze deine Tailscale-IP).
4. Lade die Datei lab01-agent-console.html in das Root-Verzeichnis der Website (htdocs/) hoch und benenne sie um in index.html.

Das Dashboard erkennt beim Laden im Browser automatisch, von welcher VPS-IP/Domain es aufgerufen wurde, und leitet alle Anfragen (Claude auf Port 6767, Obsidian auf Port 6768, Hermes auf Port 9119) automatisch an deinen VPS weiter.

---

## 2. Docker Compose Bridges starten (VPS)

Das Setup startet die Claude- und die Obsidian-Brücke gekapselt und sicher auf deinem VPS.

1. Erstelle auf deinem VPS ein Verzeichnis für dein Agent-OS (z. B. /root/agent-os).
2. Kopiere den gesamten Projektordner (inklusive dem Unterordner free-claude-code/, docker-compose.yml, Dockerfile.claude, claude-bridge.js und obsidian-bridge.js) auf deinen VPS.
3. Öffne die docker-compose.yml auf dem VPS und trage deine API-Keys (z. B. OPENROUTER_API_KEY) und das gewünschte freie Modell (Variable MODEL) ein:
   environment:
     - CLAUDE_COMMAND=fcc-claude
     - PORT=6767
     - OPENROUTER_API_KEY=dein_openrouter_key
     - MODEL=open_router/openrouter/free
4. Erstelle auf dem VPS den Ordner workspace (hier arbeitet Claude) und kopiere deinen Obsidian-Vault nach obsidian/DAS_SYSTEM:
   mkdir workspace
   mkdir -p obsidian/DAS_SYSTEM
5. Starte die Docker-Container auf dem VPS:
   docker compose up -d --build
    Die Brücken lauschen nun auf Port 6767 (Claude) und Port 6768 (Obsidian).

#### Alternative: Bereitstellung direkt über Portainer Stacks (Vollständig verwaltet)
Wenn du den Stack direkt in Portainer anlegen möchtest, damit die Container voll integriert und verwaltet sind, folge diesen Schritten:

1. Kopiere den Projektordner auf deinen VPS (z. B. nach `/root/agent-os`).
2. Kopiere deinen Obsidian-Vault nach `/root/agent-os/obsidian/DAS_SYSTEM`.
3. Gehe in Portainer auf **Stacks** -> **Add stack** -> **Web editor**.
4. Kopiere den Inhalt der `docker-compose.yml` hinein, passe deine API-Keys an und ändere die **relativen Pfade (`.`) in absolute Pfade (`/root/agent-os`) um**, damit Portainer die Dateien findet:
   ```yaml
   services:
     claude-bridge:
       build:
         context: /root/agent-os
         dockerfile: Dockerfile.claude
       # ...
       volumes:
         - /root/agent-os/workspace:/app/workspace
         - claude-config:/root/.config
       # ...
     obsidian-bridge:
       # ...
       volumes:
         - /root/agent-os:/app
         - /root/agent-os/obsidian/DAS_SYSTEM:/app/vault
   ```
5. Klicke unten auf **Deploy the stack**. Portainer baut und startet die Container nun voll integriert.

---

## 3. Erstmaliger Claude Code Login im Container (Wichtig)

Damit Claude Code sich mit dem lokalen Proxy verbindet, führt die Bridge den Befehl fcc-claude aus. Du musst dich einmalig innerhalb des Containers anmelden, um die Umgebung zu aktivieren:

1. Verbinde dich per SSH auf deinen VPS.
2. Starte die interaktive Free-Claude CLI im laufenden Container:
   docker exec -it claude-bridge fcc-claude
3. Folge den Anweisungen auf dem Bildschirm. Da der free-claude-code-Proxy aktiv ist, wirst du zu einer lokalen oder simulierten Authentifizierung weitergeleitet, die du im Browser bestätigen kannst.
4. Sobald der Login im Terminal erfolgreich bestätigt wurde, kannst du das CLI mit exit oder Ctrl+D verlassen.

Ab jetzt leitet der Container alle Anfragen über den internen Proxy direkt an OpenRouter (oder dein konfiguriertes freies Modell) weiter.

---

## 4. Hermes API (Docker)

* Hermes läuft laut deiner Konfiguration bereits in einem Docker-Container auf Port 9119.
* Das Dashboard spricht diesen Port automatisch unter http://<VPS-IP>:9119/v1/chat/completions an.
* Stelle sicher, dass der Port 9119 über deine Tailscale-Schnittstelle auf dem VPS erreichbar ist.

---

## 5. Tailscale & Sicherheit

Da die Claude- und Obsidian-Bridges tiefe Eingriffe ins Dateisystem machen, sollten sie niemals öffentlich im Internet stehen:

1. Stelle sicher, dass die Ports 6767 (Claude), 6768 (Obsidian) und 9119 (Hermes) in der VPS-Firewall für die Öffentlichkeit gesperrt sind.
2. Greife auf das Dashboard über deine Tailscale-IP des VPS (z. B. http://100.x.y.z oder die CloudPanel-Subdomain über dein internes VPN) zu.