CT 118 – PaperclipAI

Basisdaten

Was ist PaperclipAI?

PaperclipAI ist eine Agentenorchestrierung – du erstellst virtuelle Unternehmen mit KI-Agenten (hier: Claude Code), die eigenständig Code schreiben, Bugs fixen, Tasks ausführen und dabei ein Monatsbudget einhalten.

Kernkonzepte:

Einrichtung – Schritt für Schritt

1. Dashboard öffnen

Öffne https://agent.ls-cloud.biz im Browser.

Login mit Caddy-Credentials → danach erscheint das PaperclipAI-Dashboard.

2. Ersten Account anlegen (Bootstrap)

Falls noch kein Account existiert:

1. https://agent.ls-cloud.biz aufrufen
2. "Create Account" oder Bootstrap-Formular ausfüllen
3. E-Mail + Passwort festlegen
4. Du bist jetzt Admin

[!TIP] Nach dem ersten Account empfiehlt es sich, in den Einstellungen die freie Registrierung zu deaktivieren – sonst kann sich jeder mit dem Caddy-Passwort auch einen PaperclipAI-Account anlegen.

3. Company erstellen

Eine Company ist der Arbeitsraum. Jedes Projekt / jeder Themenkomplex kann eine eigene Company sein.

1. Im Dashboard auf "New Company" klicken
2. Name vergeben (z.B. Homelab Automation)
3. Optional: Beschreibung
4. "Create" → Company ist angelegt

Du landest automatisch im Company-Dashboard.

4. Agent hinzufügen

Ein Agent ist die Verbindung zu Claude Code (dem eigentlichen KI-Worker).

1. In der Company auf "Agents" → "Add Agent"
2. Name vergeben (z.B. claude-engineer)
3. Adapter wählen: claude_local
4. Monatliches Budget setzen (z.B. $10.00) – schützt vor unkontrollierten Kosten
5. Optional: Working Directory – Verzeichnis in dem Claude Code arbeitet
6. "Save" → Agent ist registriert

[!WARNING] Ohne Budget-Limit läuft der Agent unbegrenzt. Für Homelab-Nutzung reichen \(5–\)20/Monat je nach Nutzungsintensität.

5. Ersten Job erstellen (Agent beauftragen)

Jobs sind die eigentlichen Aufgaben, die du dem Agenten gibst.

1. Im Company-Dashboard auf "New Job" klicken

2. Agent auswählen (den gerade angelegten)

3. Prompt eingeben – so präzise wie möglich, z.B.:

   Analysiere das Verzeichnis /opt/myapp und finde alle Stellen wo 
   SQL-Queries direkt aus User-Input gebaut werden. Liste die Dateien 
   und Zeilennummern auf und erkläre das Risiko.
   

4. Optional: Kontext-Dateien anhängen

5. "Start Job" → Agent beginnt die Arbeit

Der Job erscheint in der Job-Liste mit Status running. Du siehst in Echtzeit die Ausgabe des Agenten.

6. Job-Ausgabe lesen

Während und nach dem Job:

• Live-Output: Claude Codes Nachrichten erscheinen in Echtzeit im Job-Detail
• Tool-Calls: Jede Datei die gelesen/geschrieben wird, jeder Bash-Befehl – alles sichtbar
• Status: running → completed / failed
• Kosten: Werden nach Abschluss gegen das Budget gebucht

7. Mehrere Agenten & Arbeitsteilung

Du kannst mehrere Agenten in einer Company anlegen und ihnen verschiedene Rollen geben:

Jeder Agent hat sein eigenes Budget. So lässt sich Kosten pro Bereich tracken.

8. Plugins & Integrationen

Unter Settings → Plugins kannst du Erweiterungen aktivieren:

• GitHub: Agent öffnet automatisch PRs für seine Änderungen
• Jira / Linear: Tasks aus Ticketsystem als Job-Quelle
• Webhook: Externe Trigger für Jobs (z.B. aus CI/CD Pipeline)

Plugins werden pro Agent oder global aktiviert.

Tägliche Nutzung

Neuen Job starten

Company → "New Job" → Agent wählen → Prompt schreiben → "Start"

Job-Status prüfen

Company → "Jobs" → Job anklicken → Live-Output + Kostenübersicht

Budget-Verbrauch prüfen

Company → "Agents" → Agent anklicken → Budget-Chart (verbraucht / verbleibend)

Agent temporär pausieren

Agents → Agent → "Disable" → Agent nimmt keine neuen Jobs an

Überwachung & Wartung

Service-Status

ssh root@192.168.178.88
systemctl status paperclipai

Logs

# Systemd-Journal
journalctl -u paperclipai -f

# PaperclipAI eigene Logs
tail -f /home/paperclip/.paperclip/instances/default/logs/*.log

Neustart

systemctl restart paperclipai

Claude OAuth-Token erneuern (falls abgelaufen)

ssh root@192.168.178.88
su - paperclip
claude logout
claude login
# URL kopieren → im Browser öffnen → Pro-Account einloggen

Danach Credentials wieder für den paperclip User verfügbar machen:

cp /root/.claude/.credentials.json /home/paperclip/.claude/.credentials.json
chown paperclip:paperclip /home/paperclip/.claude/.credentials.json
systemctl restart paperclipai

PaperclipAI updaten

ssh root@192.168.178.88
su - paperclip
npm install -g paperclipai@latest
systemctl restart paperclipai

Architektur im Überblick

Browser
  └── https://agent.ls-cloud.biz
        └── Caddy (Proxmox Host, basic_auth)
              └── nginx CT 118 :3101
                    └── PaperclipAI :3100 (127.0.0.1, User: paperclip)
                          └── embedded PostgreSQL :54329
                          └── claude_local Adapter
                                └── Claude Code (/usr/bin/claude)
                                      └── OAuth → Claude Pro Plan

Wichtige Pfade

Schnellcheck

# Container läuft?
ssh root@192.168.178.46 "pct status 118"

# Service läuft?
ssh root@192.168.178.88 "systemctl status paperclipai --no-pager | head -5"

# API erreichbar?
curl -s http://192.168.178.88:3101/api/health | python3 -m json.tool

# HTTPS mit Auth?
curl -sk -u 'xclusive:PASSWORT' https://agent.ls-cloud.biz/api/health