Agentserver

Was ist PocketHook Agent Server?

#

Der Agentserver verwandelt PocketHook in einen vollständigen KI-Assistenten. Anstatt die Antwortlogik selbst zu schreiben, verbindest du ein LLM (Claude, GPT, Gemini usw.), das Nachrichten verarbeitet, Tools aufruft und strukturierte PocketHook-Antworten zurückgibt — einschließlich Shortcut-Auslöser.

Der Server läuft auf deinem eigenen Rechner. Deine Daten bleiben bei dir.

Dies ist ein Ausgangspunkt. Der Server wird mit einem Kernsatz an Tools ausgeliefert und ist darauf ausgelegt, von dir erweitert zu werden. Füge deine eigenen Integrationen hinzu — E-Mail, Kalender, Dokumente, APIs — und mach ihn zu deinem.

Funktionen

#

• Multi-Provider-LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• Schnelles Modell — Führe ein leichtgewichtiges Zweitmodell für interne Helfer (Speicherklassifizierung, Entitätsextraktion) parallel zu deinem Haupt-Chat-Modell aus — volle Kontrolle über Kosten und Latenz
• Safari-Erweiterung — Verbinde eine notarisierte macOS-Safari-Erweiterung, damit der Agent Tabs öffnen, Seiten inspizieren, klicken, Formulare ausfüllen und Screenshots in deiner echten Browsersitzung erfassen kann, mit dem Berechtigungslevel, das du wählst
• OAuth-Authentifizierung — GitHub Copilot und OpenAI Codex über Device-Code-/Browser-Flow
• Agenten-Tools — Shell-Befehle, Datei lesen/schreiben, Verzeichnislisting, Websuche, Web-Scraping, Dev-Server-Verwaltung
• Framework-/Benutzer-Trennung — Framework-Dateien (skills/, custom-tools/, config/) bleiben schreibgeschützt. Deine Anpassungen liegen unter data/user/ (Skills, Custom Tools, Anweisungen, typisierte Prefs). Framework-Updates landen sauber, ohne deine Arbeit zu überschreiben
• Typisierte Benutzer-Prefs — Speichere Werte wie deine bevorzugte Karten-App oder Tunnel-Domain in data/user/prefs.json. Referenziere sie in Skills als {{prefs.key}}, und der Server ersetzt sie beim Laden
• Programmieraufgaben in einem Aufruf — Das Meta-Tool run_code_job erstellt einen Hintergrundjob vom Typ Prompt (ausgeführt von deinem konfigurierten LLM) und sendet dem Benutzer die Bestätigung in einem einzigen Schritt — es ersetzt das fehleranfällige Muster “respond + create-job”
• Typisierte Protokoll-Tools — Sechs dedizierte respond_*-Tools (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), dazu typisierte Job-Tools (create_once_job, create_cron_job) und typisierte Workspace-Tools (create_project, list_projects, delete_project). Schemas weisen fehlerhafte URLs, Button-Syntax sowie type/schedule-Kombinationen ab, bevor sie das Gerät erreichen
• Typisierte Writer für Anpassungen — create_user_skill und create_custom_tool erzeugen das Markdown der Benutzerschicht mit korrektem Frontmatter, sodass der Loader es immer parst und der Agent diese Dateien nie von Hand schreibt
• Hintergrund-Jobs — Einmalige oder wiederkehrende Aufgaben mit Cron-Ausdrücken oder einfachen Intervallen
• Dynamische Skills — Definiere Shortcuts und Verhaltensregeln als .md-Dateien. Nur ein kompakter Index wird in den Prompt geladen; vollständiger Inhalt wird bei Bedarf über das load_skill-Tool abgerufen
• Selbstverwaltende Skills — Der Agent kann Skill-Definitionen erstellen, bearbeiten und löschen (Schreibvorgänge landen immer in der Benutzerschicht)
• Semantisches Gedächtnis — Vektorbasierte Suche mit Embeddings (Ollama, LM Studio oder OpenAI). Erinnerungen werden vom LLM automatisch in Wing/Room/Hall/Status-Dimensionen klassifiziert
• Wissensgraph — Temporaler Triple-Store für dauerhafte Fakten mit automatischer Invalidierung. Multi-Wert-Beziehungen koexistieren; Einzelwert-Fakten werden automatisch ersetzt
• PARA-Methode mit Projektabschluss-Kaskade — Jede Erinnerung wird mit einem Status versehen (Projekt, Bereich, Ressource, Archiv). Wenn ein Projekt endet, archiviert ein einziger complete_project-Aufruf seine Vektoren, invalidiert alle zum Slug passenden Planungs-Tripel und zeichnet den Abschluss auf — ein Aufruf statt drei
• Hybride Abfrage — Kombiniert FTS5-Stichwortsuche mit vektorbasierter semantischer Suche mittels Reciprocal-Rank-Fusion
• Langzeitgedächtnis — SQLite + FTS5-Volltextsuche als Fallback, wenn semantisches Gedächtnis deaktiviert ist
• Dev-Server-Verwaltung mit Tunnel-Vertrag — Starte, stoppe und liste Dev-Server. Wenn tunnel: true angefordert wird, setzt der Server dies vor dem Start und nach dem Spawn durch — ein unerreichbarer localhost-Server läuft nie stillschweigend weiter
• Automatische URL-Bereinigung — Wenn der Agent eine localhost-URL in einer Antwort stehen lässt, schreiben die respond_*-Tools sie auf die passende Tunnel-URL um, damit dein Telefon immer einen erreichbaren Link bekommt
• Benutzerdefinierte Tools — Der Agent kann CLI-Tools installieren und als neue Fähigkeiten registrieren
• Versionierung — Automatische Git-Versionierung für Workspace-Dateien; Konfigurations-Backups für Skills und Berechtigungen
• Web-Dashboard — Live-Übersicht über Hintergrund-Jobs, anpassbar pro Benutzer. /dashboard und /api/jobs sind absichtlich nicht authentifiziert — beschränke den Zugriff auf Netzwerkebene (Tailscale-ACL, Firewall, Reverse Proxy mit Basic Auth) oder setze DASHBOARD=false, wenn du es nicht brauchst
• HTTPS-Tunneling — Eingebaute Unterstützung für Tailscale, ngrok und Cloudflare Tunnel
• Systemdienst — Installation als persistenter Dienst unter macOS, Linux oder Windows
• Rate-Limiting — Pro-Token-Anfragelimits mit konfigurierbaren Schwellenwerten

Voraussetzungen

#

• Bun Runtime
• Ein API-Schlüssel oder OAuth-Anmeldedaten für deinen LLM-Anbieter
• (Optional) Tailscale, ngrok oder cloudflared für HTTPS-Tunneling

Schnellstart

#

git clone https://github.com/pockethook-app/pockethook-agent-server.git
cd pockethook-agent-server
bun install

# Interaktive Einrichtung — Anbieter, Modell, Auth-Token, Port waehlen
bun run setup

# Server + HTTPS-Tunnel starten
bun run dev:tunnel

Der Einrichtungsassistent führt dich durch die Auswahl eines LLM-Anbieters, die Konfiguration der Authentifizierung und die Einrichtung der Tool-Berechtigungen — einschließlich der Frage, ob die Safari-Erweiterung installiert werden soll (optional, überspringbar, nur macOS).

Führe jederzeit bun run help aus, um alle Befehle aufzulisten, oder bun run config, um deine aktuelle Konfiguration auf einen Blick zu sehen (Geheimnisse maskiert).

Sobald der Server läuft, kopiere die angezeigten URLs in die PocketHook-Einstellungen:

Funktionsweise

#

1. Du sendest eine Nachricht in PocketHook
2. Der Server leitet sie an dein gewähltes LLM weiter, zusammen mit Gesprächsverlauf, abgerufenen Erinnerungen und verfügbaren Tools
3. Das LLM verarbeitet die Nachricht — es kann Shell-Befehle ausführen, Dateien lesen/schreiben, im Web suchen, Hintergrund-Jobs planen, Fakten merken oder Dev-Server starten
4. Die Antwort wird im PocketHook-Format zurückgegeben (msg + shortcut + data + url)
5. PocketHook zeigt die Nachricht an und führt alle Shortcuts auf deinem Gerät aus

Unterstützte LLM-Anbieter

#

Wechsle jederzeit den Anbieter mit bun run switch. Ollama und LM Studio laufen vollständig auf deinem Rechner — kein API-Schlüssel nötig, keine Daten verlassen dein Netzwerk.

Gedächtnis

#

Das Gedächtnissystem hat drei Schichten, die jeweils einem anderen Zweck dienen.

Das Design des semantischen Gedächtnisses kombiniert Ideen von MemPalace (eine Gedächtnispalast-Architektur, die Erinnerungen in Wings, Halls und Rooms organisiert) und Tiago Fortes PARA-Methode (Projekte, Bereiche, Ressourcen, Archiv) für das Wissenslebenszyklus-Management.

Gesprächsgedächtnis

#

SQLite mit FTS5-Volltextsuche. Alle Nachrichten werden mit Zeitstempeln und Sitzungs-IDs gespeichert.

• Kurzzeit — Die letzten MAX_HISTORY Nachrichten werden pro Sitzung im Speicher gehalten
• Langzeit — Alle Nachrichten dauerhaft in SQLite gespeichert, durchsuchbar über FTS5-Stichwortsuche
• Abruf pro Turn — Wenn das semantische Gedächtnis aktiv ist, steuert MAX_RECALL, wie viele relevante Erinnerungen pro Turn in den Prompt eingespeist werden
• Sitzungen laufen nach SESSION_TTL_MINUTES ab, aber das Langzeitgedächtnis bleibt für immer bestehen

Stelle diese Werte interaktiv mit bun run memory ein.

Semantisches Gedächtnis

#

Erfordert VECTOR_MEMORY=true und einen Embedding-Anbieter (Ollama, LM Studio oder OpenAI).

Jede Erinnerung wird als Vektor eingebettet und vom LLM automatisch in vier Dimensionen klassifiziert:

• Wing — Die Entität: user, person:john, project:blog, place:london
• Room — Der Typ: facts, preferences, events, decisions, requests
• Hall — Das Thema: personal, tech, health, travel, food, work
• Status — PARA-Klassifikation: project, area, resource, archive

Wenn du eine Frage stellst, fokussiert die Entitätsextraktion die Vektorsuche auf die relevantesten Wings. Ergebnisse werden mit FTS5-Stichwort-Ergebnissen mittels Reciprocal-Rank-Fusion zusammengeführt — so bekommst du das Beste aus Stichwort- und semantischer Suche.

Wissensgraph

#

Ein temporaler Triple-Store für strukturierte, dauerhafte Fakten:

• Tripel: (Subjekt, Praedikat, Objekt) mit valid_from / valid_until Zeitstempeln
• Einzelwert-Prädikate (lives_in, partner) invalidieren automatisch den alten Wert bei Aktualisierung
• Mehrwert-Prädikate (child, friend, hobby) koexistieren ohne Invalidierung
• Wissensgraph-Fakten werden zusammen mit abgerufenen Erinnerungen in jedes Gespräch eingespeist

Wenn du dem Agenten sagst “Ich bin nach Berlin gezogen”, invalidiert er das alte lives_in-Tripel und erstellt ein neues — automatisch.

PARA-Lebenszyklus

#

Jede Erinnerung wird mit einem PARA-Status versehen:

• Projekt — Aktive, zeitgebundene Arbeit
• Bereich — Laufende Verantwortlichkeiten
• Ressource — Referenzmaterial (Listen, Empfehlungen, Anleitungen)
• Archiv — Abgeschlossene oder abgebrochene Projekte

Wenn ein Projekt abgeschlossen wird, verwendet der Agent semantische Ähnlichkeit, um nur die Erinnerungen dieses Projekts zu archivieren, während Referenzmaterial für zukünftige Nutzung erhalten bleibt.

Projektabschluss-Kaskade

#

Sag “Ich storniere meine Reise nach Barcelona”, und ein einziger Tool-Aufruf erledigt alles:

1. Archiviert die Vektoren des Projekts (Ereignisse, Entscheidungen, Anfragen, die mit Barcelona verbunden sind).
2. Invalidiert jedes aktive Wissensgraph-Tripel, dessen Prädikat zum Projekt-Slug passt (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Zeichnet den Abschluss als neues Tripel auf: (user, "cancelled_visit_barcelona", "2026-04-15").

Die Zuordnung erfolgt grenzensensitiv — ein anderes Projekt namens revisit_barcelona bleibt unberührt. Der Agent muss nicht mehr drei separate Aufrufe in der richtigen Reihenfolge orchestrieren, weshalb auch kleinere Modelle das zuverlässig hinbekommen.

Wenn VECTOR_MEMORY deaktiviert ist oder der Embedding-Anbieter nicht erreichbar ist, fällt das System fehlerfrei auf FTS5-only zurück.

Skills

#

Skills sind .md-Dateien in skills/, die iOS-Shortcuts definieren, die der Agent auslösen kann, und/oder Verhaltensregeln. Sie verwenden dynamisches Laden: Nur ein kompakter Index (Titel, Beschreibung, Shortcut-Liste) wird in den System-Prompt injiziert. Der Agent lädt den vollständigen Inhalt bei Bedarf über das load_skill-Tool, um den Token-Verbrauch niedrig zu halten, wenn du mehr Skills hinzufügst.

Jede Skill-Datei verwendet YAML-Frontmatter:

---
title: Notes
description: Create notes on the user's device with a title and body
shortcuts: [newNote]
target: mac
sync_app: Notes
---

### New Note

Shortcut name: `newNote`

Creates a new note on the user's device.

Data fields:
- title (string, required): Note title
- content (string, required): Note body

Frontmatter-Felder

#

Skills können auch Verhaltensregeln ohne Shortcuts sein (z. B. “wie man eine Familienreise plant”). Verwende shortcuts: [] dafür.

Der Agent kann Skills auf Anfrage erstellen und verwalten — bitte ihn “erstelle einen Skill zur Steuerung meiner Lampen” und er schreibt die .md-Datei für dich. Neue und bearbeitete Skills landen immer in deiner Benutzerschicht (data/user/skills/), sodass Framework-Updates sie niemals überschreiben. Siehe den Abschnitt Agent anpassen weiter unten.

Shortcuts auf dem Mac-Server ausführen

#

Wenn ein Skill target: mac hat, werden Shortcuts still auf dem Mac-Server über die shortcuts run-CLI ausgeführt, anstatt an das iOS-Gerät gesendet zu werden. Das ist ideal für Aktionen, die iCloud-synchronisierte Inhalte erzeugen — Notizen, Erinnerungen, Kalenderereignisse — weil das Ergebnis automatisch auf all deine Geräte synchronisiert wird, ohne dass die PocketHook-App etwas tun muss.

So funktioniert es:

1. Der Agent entscheidet, dass ein Shortcut ausgeführt werden soll (z. B. “erstelle eine Notiz mit den heutigen Besprechungsnotizen”)
2. Der Server ruft shortcuts run "shortcutName" mit den als JSON über stdin übergebenen Daten auf und verwendet dasselbe Wrapper-Format wie PocketHook iOS
3. Wenn sync_app gesetzt ist, öffnet der Server diese App kurz im Hintergrund (open -gj -a Notes), um iCloud-Sync zu erzwingen, und schließt sie nach 5 Sekunden wieder
4. Der Benutzer erhält eine Bestätigung im Chat; der Shortcut selbst wird nicht an das Gerät gesendet

Voraussetzungen:

• Der Server muss auf macOS laufen — shortcuts run ist nur unter macOS verfügbar. Auf anderen Plattformen protokolliert der Server eine Warnung und fällt auf Geräte-Ausführung zurück
• Der Shortcut muss in Shortcuts.app auf dem Server-Mac installiert sein
• Der Shortcut muss ein Dictionary als Eingabe erwarten (PocketHook verpackt Daten in { context, timestamp, app, data })

Wann target: mac verwenden:

• iCloud-synchronisierte Aktionen (Notizen, Erinnerungen, Kalender) — das Ergebnis erreicht ohnehin jedes Gerät
• Lang laufende Verarbeitungen, die du vom iOS-Gerät fernhalten willst
• Jeder Shortcut, der nicht mit der iPhone-Oberfläche interagieren muss

Wann target: device (Standard) beibehalten:

• Shortcuts, die iPhone-spezifische Funktionen benötigen (Kamera, genauer Standort, lokale App-Automatisierungen)
• Shortcuts, die eine interaktive Benutzereingabe verlangen
• Shortcuts, die App Intents aus iOS-exklusiven Apps verwenden

Hintergrund-Jobs

#

Bitte den Agenten, Aufgaben zu planen, und er erledigt den Rest:

• “Prüfe jeden Morgen um 8 Uhr das Wetter und erstelle eine Notiz”
• “Führe dieses Skript jede Stunde aus”
• “Erinnere mich in 30 Minuten, meine E-Mails zu prüfen”

Jobs unterstützen Cron-Ausdrücke (0 8 * * *) und einfache Intervalle (30m, 1h, 2d). Ergebnisse werden an PocketHook geliefert, wenn es den /jobs-Endpunkt abfragt.

Zwei Ausführungstypen:

• Shell — Führt einen Bash-Befehl aus, erfasst die Ausgabe. Kann bei Abschluss einen Shortcut auslösen
• Prompt — Wird vom KI-Agenten mit vollem Tool-Zugriff verarbeitet, speichert die vollständige PocketHook-Antwort

Dev-Server

#

Wenn der Agent ein Webprojekt im Workspace erstellt (Hugo, Astro, Next.js, Flask, Go usw.), bietet er proaktiv an, es bereitzustellen:

• Vorschau — Startet einen lokalen Dev-Server auf einem automatisch zugewiesenen Port zur schnellen Ansicht
• Öffentlich — Startet den Server und macht ihn über einen HTTPS-Tunnel von überall zugänglich

Der Agent verwaltet den Lebenszyklus: Starten, Stoppen und Auflisten laufender Server. Alle Server werden bereinigt, wenn der Hauptserver gestoppt wird.

Tunnel-Vertrag

#

Wenn der Agent einen Server mit angeforderter Tunnel-Freigabe startet, setzt die Laufzeit diese durch: Ist kein Tunnel-Tool (Tailscale, ngrok, cloudflared) installiert, verweigert der Server den Start. Schlägt die Tunnel-Einrichtung nach dem Spawn fehl, wird der verwaiste Prozess gestoppt und der Agent wird ausdrücklich informiert — so kann er auf den Vorschaumodus zurückfallen oder dich bitten, einen Tunnel zu installieren. Die zurückgegebene URL ist immer die Tunnel-URL, wenn Tunneling aktiv ist, mit dem Hinweis, dass die lokale URL nur für den Host gilt.

Als Sicherheitsnetz nachbearbeitet jedes respond_*-Tool seine Nachricht: Jede localhost- oder 127.0.0.1-URL, die sich in eine Antwort schleicht, wird automatisch auf die passende Tunnel-URL umgeschrieben, sofern ein verwalteter Server eine hat. Kann nicht umgeschrieben werden, bekommst du eine Warnung in den Logs statt eines defekten Links auf deinem Telefon.

Dashboard

#

Das eingebaute Web-Dashboard unter /dashboard zeigt eine Live-Übersicht der Hintergrund-Jobs.

Absichtlich nicht authentifiziert. Sowohl /dashboard als auch /api/jobs sind offene GET-Endpunkte — wer den Host erreichen kann, kann Jobs auflisten. Beschränke den Zugriff auf Netzwerkebene (Tailscale-ACL, Firewall, Reverse Proxy mit Basic Auth) oder setze DASHBOARD=false, wenn du es nicht brauchst. Die PocketHook-iOS-App nutzt diese Endpunkte nicht.

Es ist vollständig anpassbar:

• Schnellbearbeitung — Platziere eine dashboard.html in workspace/dashboard/ für einfache Anpassungen
• Volles Projekt — Erstelle ein Framework-Projekt (Svelte, React, Vue usw.) in workspace/dashboard/ mit Build-Ausgabe nach dist/

Bitte den Agenten, dein Dashboard anzupassen, und er erledigt den Rest — jeder Benutzer bekommt ein einzigartiges, personalisiertes Dashboard.

Benutzerdefinierte Tools

#

Der Agent kann CLI-Tools installieren und sie als neue Fähigkeiten registrieren — er erweitert sich selbst, ohne den Servercode zu ändern.

Sage zum Beispiel “installiere Playwright und benutze es, um Screenshots zu machen”. Der Agent wird:

1. Die Abhängigkeit installieren
2. Eine Tool-Definition erstellen (eine einfache .md-Datei)
3. Das neue Tool in zukünftigen Gesprächen verwenden

Benutzerdefinierte Tools werden sofort nachgeladen — kein Neustart nötig. Lösche die .md-Datei, um ein Tool zu entfernen.

Versionierung

#

Alle Benutzerdaten werden automatisch versioniert:

• Workspace-Dateien — Werden mit einem lokalen Git-Repo innerhalb von workspace/ verfolgt. Jeder Schreibvorgang erstellt einen Auto-Commit. Bitte den Agenten “mache die letzte Änderung rückgängig” oder verwende git revert HEAD manuell
• Konfigurationsdateien — config/agent-instructions.md, config/personality.md, skills/ und permissions.json werden vor jeder Änderung gesichert. Bis zu 20 Versionen pro Datei

Git ist optional — wenn nicht installiert, sind Workspace-Änderungen nicht versioniert. Konfigurations-Backups funktionieren immer.

Agent anpassen

#

Der Agentserver kommt mit einer minimalen Framework-Basis und erwartet, dass du deine eigenen Anpassungen darüber legst. Die Laufzeit hält beides getrennt, damit Framework-Updates deine Arbeit nie überschreiben.

Framework vs. Benutzer

#

pockethook-agent-server/
├── skills/                      # vom Framework ausgelieferte Skills (schreibgeschuetzt)
├── custom-tools/                # reserviert fuer vom Framework ausgelieferte Tools (schreibgeschuetzt)
├── config/
│   ├── agent-instructions.md    # Framework-Agentenanweisungen (schreibgeschuetzt)
│   └── personality.md           # Framework-Persoenlichkeit (schreibgeschuetzt)
└── data/user/                   # DEINE Anpassung liegt hier (von git ignoriert)
    ├── skills/                  # deine eigenen Skills (ueberschreiben Basis nach Dateiname)
    ├── custom-tools/            # deine installierten Custom Tools
    ├── instructions.md          # deine Ergaenzungen zu den Agentenanweisungen
    └── prefs.json               # typisierte Werte, referenziert als {{prefs.key}}

Benutzeranpassungen werden über dedizierte typisierte Tools (create_user_skill, create_custom_tool) geschrieben, sodass die resultierenden Dateien immer dem Format des Loaders entsprechen. Das write-Tool weist außerdem jeden Pfad unter skills/, custom-tools/ oder config/ ab und leitet den Agenten nach data/user/* um — selbst direkte Datei-Edits landen so in der Benutzerschicht.

Hinweis zum Basis-Verzeichnis custom-tools/. Aktuell enthält es nur eine Vorlage (_example.md), die der Loader ignoriert — jedes Tool, das der Agent für dich installiert, landet in data/user/custom-tools/. Das Verzeichnis ist reserviert, damit zukünftige Framework-Releases optionale eingebaute Tools ausliefern können, ohne deine Installationen zu überschreiben. Wenn das passiert, gewinnen deine Dateien aus der Benutzerschicht weiterhin bei Namenskollisionen, sodass nichts zu migrieren ist.

Vier Wege zur Anpassung

#

Du musst diese Dateien nie von Hand schreiben. Sag dem Agenten einfach, was du willst, und er wählt die richtige Schicht automatisch.

Typisierte Präferenzen mit {{prefs.*}}

#

Angenommen, du schreibst einen Routenplaner-Skill, der deinen Standard-Startpunkt kennen muss. Statt “Madrid” im Skill hart zu verdrahten, referenziere die Pref:

- **Startpunkt**: {{prefs.routeOrigin}}, sofern der Benutzer keinen anderen Ursprung angibt.

Und speichere den Wert in data/user/prefs.json:

{
  "routeOrigin": "Madrid, Spanien",
  "preferredMapsApp": "apple",
  "tunnel": { "domain": "my-host.ts.net" }
}

Der Server ersetzt Platzhalter beim Laden des Skills. Verschachtelte Schlüssel ({{prefs.tunnel.domain}}) funktionieren ebenfalls. Unbekannte Schlüssel bleiben unverändert, damit Tippfehler sichtbar bleiben.

Die Framework-Basis direkt bearbeiten

#

Wenn du selbst hostest und das Framework selbst anpassen willst, kannst du config/agent-instructions.md, config/personality.md, skills/ oder custom-tools/ direkt bearbeiten — der Server hält dich nicht davon ab, wenn du einen Dateieditor verwendest. Aber der Agent schreibt aus einem Gespräch heraus nicht in diese Pfade. Und Framework-Updates werden deine Änderungen überschreiben. Bevorzuge die Benutzerschicht für alles, was du behalten willst.

Server erweitern

#

• Benutzerdefinierte Tools — Bitte den Agenten, CLI-Tools zu installieren; sie landen automatisch in data/user/custom-tools/
• Skills hinzufügen — Bitte den Agenten, einen Skill zu erstellen; die Datei landet in data/user/skills/
• Verhalten ändern — Bitte den Agenten, eine globale Regel anzuwenden; sie wird an data/user/instructions.md angehängt
• Berechtigungen konfigurieren — Führe bun run permissions aus, um zu steuern, welche Tools der Agent nutzen darf
• Eingebaute Tools hinzufügen — Implementiere neue Tool-Funktionen in src/tools.ts für tiefere Integrationen (erfordert Forken des Servers)

Konfiguration

#

Alle Einstellungen werden in .env gespeichert (erstellt durch bun run setup). Wichtige Optionen:

Die vollständige Konfigurationsreferenz findest du im GitHub-Repository.

Als Dienst ausführen

#

Installation als persistenter Dienst, der automatisch startet:

bun run service install

INSTANCE_NAME ist standardmäßig der Basisname des Projektverzeichnisses ohne das pockethook--Präfix (z. B. wird ein Checkout in pockethook-agent-server/ zu agent-server). Setze ihn explizit, um mehrere Checkouts auf demselben Rechner ohne Kollisionen zu betreiben — jede Instanz behält ihr eigenes data/ und ihre eigenen Logs.

Verwalte mit bun run service status, restart, stop oder uninstall.

Sicherheit

#

• HTTPS erforderlich — PocketHook erzwingt HTTPS für alle URLs
• Bearer-Token-Authentifizierung — Gemeinsames Geheimnis zwischen App und Server
• Rate-Limiting — Pro-Token-Limits verhindern Missbrauch
• Sandboxed Tools — Shell-Befehle und Dateizugriff durch Berechtigungen eingeschränkt
• Blockierte Muster — Gefährliche Befehle (sudo, rm -rf /) standardmäßig blockiert
• Arbeitsverzeichnis-Grenze — Agent kann sein zugewiesenes Verzeichnis nicht verlassen
• Sensible Dateien geschützt — .env, .git, *.key, *.pem vor Agentenzugriff blockiert
• Automatische Versionierung — Alle Workspace-Änderungen werden per Git verfolgt für einfaches Zurückrollen