HydraHive Handbuch

1. Installation

Voraussetzungen

• Ubuntu 22.04 oder 24.04 LTS (amd64)
• Mindestens 4 GB RAM, 20 GB Disk
• Root-Zugriff
• Internetzugang für Download

Installer ausführen

git clone https://github.com/tilleulenspiegel/hydrahive.git
cd hydrahive
sudo bash installer/install.sh

Der Installer läuft vollautomatisch und richtet ein:

• conduwuit (Matrix-Homeserver)
• HydraHive Core (Python-Backend)
• HydraHive Console (React-Frontend via nginx)
• HTTPS mit self-signed Zertifikat
• Optional: Ollama (bei PROFILE=full)

HTTPS und Zertifikat

Nach der Installation ist die Konsole unter https://<IP> erreichbar. Browser zeigen eine Warnung wegen des self-signed Zertifikats — einmalig bestätigen.

Für ein echtes Zertifikat mit Let's Encrypt:

apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d mein.domain.de

2. Erster Login

Nach der Installation ist die Konsole sofort nutzbar. Der Installer hat einen Admin-Account angelegt:

• Benutzername: admin
• Passwort: steht in /etc/hydrahive/admin_credentials auf dem Server

sudo cat /etc/hydrahive/admin_credentials
# matrix_admin_password=<generiertes-passwort>

3. Die Webkonsole

Die Konsole ist unter https://<IP> erreichbar. Alle Bereiche sind über die linke Sidebar zugänglich:

4. Agenten anlegen

Agenten sind KI-Persönlichkeiten die Aufgaben ausführen. Jeder Agent hat einen Typ, ein Sprachmodell und optional eine "Soul" (Persönlichkeitsbeschreibung).

Agent-Typen

Agent anlegen (Konsole)

1. 1Agenten → Neuer Agent
2. 2Felder ausfüllen: Agent-ID, Anzeigename, Typ, LLM-Modell, Tools, Soul
3. 3Agent anlegen klicken

Agent-Konfiguration (Datei)

Agenten liegen als Verzeichnisse unter /agents/<id>/:

/agents/steuer-agent/
├── agent.yaml       # Konfiguration
├── soul.md          # Persönlichkeit (optional)
└── skills/          # Skill-Dateien (optional)
    ├── steuerrecht.md
    └── buchhaltung.md

agent.yaml:

id: steuer-agent
type: specialist
identity: Steuerbert

llm:
  model: llama3.1:8b
  temperature: 0.7
  max_tokens: 4096

tools:
  - file_read
  - file_write

heartbeat:
  interval: 30s
  timeout: 90s
  on_failure: restart

heartbeat_tasks:
  - id: tagesstart
    message: "Guten Morgen! Bitte prüfe offene Aufgaben."
    schedule: "0 8 * * 1-5"    # Mo–Fr um 08:00
    active_hours: "07:00-22:00"

  - id: erinnerung
    message: "Bitte prüfe ob neue Dokumente hochgeladen wurden."
    interval: 3600              # jede Stunde

Heartbeat Tasks — Automatische Aktivierung

heartbeat_tasks definiert periodische Aufgaben die der Agent automatisch ausführt.

Verfügbare Tools

shell_exec Blocklist

shell_exec läuft ohne Sandbox mit vollem Systemzugriff, ist aber gegen destruktive Aktionen gesichert. Folgende Kommandos werden immer blockiert, unabhängig vom Agenten:

Geblockte Befehle werden mit einer Fehlermeldung abgelehnt und im Log protokolliert.

5. Projekte anlegen

Ein Projekt ist ein isolierter Arbeitsbereich: eigener Linux-User, eigenes Verzeichnis, optionale Samba-Freigabe, optionaler Matrix-Room.

Projekt anlegen (Konsole)

1. 1Projekte → Neues Projekt
2. 2Projekt-ID, Name, Boss-Agent, Worker-Agenten und Samba-Option eintragen
3. 3Projekt anlegen klicken

HydraHive richtet automatisch ein:

• Linux-User proj_<id> mit eigenem Home-Verzeichnis
• Verzeichnis /projects/<id>/ für Agenten-Dateien
• Matrix-Room (wenn Matrix konfiguriert)
• Samba-Freigabe (wenn aktiviert)

Projekt-Konfiguration (Datei)

# /projects/buchhaltung/project.yaml
id: buchhaltung
version: "1.0.0"

identity:
  name: Buchhaltung GmbH
  description: Finanzagenten für die GmbH

agents:
  boss: finanz-boss
  workers:
    - steuer-agent
    - buchhalter

matrix:
  room: "!abc123:mein-server.de"    # leer → wird automatisch angelegt

filesystem:
  samba: true

chat:
  show_swarm: false    # true = Worker im Chat anzeigen

6. Chat verwenden

1. 1Projekte → Chat öffnen beim gewünschten Projekt
2. 2Nachricht eingeben und Enter drücken (oder Shift+Enter für Zeilenumbruch)
3. 3Die Antwort erscheint Token-für-Token (Streaming)

Swarm-Ansicht

Das Netzwerk-Symbol oben rechts im Chat schaltet die Swarm-Ansicht um. Bei aktivierter Ansicht wird unter jeder Antwort angezeigt welche Worker-Agenten beteiligt waren.

Token-Anzeige

Unter jeder Assistenten-Antwort erscheint eine kleine Anzeige mit dem Tokenverbrauch der aktuellen Anfrage:

↑ 12.450 ↓ 380 Tokens

• ↑ = Input-Tokens (gesendeter Kontext inkl. System-Prompt und History)
• ↓ = Output-Tokens (erzeugte Antwort)

Die Anzeige hilft dabei, den LLM-Ressourcenverbrauch im Blick zu behalten — besonders bei kostenpflichtigen Modellen (Claude, GPT-4 etc.).

Chat-History

Die Nachrichten einer Session bleiben erhalten und werden beim nächsten Öffnen automatisch geladen.

Slash Commands

Tippe / um verfügbare Schnellbefehle anzuzeigen. Das Dropdown öffnet sich automatisch und kann mit Pfeiltasten navigiert werden.

Bedienung: Pfeiltasten zum Navigieren, Tab oder Enter zum Auswählen, Escape schließt das Dropdown.

7. LLM-Konfiguration

Ollama (lokal, kostenfrei)

Standardmäßig läuft Ollama lokal auf Port 11434. Modelle werden über LLM-Config → Ollama verwaltet.

Empfohlene Modelle:

• llama3.2:3b — schnell, wenig RAM (4 GB)
• llama3.1:8b — ausgewogen (8 GB RAM)
• mistral-nemo:12b — beste Qualität lokal (12 GB RAM)

Claude Max (OAuth)

Für Claude-Modelle via Claude Max Abonnement:

1. 1LLM-Config → Claude Max
2. 2OAuth-Token einfügen (sk-ant-oat01-...)
3. 3Speichern

Der Token-Status wird mit Ablauf-Datum angezeigt. oat01-Tokens gelten ~30 Tage.

OpenAI / andere Anbieter

1. 1LLM-Config → Anbieter konfigurieren
2. 2API-Key und Modell eintragen

8. Skills — Agenten-Wissen erweitern

Skills sind Markdown-Dateien die dem Agenten zusätzliches Wissen geben. Sie werden automatisch in den System-Prompt geladen.

Skill anlegen (Konsole)

1. 1Agenten → Agent auswählen → Skills (Buch-Icon)
2. 2Neuer Skill
3. 3Dateiname, Skill-Name, Scope, Trigger-Keywords, Priority und Inhalt ausfüllen

Skill-Datei (direkt)

---
skill: Steuerrecht Grundlagen
version: "1.0"
scope: on-demand
triggers:
  - steuer
  - finanzamt
  - umsatzsteuer
priority: 10
---

## Steuerrecht Grundlagen

Umsatzsteuer (USt) beträgt in Deutschland standardmäßig 19%.
Ermäßigter Satz: 7% für Lebensmittel, Bücher, ÖPNV.

9. Persönlicher Agent (Mein Agent)

Jeder User bekommt automatisch einen persönlichen Agenten — personal_<username>. Dieser Agent läuft unabhängig von Projekten und ist direkt über Mein Agent in der Sidebar erreichbar.

Chat

Der Chat unter Mein Agent → Chat funktioniert wie der Projekt-Chat: Streaming, History, Slash Commands. Der Agent merkt sich den Gesprächsverlauf sessionübergreifend.

Einstellungen

Unter Mein Agent → Einstellungen kann jeder User seinen Agenten selbst konfigurieren:

10. Gedächtnis-System (Memory)

Das Gedächtnis-System ermöglicht Agenten, Informationen persistent über Sessions hinaus zu speichern und beim nächsten Start automatisch zu laden.

Funktionsweise

Memory-Dateien liegen als Markdown unter /agents/<id>/memory/ und werden beim Start jeder Session automatisch in den System-Prompt injiziert.

/agents/personal_admin/memory/
├── user.md          # Informationen über den User
├── projects.md      # Aktive Projekte und Kontext
└── daily_2026-03-21.md  # Tages-Notizen

Memory-Tools

A-MEM Memory Search

Wenn der Agent amem als MCP-Server konfiguriert hat, kann er gezielt in der gemeinsamen Wissensdatenbank suchen statt alles lokal zu laden — spart erheblich Tokens:

# Im Chat:
"Was weißt du über das AgentLink-Projekt?"
→ Agent: amem_search("AgentLink Projekt")
→ Liefert nur relevante Abschnitte

11. WKS-Zugang (Workstation)

Persönliche Agenten können via SSH auf die eigene Workstation des Users zugreifen — Dateien lesen/schreiben und Befehle ausführen.

WKS einrichten

1. 1Mein Agent → WKS öffnen
2. 2IP-Adresse der Workstation eintragen (z.B. 192.168.1.101)
3. 3SSH-Benutzer eintragen (z.B. till)
4. 4SSH Private Key (PEM) einfügen
5. 5Ollama-Port eintragen (Standard: 11434) → Speichern

Public Key auf der Workstation hinterlegen:

echo "ssh-ed25519 AAAA... hydrahive-wks@hydrahive" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
sudo systemctl enable --now ssh

Klick auf Verbindung testen zeigt die verfügbaren Ollama-Modelle auf der WKS.

WKS-Tools

WKS-Ollama

Wenn Ollama auf der Workstation läuft und von außen erreichbar ist, erscheinen WKS-Modelle im Modell-Dropdown als WKS: <modellname>:

# Ollama auf allen Interfaces lauschen lassen:
sudo mkdir -p /etc/systemd/system/ollama.service.d
echo '[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"' | sudo tee /etc/systemd/system/ollama.service.d/listen.conf
sudo systemctl daemon-reload && sudo systemctl restart ollama

12. Git-Tools

Agenten können direkt mit Gitea interagieren — Git-Status prüfen, Commits erstellen und Pull Requests öffnen.

Gitea konfigurieren

Unter LLM-Config → Gitea oder direkt in /etc/hydrahive/gitea_config.json:

{
  "url": "http://192.168.1.100:3001",
  "token": "dein-gitea-token",
  "org": "hydrahive"
}

Git-Tools

13. MCP-Server

MCP (Model Context Protocol) ermöglicht Agenten den Zugriff auf externe Tool-Server. HydraHive unterstützt streamableHttp-Transport.

MCP-Server konfigurieren (Admin)

1. 1MCP-Server in der Sidebar → Neuer MCP-Server
2. 2ID, Name, Transport (streamableHttp), URL eintragen

A-MEM — Shared Memory MCP

HydraHive wird mit einem A-MEM-MCP-Server ausgeliefert (Port 8020). Er ermöglicht semantische Suche in der gemeinsamen Wissensdatenbank und im A-MEM-Index. Die Web-UI läuft auf Port 8021:

[
  {
    "id": "amem",
    "name": "A-MEM Shared Memory",
    "transport": "streamableHttp",
    "url": "http://127.0.0.1:8020/sse"
  }
]

MCP im Agenten aktivieren

MCP-Server werden pro Agent in agent.yaml eingetragen:

mcp_servers:
  - amem

Oder unter Mein Agent → MCP für den persönlichen Agenten.

14. Webhooks

Webhooks ermöglichen externen Systemen HydraHive zu triggern — z.B. bei einem Git-Push automatisch einen Agenten starten.

Webhook anlegen (Konsole)

1. 1Projekte → Webhook-Icon beim Projekt
2. 2Neuer Webhook
3. 3URL, Name, Events und optional Secret eintragen

Verfügbare Events: message, agent_error, provision, agent_start, agent_stop

Externer Trigger (Wake-Endpoint)

curl -X POST https://<ip>/api/hooks/<projekt-id>/wake \
  -H "Content-Type: application/json" \
  -d '{"message": "Neuer Git-Push auf main — bitte Code-Review starten"}'

HMAC-Signierung

Wenn ein Secret gesetzt ist, wird jeder ausgehende Webhook-Request mit X-HydraHive-Signature: sha256=<hmac> signiert.

import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert f"sha256={expected}" == request.headers["X-HydraHive-Signature"]

15. Benutzer und Rollen

Unter Benutzer (Admin only) werden Accounts verwaltet. HydraHive kennt zwei Rollen:

• Neuer Benutzer: Benutzername, Passwort und Rolle wählen
• Passwort ändern: Stift-Symbol
• Löschen: Papierkorb-Symbol (eigener Account kann nicht gelöscht werden)

16. Backup & Restore

Unter Backup (Admin only) können vollständige System-Backups erstellt und verwaltet werden.

Was wird gesichert?

Ein Backup enthält als tar.gz:

• /etc/hydrahive/ — Konfigurationsdateien (JWT-Secret, Users, LLM-Config)
• /agents/ — alle Agenten-Definitionen und Skills
• /projects/ — Projekt-Konfigurationen und Agenten-Dateien

Backup erstellen

1. 1Backup → Backup erstellen
2. 2Das Backup erscheint sofort in der Liste mit Zeitstempel und Größe

Backup herunterladen

Klick auf das Download-Symbol neben dem Backup — die tar.gz-Datei wird heruntergeladen.

Backup wiederherstellen

1. 1Klick auf das Wiederherstellen-Symbol
2. 2Bestätigen
3. 3Core-Service startet automatisch neu — nach 10 Sekunden Seite neu laden

17. Audit-Log

Das Audit-Log protokolliert alle sicherheitsrelevanten Aktionen:

• Logins (erfolgreich und fehlgeschlagen)
• Benutzer anlegen/löschen
• Agenten anlegen/löschen
• Projekte anlegen/provisionieren
• Skills anlegen/ändern/löschen
• Webhooks anlegen/löschen/auslösen
• LLM-Token setzen

Gespeichert in /var/log/hydrahive/audit.jsonl — append-only, ein JSON-Objekt pro Zeile.

Filter: Nach Benutzer, Aktion, Projekt und Anzahl Einträge filterbar.

18. Matrix-Integration

HydraHive kann Nachrichten über Matrix (Element) empfangen und beantworten.

Element-Client verbinden

Matrix-Server läuft auf Port 8008 (nginx-Proxy → conduwuit auf 6167):

• Homeserver: https://<ip>:8008 oder http://<ip>:8008
• Benutzer: @admin:<hostname>
• Passwort: aus /etc/hydrahive/admin_credentials

Agenten-Bot im Room

Wenn ein Projekt einen Matrix-Room hat, lauscht der Boss-Agent dort automatisch. Nachrichten im Room werden wie Chat-Nachrichten behandelt.

19. GPU-Monitoring

Wenn eine NVIDIA-Grafikkarte im Server verfügbar ist, zeigt die System-Seite eine GPU-Auslastungsanzeige.

Angezeigte Werte

Die Auslastungsbalken sind farbkodiert: grün (< 80 %), orange (< 95 %), rot (≥ 95 %).

Voraussetzung

NVIDIA-Treiber und nvidia-smi müssen installiert sein. Ohne GPU oder ohne Treiber wird die GPU-Sektion nicht angezeigt — kein Fehler.

20. System-Update

HydraHive kann sich selbst aus der Webkonsole heraus auf den neuesten Stand bringen — ohne SSH.

Update starten

1. 1Sidebar → Update-Button (Admin only, oben links neben dem Logo)
2. 2Bestätigen
3. 3Das System zieht die neuesten Änderungen aus dem Git-Repository, baut die Console neu und startet den Service

Der Update-Status ist live einsehbar — inkl. Log-Ausgaben und Commit-Hash nach Abschluss. Nach einem Update die Seite neu laden.

21. Troubleshooting

Konsole nicht erreichbar

sudo systemctl status nginx
sudo nginx -t
sudo journalctl -u nginx -n 50

Core reagiert nicht

sudo systemctl status hydrahive-core
sudo journalctl -u hydrahive-core -n 100 --no-pager

Agent antwortet nicht

1. 1Agenten → Agent auswählen → Logs-Icon prüfen
2. 2Heartbeat-Status in der Agent-Liste prüfen (orange = Warnung)
3. 3LLM-Verbindung prüfen: LLM-Config → Status

Matrix-Bot antwortet nicht

sudo journalctl -u hydrahive-core -n 50 | grep -i matrix

Der Matrix-Watchdog startet den Bot automatisch neu. Bei dauerhaftem Fehler:

sudo systemctl restart hydrahive-core

OAuth-Token abgelaufen

LLM-Config → Claude Max → Token-Status prüfen. Neuen Token über claude setup holen und eintragen.

Login funktioniert nicht (429 Too Many Requests)

Rate-Limiting: max. 10 Versuche pro Minute. Nach 60 Sekunden warten.

Logs direkt auf dem Server

# Core-Logs
sudo journalctl -u hydrahive-core -f

# Audit-Log
sudo tail -f /var/log/hydrahive/audit.jsonl | python3 -m json.tool

# nginx-Logs
sudo tail -f /var/log/nginx/error.log