Dokumentation

DucKI Agent — Handbuch

So richtest du deinen Agenten ein und nutzt Chat, Coding, 39 Skills, 9 Plugins und 17 Tools — lokal (BYO) oder in der Cloud.

Überblick

Der DucKI Agent ist ein KI-Assistent, der nicht nur chattet, sondern eigenständig handelt: Dateien lesen und schreiben, Code erstellen, das Web durchsuchen, Git bedienen und über Plugins externe Dienste anbinden. Er merkt sich Kontext über Memory und erweitert sich selbst über Skills.

Es gibt zwei Betriebsarten:

• BYO (Free): Die Web-UI läuft gehostet, den Agenten betreibst du selbst auf deinem Rechner — ideal für lokale Modelle und maximale Datenkontrolle.
• Cloud (bezahlt): Wir hosten den Agenten für dich — nichts zu installieren, automatisch mit deinem Konto verbunden.

Schnellstart

Der schnellste Weg zum eigenen Agenten (BYO):

1. Konto anlegen unter /register (Free-Tier, keine Kreditkarte nötig).
2. Agent installieren — ein Befehl je Betriebssystem auf der Installationsseite.
3. Web-UI öffnen unter /app — sie verbindet sich automatisch mit deinem lokalen Agenten auf http://localhost:3001.

Beispiel (macOS/Linux):

curl -fsSL https://ducki.cloud/install.sh | bash

Alle Plattformen (Windows, macOS, Linux, Raspberry Pi) inkl. Copy-Buttons findest du auf der Download-Seite.

Installation im Detail

Der Installer läuft im Benutzerkontext (kein Admin nötig, sofern Node/git vorhanden) und ist idempotent — erneutes Ausführen aktualisiert eine bestehende Installation. Ablauf des Skripts:

1. Voraussetzungen prüfen/installieren: git und Node.js ≥ 20 (unter Windows automatisch via winget), danach pnpm über Corepack.
2. Quellcode holen: Klonen bzw. Aktualisieren des Repos ducKI-Agent (harter Sync auf den neuesten Stand, damit lokale Build-Artefakte kein Update blockieren).
3. Abhängigkeiten & Build: pnpm install, dann pnpm build:server — baut den Server und alle Workspace-Pakete. Bricht bei Fehlern klar ab.
4. Autostart: Registriert einen Dienst, der den Agenten bei jeder Anmeldung startet, und startet ihn sofort.
5. Health-Check: Wartet, bis der Agent unter /api/health antwortet.

Installationsort, Ports & Dienste

Überschreibbar per Umgebungsvariable: DUCKI_HOME (Zielordner), DUCKI_PORT (Agent-Port).

Aktualisieren & Deinstallieren

Zum Aktualisieren einfach denselben Installationsbefehl erneut ausführen — er zieht den neuesten Stand und baut neu. Manuell geht das auch direkt im Installationsordner:

cd "%LOCALAPPDATA%\ducki-agent\app"
					git fetch --depth 1 origin
					git reset --hard FETCH_HEAD
					pnpm install --prod=false
					pnpm build:server

Zum Deinstallieren den Autostart-Dienst entfernen und den Ordner löschen (schtasks /delete /tn "DucKI Agent" /f, danach den Installationsordner entfernen). Deine erzeugten Dateien liegen im Unterordner shared-workspace — sichere sie vorher bei Bedarf.

Windows ohne Terminal

Wer lieber keine PowerShell-Befehle ausführen möchte, installiert den Agenten unter Windows auch komplett ohne Kommandozeile über die Download-Seite. Empfohlen ist das Komplettpaket: Server und Oberfläche laufen darin in einem einzigen Prozess mit Tray-Icon.

→ Komplettpaket herunterladen (93,7 MB) — Prüfsumme (SHA-256) steht auf der Download-Seite.

ZIP entpacken und ducki-node.exe darin starten. Das bündelt eine eigene, portable Node.js-Laufzeit (kein Node.js und kein Git auf deinem Rechner nötig), startet den Agenten sofort auf http://localhost:3001 und öffnet ein natives Fenster mit der Oberfläche. Danach läuft die App als Tray-Icon (Ente in der Taskleiste) weiter — Rechtsklick öffnet ein Menü mit:

• Oberfläche öffnen — holt das Fenster wieder in den Vordergrund.
• Agent neu starten — startet nur den Backend-Prozess neu, ohne die App zu beenden.
• Logs öffnen — öffnet den Datenordner (Arbeitsverzeichnis, Datenbank) im Explorer.
• Autostart — Checkbox zum Ein-/Ausschalten des automatischen Starts bei der Anmeldung.
• Beenden — stoppt Server und App vollständig.

Windows-Benachrichtigungen informieren über Start, Neustart und Fehler. Schließen des Fensters (X) minimiert nur in den Tray — die App bleibt im Hintergrund aktiv, bis du „Beenden" wählst. Arbeitsverzeichnis und Datenbank liegen in deinem Benutzerprofil, nicht im entpackten Ordner selbst; wichtig ist nur, den kompletten entpackten Ordner zusammenzulassen (ducki-node.exe, node.exe und resources/ gehören zusammen).

Server und Oberfläche gibt es auf der Download-Seite auch einzeln — z. B. für einen Agenten ohne Fenster im Hintergrund, oder eine eigene Oberfläche für einen bereits laufenden Agenten (mehr dazu unter Desktop-App).

Die Web-Oberfläche

Die Web-UI ist deine Kommandozentrale: links die Sidebar mit Sessions und Navigation, in der Mitte der Chat mit dem Agenten, rechts kontextabhängige Panels (z. B. Plugin-Widgets). Sie ist responsiv und unterstützt Light- und Dark-Mode.

Web-UI lokal betreiben

Normalerweise nutzt du die gehostete Web-UI unter /app und verbindest sie mit deinem lokalen Agenten. Du kannst die Oberfläche aber auch komplett selbst hosten — z. B. für den vollständig offline-Betrieb ohne jede Cloud-Verbindung. Dafür gibt es ein zweites Installationsskript für alle Plattformen:

Windows (PowerShell):

irm https://ducki.cloud/install-webui.ps1 | iex

macOS / Linux / Raspberry Pi (Terminal):

curl -fsSL https://ducki.cloud/install-webui.sh | bash

Das Skript baut die Web-UI und liefert sie als Autostart-Dienst aus (Windows-Task „DucKI WebUI", Linux systemd-Unit ducki-webui, macOS launchd). So funktioniert es:

• Die gebaute Oberfläche läuft unter http://localhost:5173.
• Aufrufe an /api und /socket.io werden zum lokalen Agenten (http://localhost:3001) weitergeleitet — die UI ist damit same-origin, es sind keine CORS- oder Backend-Einstellungen nötig.
• Standardmäßig bindet die UI nur an 127.0.0.1 (kein Zugriff aus dem Netzwerk).

Anpassbar per Umgebungsvariable:

Desktop-App (Windows)

Das Komplettpaket (empfohlen) enthält Server und Oberfläche bereits zusammen. Wenn du stattdessen nur die Oberfläche für einen bereits laufenden Agenten möchtest (Skript-Installer oben oder ein separat laufendes Server-Paket), gibt es sie auch einzeln: portabel (keine Installation, kein Node.js/keine resources/ nötig — eine einzelne .exe), verbindet sich zur Laufzeit mit http://localhost:3001 (unter Einstellungen → Backend-Verbindung änderbar).

→ Nur-Oberfläche herunterladen (3,9 MB) — die aktuelle Prüfsumme (SHA-256) steht auf der Download-Seite.

Chat & Agent

Im Chat beschreibst du dein Ziel in natürlicher Sprache. Der Agent plant die nötigen Schritte, ruft passende Tools auf und zeigt transparent, was er tut. Größere Tool-Ergebnisse werden als Vorschau eingeblendet, bevor sie in den Verlauf übernommen werden.

Coding & Workspace

Jeder Agent hat einen eigenen Workspace — ein isoliertes Verzeichnis, in dem er Dateien liest, schreibt und Code erstellt. Im Cloud-Modus ist dieser Workspace pro Konto getrennt; im BYO-Modus liegt er auf deinem Rechner.

Typische Coding-Aufgaben:

• Projektdateien lesen und erklären lassen
• Neue Dateien und ganze Features erstellen
• Bestehenden Code umbauen oder debuggen

Skills

Skills sind wiederverwendbare Anleitungen, mit denen sich der Agent neue Fähigkeiten beibringt — kompatibel zum agentskills.io-Standard. Aktuell sind 39 Skills verfügbar. Der Agent kann Skills anlegen, bearbeiten und selbst verwenden.

→ Alle Skills im Katalog ansehen

Plugins

Plugins erweitern den Agenten um komplette Integrationen: ein eigenes Tool, eine Frontend-Seite, ein Widget und optional eine plugin-eigene SQLite-Datenbank (getrennt von der Hauptdatenbank). So bleiben Erweiterungen wie Kalender, Notizen oder Wechselkurse sauber gekapselt. Aktuell: 9 Plugins.

→ Alle Plugins im Katalog ansehen

Tools

Tools sind die eingebauten Werkzeuge, mit denen der Agent tatsächlich handelt: Dateisystem, Browser-Automatisierung, Git, HTTP, Shell und mehr — insgesamt 17 Tools. Welche Tools verfügbar sind, hängt im Cloud-Modus von deinem Tarif ab (Capability-Gating).

→ Alle Tools im Katalog ansehen

Memory

Über Memory merkt sich der Agent Kontext über einzelne Sessions hinaus — z. B. Vorlieben, Projektziele oder wiederkehrende Fakten. Jede Erinnerung ist eine kleine, beschriftete Notiz, die der Agent bei passender Gelegenheit wieder heranzieht.

Modelle & Provider

Die eigentlichen LLM-Aufrufe macht der Node-Agent serverseitig. Du kannst verschiedene Anbieter konfigurieren:

• Lokale Modelle: LM Studio oder Ollama auf deinem Rechner — nur im BYO-Modus, da localhost dort deinen eigenen Rechner meint.
• Cloud-Provider: z. B. OpenAI, OpenRouter oder Anthropic — funktionieren in beiden Modi.

Cloud vs. BYO

Hinweis: Das Cloud-Hosting ist noch in Vorbereitung — aktuell ist der Free-/BYO-Agent verfügbar. Details auf der Preisseite.

Von überall nutzen (HTTPS via Tailscale)

Willst du die gehostete Web-UI (https) mit deinem lokalen Agenten verbinden, blockt der Browser http://localhost als Mixed Content. Lösung: Mach den Agenten per Tailscale über HTTPS erreichbar.

API-Referenz

Der Fähigkeiten-Katalog steht auch als JSON zur Verfügung:

Fehlerbehebung

Der Agent läuft als versteckter Autostart-Dienst — Fehler siehst du dort nicht direkt. Zum Diagnostizieren startest du ihn einmal im Vordergrund und liest die Ausgabe. Unter Windows im Installationsordner:

cd "%LOCALAPPDATA%\ducki-agent\app"
pnpm --filter @ducki/server start > "%USERPROFILE%\Desktop\ducki-agent.log" 2>&1

Lass den Start ~30 Sekunden laufen. Springt das Fenster sofort zur Eingabe zurück, ist der Agent abgestürzt — die Ursache steht dann in ducki-agent.log (mit Strg+C beenden und die Datei öffnen). Erscheint dagegen Server started … http://127.0.0.1:3001, läuft er.

Häufige Ursachen

Weiterhin Probleme? Öffne ein Issue auf GitHub und hänge die letzten Zeilen aus ducki-agent.log an.

FAQ