PaperClip/README.md

PaperClip

PaperClip ist eine Plattform zur Orchestrierung von KI-Agenten, die über Docker und Caddy betrieben wird.

Dieses Repository enthält die Infrastruktur, um PaperClip inklusive Caddy (Reverse-Proxy) und einer Postgres-Datenbank auf einem neuen Server auszurollen.

Architektur

• Reverse Proxy: Caddy
• Datenbank: Postgres 17
• Anwendung: PaperClip (via ghcr.io/paperclipai/paperclip:latest)
• Agent-Runtime: Hermes Agent (via nousresearch/hermes-agent:latest) — Dashboard: hermes.orfel.de

Alle Volumes werden als lokale Mounts unter /opt/PaperClip-Data/ auf dem Host abgelegt.

Installation & Deployment

Um das System auf einem neuen Server (z. B. Hetzner CX23) aufzusetzen, klone das Repository nach /opt/PaperClip und führe das Master-Deployment-Skript als root aus.

# Repository klonen
sudo mkdir -p /opt/PaperClip
sudo git clone https://git.orfel.de/Jannik/PaperClip.git /opt/PaperClip

# Setup & Deploy
sudo bash /opt/PaperClip/deploy_script.sh

Das Skript ist idempotent und kümmert sich um:

• Die Installation von Docker, age und fail2ban.
• Das Einrichten des Swaps und der Cronjobs (für automatische Updates).
• Das Entschlüsseln der .env-Dateien mit age.
• Das Starten von Caddy, Postgres und PaperClip.

Umgebungsvariablen hinzufügen oder ändern

Die Umgebungsvariablen liegen lokal unter services/paperclip/.env. Da dieses File per .gitignore ausgeschlossen ist (aus Sicherheitsgründen), wird stattdessen .env.age in das Repository gepusht.

Sobald du Änderungen an deiner lokalen .env machst, musst du diese neu verschlüsseln, bevor du den Commit erstellst:

age -r <DEIN_AGE_PUBLIC_KEY> -o services/paperclip/.env.age services/paperclip/.env

LLM Konfiguration & Onboarding Workaround

Paperclip ist in seiner Benutzeroberfläche bei der Erstinstallation stark auf offizielle OpenAI- oder Anthropic (Claude)-Accounts fokussiert. Wenn du stattdessen alternative Provider wie OpenRouter oder Mistral nutzen möchtest, greift ein Workaround im Deployment-Prozess:

1. API Keys in der .env hinterlegen: Trage deine gewünschten API-Keys in die services/paperclip/.env ein (z. B. OPENROUTER_API_KEY=sk-or-v1-...).

2. Automatischer Patch durch das Deploy-Skript: Das deploy_script.sh erkennt automatisch, wenn ein OPENROUTER_API_KEY (oder MISTRAL_API_KEY) vorhanden ist, aber kein nativer OpenAI/Claude-Key. Es führt dann folgende Schritte aus:

   • Setzt OPENAI_API_KEY auf deinen OpenRouter/Mistral-Key.
   • Setzt OPENAI_BASE_URL auf die entsprechende API-URL (z. B. https://openrouter.ai/api/v1).
   • WICHTIG: Das Skript patcht den Paperclip-Container (die Datei ai-connections.js) direkt nach dem Start. Dadurch wird sichergestellt, dass die strenge UI-Validierung beim Onboarding deine alternative URL (OPENAI_BASE_URL) verwendet und nicht hartcodiert bei OpenAI anfragt.

3. Das Onboarding in der UI abschließen:

   • Sobald du deinen CEO-Account über den Invite-Link erstellst, landest du im Schritt "Connect a model".
   • Klicke hier auf die Schaltfläche OpenAI (API).
   • Füge exakt deinen OpenRouter- oder Mistral-Key in das Textfeld ein und klicke auf "Connect".
   • Paperclip testet den Key nun erfolgreich gegen deinen Provider und lässt dich ins Dashboard!

Hermes Agent

Hermes Agent ist ein Open-Source-KI-Agent von Nous Research, der als eigenständiger Docker-Service läuft und von PaperClip als "Mitarbeiter" eingestellt werden kann.

Architektur

• Container: hermes (Image: nousresearch/hermes-agent:latest)
• Netz: Im selben paperclip-net — PaperClip erreicht Hermes intern über http://hermes:8642
• Web-Dashboard: https://hermes.orfel.de (Port 9119)
• Daten: /opt/PaperClip-Data/hermes/ auf dem Host

Hermes in PaperClip einbinden

Nachdem der Service gestartet ist, kann PaperClip Hermes als Agenten einstellen:

1. Im PaperClip-Dashboard → "Hire Agent"
2. Adapter wählen: hermes_gateway
3. Gateway-URL eintragen: http://hermes:8642
4. Hermes-Agent konfigurieren und Tasks zuweisen

Umgebungsvariablen ändern

Die .env für Hermes liegt unter services/hermes/.env (nicht committed). Nach Änderungen neu verschlüsseln:

age -r <DEIN_AGE_PUBLIC_KEY> -o services/hermes/.env.age services/hermes/.env