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.paperclip.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

Es gibt zwei Arten von .env-Dateien:

Datei	Inhalt	Gilt für
services/shared.env(.age)	API Keys (OpenRouter, Mistral, etc.)	Alle Services
services/<name>/.env(.age)	Service-spezifische Secrets (DB-Passwort, Auth-Secret)	Nur dieser Service

Da .env-Dateien per .gitignore ausgeschlossen sind, wird stattdessen jeweils die .age-Variante ins Repository gepusht. Nach Änderungen neu verschlüsseln:

# Geteilte API Keys (alle Services)
age -r <AGE_PUBLIC_KEY> -o services/shared.env.age services/shared.env

# Service-spezifisch (z. B. PaperClip)
age -r <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.paperclip.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