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
• API Gateway: https://hermes.paperclip.orfel.de (Port 8642 via Caddy HTTPS)
• Web-Dashboard: https://hermes-ui.paperclip.orfel.de (Port 9119 via Caddy HTTPS)
• Daten: /opt/PaperClip-Data/hermes/ auf dem Host

Hermes in PaperClip einbinden

Das Setup-Unterskript services/hermes/setup_hermes.sh wird automatisch beim Deployment ausgeführt und richtet die hermes CLI vollständig im PaperClip-Container ein (pip install hermes-agent).

In PaperClip kann Hermes auf zwei Arten eingestellt werden:

1. hermes_local (Standard & empfohlen):

   • Im PaperClip-Dashboard → "Hire Agent"
   • Adapter: hermes_local
   • PaperClip ruft die CLI hermes direkt im Container auf. API Keys werden automatisch aus services/shared.env bereitgestellt.

2. hermes_gateway (Standalone):

   • Adapter: Hermes Gateway
   • Gateway-URL: http://hermes:8642 (intern) oder https://hermes.paperclip.orfel.de

Manuelles Setup

Falls Hermes manuell neu eingerichtet werden soll:

sudo bash /opt/PaperClip/services/hermes/setup_hermes.sh

Weitere Adapter einbinden

1. OpenCode

PaperClip unterstützt OpenCode nativ mit OpenAI-kompatiblen Endpunkten. In services/paperclip/docker-compose.yml ist OpenRouter bereits vorkonfiguriert:

1. Im PaperClip-Dashboard → "Hire Agent"
2. Adapter wählen: OpenCode
3. Model eintragen, z. B.:
   • openrouter/anthropic/claude-sonnet-4-5
   • openrouter/deepseek/deepseek-r1
   • openrouter/google/gemini-2.5-pro
   • openrouter/openai/gpt-4o

2. Gemini CLI

Der GEMINI_API_KEY ist in services/shared.env hinterlegt und wird automatisch in den PaperClip-Container geladen:

1. Im PaperClip-Dashboard → "Hire Agent"
2. Adapter wählen: Gemini CLI
3. Modell / Parameter konfigurieren und Agent starten.

Umgebungsvariablen ändern & verschlüsseln

Alle geteilten Keys liegen in services/shared.env. Nach Änderungen neu verschlüsseln:

age -r age1sa3q5qxl5dylld7v839m9lkv5h7l457wq4h40pt7kfmcfhcqkfjqspdjpn -o services/shared.env.age services/shared.env