Ct-118-Paperclipai - blame None

Blame

546dd5	Wiki	2026-04-08 20:55:40
Add CT 118 PaperclipAI article

# CT 118 – PaperclipAI

> [!NOTE]

> CT 118 hostet **PaperclipAI** – eine Open-Source Multi-Agent-Orchestrierungsplattform, die KI-Agenten (Claude Code) als autonome "Mitarbeiter" in virtuellen Unternehmen koordiniert. Zugriff über `https://agent.ls-cloud.biz` (Login erforderlich).

## Basisdaten

| Eigenschaft | Wert |

|---|---|

| **CT-ID** | `118` |

| **Name** | `paperclipai` |

| **IP** | `192.168.178.88` |

| **OS** | Debian 12 (Bookworm) |

| **RAM** | 2048 MB |

| **Disk** | 20 GB |

| **Web-UI (intern)** | `http://192.168.178.88:3101` |

| **Web-UI (extern)** | `https://agent.ls-cloud.biz` |

| **Service** | `paperclipai.service` (User: `paperclip`) |

| **Node.js** | v20.20.2 |

| **PaperclipAI** | v2026.403.0 |

| **Claude Code** | v2.1.96 |

| **Auth** | Caddy basic_auth + PaperclipAI-eigene Accounts |

---

## 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:**

| Begriff | Bedeutung |

|---|---|

| **Company** | Virtuelles Unternehmen – Container für Agenten und Projekte |

| **Agent** | KI-Worker (hier Claude Code) – führt Tasks autonom aus |

| **Job** | Einzelner Auftrag / Prompt, den ein Agent bearbeitet |

| **Budget** | Monatliches Kostenlimit pro Agent (verhindert Kontrollverlust) |

| **Plugin** | Erweiterung für Agenten (z.B. GitHub, Jira-Integration) |

---

## Einrichtung – Schritt für Schritt

### 1. Dashboard öffnen

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

> [!NOTE]

> Beim ersten Aufruf nach Installation erscheint ein **Bootstrap-Wizard** um den ersten Admin-Account anzulegen. E-Mail + Passwort eingeben → Account wird erstellt.

---

### 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)

100

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

101

102

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

103

2. **Agent auswählen** (den gerade angelegten)

104

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

105

106

```

107

Analysiere das Verzeichnis /opt/myapp und finde alle Stellen wo

108

SQL-Queries direkt aus User-Input gebaut werden. Liste die Dateien

109

und Zeilennummern auf und erkläre das Risiko.

110

```

111

112

4. Optional: **Kontext-Dateien** anhängen

113

5. **"Start Job"** → Agent beginnt die Arbeit

114

115

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

116

117

---

118

119

### 6. Job-Ausgabe lesen

120

121

Während und nach dem Job:

122

123

- **Live-Output**: Claude Codes Nachrichten erscheinen in Echtzeit im Job-Detail

124

- **Tool-Calls**: Jede Datei die gelesen/geschrieben wird, jeder Bash-Befehl – alles sichtbar

125

- **Status**: `running` → `completed` / `failed`

126

- **Kosten**: Werden nach Abschluss gegen das Budget gebucht

127

128

---

129

130

### 7. Mehrere Agenten & Arbeitsteilung

131

132

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

133

134

| Agent-Name | Working Dir | Aufgabe |

135

|---|---|---|

136

| `frontend-dev` | `/opt/webapp/frontend` | React/CSS Änderungen |

137

| `backend-dev` | `/opt/webapp/api` | API-Entwicklung |

138

| `devops` | `/opt/infra` | Server/Config-Verwaltung |

139

140

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

141

142

---

143

144

### 8. Plugins & Integrationen

145

146

Unter **Settings → Plugins** kannst du Erweiterungen aktivieren:

147

148

- **GitHub**: Agent öffnet automatisch PRs für seine Änderungen

149

- **Jira / Linear**: Tasks aus Ticketsystem als Job-Quelle

150

- **Webhook**: Externe Trigger für Jobs (z.B. aus CI/CD Pipeline)

151

152

Plugins werden pro Agent oder global aktiviert.

153

154

---

155

156

## Tägliche Nutzung

157

158

### Neuen Job starten

159

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

160

161

### Job-Status prüfen

162

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

163

164

### Budget-Verbrauch prüfen

165

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

166

167

### Agent temporär pausieren

168

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

169

170

---

171

172

## Überwachung & Wartung

173

174

### Service-Status

175

176

```bash

177

ssh root@192.168.178.88

178

systemctl status paperclipai

179

```

180

181

### Logs

182

183

```bash

184

# Systemd-Journal

185

journalctl -u paperclipai -f

186

187

# PaperclipAI eigene Logs

188

tail -f /home/paperclip/.paperclip/instances/default/logs/*.log

189

```

190

191

### Neustart

192

193

```bash

194

systemctl restart paperclipai

195

```

196

197

### Claude OAuth-Token erneuern (falls abgelaufen)

198

199

```bash

200

ssh root@192.168.178.88

201

su - paperclip

202

claude logout

203

claude login

204

# URL kopieren → im Browser öffnen → Pro-Account einloggen

205

```

206

207

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

208

```bash

209

cp /root/.claude/.credentials.json /home/paperclip/.claude/.credentials.json

210

chown paperclip:paperclip /home/paperclip/.claude/.credentials.json

211

systemctl restart paperclipai

212

```

213

214

### PaperclipAI updaten

215

216

```bash

217

ssh root@192.168.178.88

218

su - paperclip

219

npm install -g paperclipai@latest

220

systemctl restart paperclipai

221

```

222

223

---

224

225

## Architektur im Überblick

226

227

```

228

Browser

229

└── https://agent.ls-cloud.biz

230

└── Caddy (Proxmox Host, basic_auth)

231

└── nginx CT 118 :3101

232

└── PaperclipAI :3100 (127.0.0.1, User: paperclip)

233

└── embedded PostgreSQL :54329

234

└── claude_local Adapter

235

└── Claude Code (/usr/bin/claude)

236

└── OAuth → Claude Pro Plan

237

```

238

239

---

240

241

## Wichtige Pfade

242

243

| Pfad | Inhalt |

244

|---|---|

245

| `/home/paperclip/.paperclip/instances/default/config.json` | Hauptkonfiguration |

246

| `/home/paperclip/.paperclip/instances/default/db/` | PostgreSQL Daten |

247

| `/home/paperclip/.paperclip/instances/default/logs/` | Logs |

248

| `/home/paperclip/.paperclip/instances/default/data/backups/` | Automatische DB-Backups |

249

| `/home/paperclip/.claude/.credentials.json` | Claude OAuth-Token |

250

| `/etc/systemd/system/paperclipai.service` | Systemd Service |

251

| `/etc/nginx/sites-enabled/paperclipai` | nginx Proxy-Config |

252

253

---

254

255

## Schnellcheck

256

257

```bash

258

# Container läuft?

259

ssh root@192.168.178.46 "pct status 118"

260

261

# Service läuft?

262

ssh root@192.168.178.88 "systemctl status paperclipai --no-pager | head -5"

263

264

# API erreichbar?

265

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

266

267

# HTTPS mit Auth?

268

curl -sk -u 'xclusive:PASSWORT' https://agent.ls-cloud.biz/api/health

269

```

270

271

---

272

273

> [!TIP]

274

> Claude Code arbeitet im **Home-Verzeichnis des paperclip-Users** (`/home/paperclip`), sofern kein Working Directory im Agent gesetzt ist. Für produktive Nutzung immer ein konkretes Projektverzeichnis als Working Directory angeben.

275

276

> [!WARNING]

277

> PaperclipAI läuft im Modus `local_trusted` – das bedeutet die App vertraut allen Requests die über localhost kommen **ohne zusätzliche Token-Prüfung**. Deshalb ist der Caddy `basic_auth` davor zwingend notwendig und darf nicht entfernt werden.