Kobold OS Dokumentation

Willkommen zur Dokumentation von Kobold OS — deinem persönlichen KI-Assistenten, der komplett lokal auf deinem Mac oder Server läuft. Hier findest du alles, was du brauchst, um deinen Kobold einzurichten und produktiv einzusetzen.

Unsere Philosophie

Kobold OS ist mehr als Software — es ist eine Überzeugung. Wir glauben, dass KI für alle zugänglich sein sollte, ohne Kompromisse bei Privatsphäre, Kosten oder Kontrolle.

Voraussetzungen

Komponente	macOS App	Docker
Betriebssystem	macOS 14+ (Sonoma)	Linux / macOS / Windows
Ollama	Erforderlich (lokal)	Extern oder im Container
RAM	8 GB+ empfohlen	4 GB+ empfohlen
Speicherplatz	~500 MB + Modelle	~200 MB Image + Daten
Apple Silicon	Empfohlen (M1+)	ARM64 unterstützt

Schnellstart

Der schnellste Weg zu deinem eigenen Kobold:

1. Ollama installieren: brew install ollama
2. Sprachmodell laden: ollama pull qwen3:4b
3. Kobold OS herunterladen: KoboldOS-0.3.8.dmg
4. App starten — der Daemon auf Port 8080 startet automatisch

macOS App installieren

1. Lade die aktuelle DMG herunter
2. Öffne die DMG und ziehe KoboldOS.app in den /Applications Ordner
3. Beim ersten Start: Rechtsklick → Öffnen (Gatekeeper-Warnung bestätigen)
4. Kobold OS startet den lokalen Daemon automatisch auf http://localhost:8080

Die App läuft als SwiftUI-Anwendung mit einem eingebetteten HTTP-Daemon. Alle Konversationen werden lokal gespeichert unter:

~/Library/Application Support/KoboldOS/sessions.json

Docker Installation

Schnell-Setup

docker pull funkjood/koboldos:latest

docker run -d \
  --name koboldos \
  -p 8080:8080 \
  -v koboldos-data:/data \
  -v /var/run/docker.sock:/var/run/docker.sock \
  funkjood/koboldos:latest

Mit Docker Compose

version: '3.8'
services:
  koboldos:
    image: funkjood/koboldos:latest
    ports:
      - "8080:8080"
    volumes:
      - koboldos-data:/data
      - /var/run/docker.sock:/var/run/docker.sock
    restart: unless-stopped
    environment:
      - OLLAMA_HOST=http://host.docker.internal:11434

volumes:
  koboldos-data:

Multi-Architektur

Das offizielle Image unterstützt linux/amd64 und linux/arm64. Es läuft auf x86-Servern genauso wie auf Raspberry Pi oder Apple Silicon.

Aus dem Quellcode bauen

git clone https://github.com/FunkJood/KoboldOS.git
cd KoboldOS
bash scripts/build.sh

Die fertige .app liegt anschließend im dist/ Verzeichnis. Voraussetzung: Xcode Command Line Tools und Swift 6.

Erster Start

Beim ersten Öffnen zeigt Kobold OS die Einstellungen. Hier konfigurierst du:

• Ollama-Verbindung — wird automatisch erkannt wenn Ollama läuft
• Sprachmodell — wähle aus den lokal verfügbaren Modellen
• Autonomie-Level — bestimmt wie selbstständig der Kobold agiert (Standard: 2)
• Verbindungen — optional Telegram, Google, etc. anbinden

Ollama einrichten

Kobold OS nutzt Ollama als Sprachmodell-Backend. Empfohlene Modelle:

Modell	Größe	Stärke	Empfehlung
qwen3:4b	~2.5 GB	Gut	Standard — schnell auf M-Chips
qwen3:8b	~5 GB	Sehr gut	Wenn genug RAM vorhanden
llama3.1:8b	~5 GB	Sehr gut	Alternative mit breitem Wissen
mistral:7b	~4 GB	Gut	Schnell, effizient

# Modell herunterladen
ollama pull qwen3:4b

# Prüfen welche Modelle installiert sind
ollama list

Verbindungen einrichten

Unter Einstellungen → Verbindungen findest du alle verfügbaren Dienste. Jede Verbindung hat eine Statusanzeige und einen "Verbinden"-Button. OAuth-basierte Dienste öffnen ein Browser-Fenster zur Autorisierung.

Dienst	Typ	Was du brauchst
Telegram	Bot Token	Token von @BotFather
Google (Drive, Mail, Kalender)	OAuth 2.0	Google Account
YouTube	OAuth 2.0	Google Account mit YouTube-Kanal
SoundCloud	OAuth 2.0	SoundCloud Account
Spotify	OAuth 2.0	Spotify Account
GitHub	Personal Token	GitHub PAT
Slack	Bot Token	Slack App Token
Notion	Integration	Notion Integration Token
Philips Hue	Bridge	Hue Bridge im Netzwerk
Uber	OAuth 2.0	Uber Account
Reddit	OAuth 2.0	Reddit App Credentials
Suno AI	API Key	API Key von sunoapi.org

Telegram Bot einrichten

1. Öffne Telegram und suche nach @BotFather
2. Sende /newbot und folge den Anweisungen
3. Kopiere den Bot-Token (z.B. 123456:ABC-DEF...)
4. Füge den Token in Kobold OS ein: Einstellungen → Verbindungen → Telegram
5. Sende deinem Bot eine Nachricht — er antwortet ab sofort

Agent-System

Kobold OS arbeitet mit drei spezialisierten Agenten. Der General Agent ist dein Hauptansprechpartner — er entscheidet selbstständig, ob er eine Aufgabe selbst erledigt oder an einen Spezialisten weitergibt.

General Agent

Der Orchestrator. Er führt Gespräche, plant Aufgaben und delegiert an die anderen Agenten. Jede Nachricht, die du sendest, geht zuerst an den General.

• Gespräche führen und Fragen beantworten
• Aufgaben planen und koordinieren
• Gedächtnis lesen und schreiben
• Entscheidet ob Coder oder Web Agent nötig ist

Coder Agent

Spezialisiert auf Dateien und Code. Schreibt Skripte, bearbeitet Dateien, führt Shell-Befehle aus.

• Dateien lesen, schreiben, verschieben, löschen
• Shell-Befehle ausführen
• Code generieren und ausführen
• Git-Operationen

Web Agent

Zuständig für alles was mit dem Internet zu tun hat. Recherche, API-Aufrufe, Web-Scraping.

• Webseiten aufrufen und analysieren
• Suchmaschinen nutzen
• APIs aufrufen
• Daten aus dem Web extrahieren

Tool-Übersicht

Kobold OS verfügt über 49+ integrierte Tools in 9 Kategorien:

Kategorie	Tools	Beschreibung
Dateisystem	read, write, list, move, delete	Dateien und Ordner verwalten
Shell	execute, script	Befehle und Skripte ausführen
Gedächtnis	remember, recall, forget	Langzeit-Speicher für Kontext
Kommunikation	telegram, email, notify	Nachrichten senden und empfangen
Medien	image_gen, youtube, soundcloud	Bilder und Medien erstellen/hochladen
Kalender	events, reminders	Termine und Erinnerungen
Cloud	drive, github, notion	Cloud-Dienste anbinden
Smart Home	hue_lights, hue_scenes	Beleuchtung steuern
Web	browse, search, scrape	Internet-Recherche

Gedächtnis

Das persistente Gedächtnis ist eine der Kernfunktionen. Der Kobold speichert Informationen über dich und deine Projekte und ruft sie automatisch ab, wenn sie relevant sind.

• Automatisch — der Kobold erkennt relevante Informationen im Gespräch
• Manuell — sage "Merk dir, dass..." um gezielt Dinge zu speichern
• Verwaltung — über die WebUI kannst du Einträge ansehen, filtern und bearbeiten

Gespeichert wird unter: ~/Library/Application Support/KoboldOS/memory/

Geplante Aufgaben

Der Kobold kann Aufgaben zeitgesteuert ausführen — ähnlich wie Cron-Jobs, aber mit natürlicher Sprache steuerbar.

# Beispiel Cron-Presets:
Täglich um 8:00        → 0 8 * * *
Alle 30 Minuten         → */30 * * * *
Montags um 9:00         → 0 9 * * 1
Erster des Monats       → 0 0 1 * *

Aufgaben werden in der App unter Aufgaben verwaltet. Du kannst sie aktivieren/deaktivieren, manuell ausführen und die letzte Ausführung prüfen.

Bildgenerierung

Kobold OS kann lokal Bilder generieren über ComfyUI mit Stable Diffusion XL.

Setup

1. ComfyUI installieren (empfohlen: ~/KoboldAI_ImageEngine/)
2. Modelle herunterladen (z.B. Juggernaut XL)
3. ComfyUI starten: bash ~/KoboldAI_ImageEngine/start_image_engine.sh
4. Kobold OS erkennt die ComfyUI-Instanz automatisch auf Port 8188

Verwendung

Beschreibe einfach was du sehen möchtest:

"Erstelle ein Bild: Ein Kobold sitzt auf einem Goldberg bei Sonnenuntergang"

Generierte Bilder werden unter ~/Documents/KoboldOS/Bilder/ gespeichert.

WebUI

Die WebUI ist unter http://localhost:8080 erreichbar und bietet folgende Bereiche:

• Chat — Hauptinterface mit SSE-Streaming, Tool-Call-Anzeige, Thinking-Panel und Thought Stream
• Aufgaben — Cron-Tasks verwalten mit 8 Presets
• Gedächtnis — Einträge durchsuchen, filtern und bearbeiten
• Workflows — Workflow Engine mit visuellem Builder und Workflow Chat
• Einstellungen — Modell, Verbindungen, Autonomie-Level
• Teams — Multi-User-Zugriff auf die WebUI mit separaten Sessions

Telegram

Nach dem Bot-Setup kannst du deinem Kobold direkt per Telegram schreiben. Er antwortet mit dem vollen Agent-System inklusive aller Tools.

• Text-Nachrichten → werden an den Agent weitergeleitet
• Dateien senden → werden heruntergeladen und können verarbeitet werden
• Bilder senden → können analysiert werden (falls Modell es unterstützt)

WhatsApp

WhatsApp-Integration läuft über die WhatsApp Business API. Du brauchst einen Meta-Developer-Account und eine verifizierte Telefonnummer. Die Einrichtung ist aufwändiger als Telegram, bietet aber den Vorteil, dass du deinen Kobold über die weltweit meistgenutzte Chat-App erreichst.

Google (Drive, Mail, Kalender)

Mit einem OAuth-Login bekommt dein Kobold Zugriff auf:

• Google Drive — Dateien hoch- und herunterladen, Ordner verwalten
• Gmail — E-Mails lesen, zusammenfassen, senden
• Google Kalender — Termine erstellen, abfragen, löschen

YouTube

Upload-Funktion für YouTube-Videos über das Resumable Upload Protocol. Der Kobold kann:

• Videos hochladen mit Titel, Beschreibung und Tags
• Thumbnails setzen
• Kanalstatistiken abrufen

SoundCloud

Audio-Uploads und Suche auf SoundCloud. Unterstützt Multipart-Upload bis 500 MB mit automatischer MIME-Type-Erkennung.

Weitere Dienste

Dienst	Funktionen
Spotify	Suche, Playlists, Wiedergabe-Steuerung
GitHub	Repos, Issues, PRs, Code-Suche
Slack	Nachrichten senden und empfangen
Notion	Seiten lesen und bearbeiten
Philips Hue	Lichter, Szenen, Gruppen steuern
Uber	Fahrten-Status und Preisschätzungen
Reddit	Suche, Posts lesen, kommentieren
Suno AI	Musik generieren lassen

Daemon API

Der lokale Daemon läuft auf Port 8080 und bietet folgende Endpoints:

Endpoint	Methode	Beschreibung
/agent/stream	POST	Haupt-Endpoint — SSE-Stream mit vollem Agent-Loop
/health	GET	Status-Check mit Agent-ID und Version
/models	GET	Verfügbare Ollama-Modelle auflisten
/settings	GET/POST	Einstellungen lesen und schreiben

Beispiel-Request

curl -N -H "Authorization: Bearer DEIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hallo Kobold!", "conversation_history": []}' \
  http://localhost:8080/agent/stream

Roadmap

Wohin geht die Reise? Hier siehst du, was wir bereits geschafft haben, woran wir aktuell arbeiten und was als nächstes kommt.

FAQ

Brauche ich einen Cloud-Account?

Nein. Kobold OS läuft komplett lokal mit Ollama. Cloud-Dienste wie Google oder Telegram sind optional und erfordern deine ausdrückliche Verbindung.

Welche Daten verlassen meinen Rechner?

Nur wenn du aktiv eine Verbindung nutzt (z.B. eine Telegram-Nachricht sendest oder ein Video auf YouTube hochlädst). Das Sprachmodell und alle Konversationen bleiben lokal.

Kann ich mehrere Modelle gleichzeitig nutzen?

Ja — Ollama verwaltet mehrere Modelle. Du kannst in den Einstellungen das Standard-Modell wechseln. Der Kobold nutzt immer das aktuell eingestellte Modell.

Ist Kobold OS kostenlos?

Ja — alle Grundfunktionen mit lokalen Modellen sind und bleiben kostenlos. Für Cloud-Modelle (wie GPT-4, Claude, etc.) planen wir eine faire monatliche API-Flatrate mit großzügigem Volumen.

Problemlösung

Daemon startet nicht

• Prüfe ob Port 8080 bereits belegt ist: lsof -i :8080
• Starte die App neu — der Daemon wird nur in AppDelegate gestartet

Ollama nicht erreichbar

• Prüfe ob Ollama läuft: ollama list
• Standard-Port ist 11434: curl http://localhost:11434/api/tags

Telegram Bot antwortet nicht

• Prüfe den Bot-Token in den Einstellungen
• Stelle sicher, dass deine Chat-ID autorisiert ist
• Prüfe die Daemon-Logs in der Konsole der App

Bilder werden nicht generiert

• Prüfe ob ComfyUI läuft: curl http://localhost:8188/system_stats
• Stelle sicher, dass mindestens ein Modell in ~/KoboldAI_ImageEngine/models/ liegt