⚙️ Installation

Systemanforderungen

Windows — Automatischer Installer

Der einfachste Weg auf Windows:

1. HiveMind herunterladen

   Lade die neueste Version von der Download-Seite herunter und entpacke das ZIP-Archiv in einen Ordner deiner Wahl, z.B. C:\HiveMind\.

2. Installer ausführen

   Führe install-windows.bat als Administrator aus. Das Skript installiert automatisch alle Python-Abhängigkeiten und richtet die virtuelle Umgebung ein.

   :: Rechtsklick → "Als Administrator ausführen"
   install-windows.bat

3. Modell herunterladen

   Das Installer-Skript fragt, ob es automatisch ein passendes Modell herunterladen soll. Empfohlen: Qwen2.5-7B-Instruct-Q4_K_M (~4.5 GB).

4. Konfiguration anpassen

   Öffne config.yaml in einem Texteditor und passe mindestens das Dashboard-Passwort an.

5. HiveMind starten

   Doppelklick auf start.bat — das Dashboard öffnet sich automatisch im Browser unter http://127.0.0.1:8420/.

Windows — Manuell

Für erfahrene Nutzer, die die Kontrolle behalten möchten:

# 1. Python 3.12 installieren (python.org)
# 2. ZIP entpacken und in den Ordner navigieren
cd C:\HiveMind

# 3. Virtuelle Umgebung erstellen
python -m venv .venv
.venv\Scripts\activate

# 4. Abhängigkeiten installieren
pip install -e .

# 5. CUDA-Version von llama-cpp-python (für NVIDIA GPU)
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124

# 6. Starten
python -m hivemind

Linux / macOS

# Voraussetzungen (Ubuntu/Debian)
sudo apt update && sudo apt install python3.12 python3.12-venv git -y

# Repository / Archiv entpacken
unzip hivemind-1.2.2.zip -d ~/hivemind
cd ~/hivemind

# Installer ausführen
chmod +x install.py
python3 install.py

# ODER manuell:
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Mit CUDA (NVIDIA)
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python

# Starten
python3 -m hivemind

Modell herunterladen

HiveMind benötigt ein GGUF-Modell. Empfehlungen nach Vram:

Modelle können von Hugging Face heruntergeladen werden. Lege die Datei in den Ordner models/ und trage den Dateinamen in die config.yaml ein.

Konfiguration

Die zentrale Konfigurationsdatei ist config.yaml im HiveMind-Ordner:

model:
  path: "models/qwen2.5-7b-instruct-q4_k_m.gguf"
  context_length: 16384       # Max. Kontext in Token
  gpu_layers: 35              # Auf GPU auslagern (0 = CPU-only)
  threads: 8                  # CPU-Threads

ui:
  port: 8420
  password: "aender-mich"

api:
  key: "dein-geheimer-api-key"

network:
  enabled: true
  port: 9420
  bootstrap_nodes:
    - "relay1.hivemind.network:9420"

telegram:
  enabled: false
  token: ""
  allowed_users: []

assistant:
  name: "HiveMind"
  language: "de"

Erster Start

Beim ersten Start:

1. Das Modell wird geladen — das dauert je nach Hardware 10–60 Sekunden
2. Das Dashboard öffnet sich unter http://127.0.0.1:8420
3. Beim Login das in config.yaml gesetzte Passwort verwenden
4. Auf der Status-Seite prüfen, ob GPU-Beschleunigung aktiv ist

Autostart einrichten

Windows (Aufgabenplaner)

# PowerShell als Administrator:
$action  = New-ScheduledTaskAction -Execute "C:\HiveMind\start.bat"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "HiveMind" -Action $action -Trigger $trigger -RunLevel Highest

Linux (systemd)

# /etc/systemd/system/hivemind.service
[Unit]
Description=HiveMind AI Node
After=network.target

[Service]
User=DEIN_USER
WorkingDirectory=/home/DEIN_USER/hivemind
ExecStart=/home/DEIN_USER/hivemind/.venv/bin/python -m hivemind
Restart=on-failure

[Install]
WantedBy=multi-user.target

# Aktivieren:
sudo systemctl enable --now hivemind

Aktualisieren

Beim Update die Konfigurationsdatei und den models/-Ordner sichern, dann:

1. Neues Archiv von der Download-Seite herunterladen
2. In neuen Ordner entpacken
3. config.yaml und models/ aus alter Installation kopieren
4. Installer/Abhängigkeiten neu ausführen: pip install -e .

Fehlerbehebung

GPU wird nicht erkannt

Prüfe, ob die CUDA-Version von llama-cpp-python installiert ist:

python -c "from llama_cpp import Llama; print('OK')"

Falls Fehler: CUDA-Toolkit 12 installieren und llama-cpp-python neu bauen (mit CMAKE_ARGS="-DGGML_CUDA=on").

Dashboard nicht erreichbar

• Läuft HiveMind noch? Konsole prüfen
• Port-Konflikt? config.yaml → anderen Port wählen
• Firewall blockiert Port 8420? Ausnahmeregel hinzufügen

Modell lädt nicht

• Pfad in config.yaml korrekt? (Backslash auf Windows vs. Slash)
• Genug freier RAM/VRAM?
• GGUF-Datei vollständig heruntergeladen? (sha256sum prüfen)

Sehr langsame Antworten

• GPU-Layers in config erhöhen: gpu_layers: 99 (alles auf GPU)
• Kleineres oder stärker quantisiertes Modell verwenden (Q4_K_M statt Q8)
• Kontext-Länge reduzieren: context_length: 4096