Agentserver

Was ist PocketHook Agent Server?

#

Der Agentserver verwandelt PocketHook in einen vollstaendigen 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 zurueckgibt — einschliesslich Shortcut-Ausloeser.

Der Server laeuft 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. Fuege 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)
• OAuth-Authentifizierung — GitHub Copilot und OpenAI Codex ueber 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 schreibgeschuetzt. Deine Anpassungen liegen unter data/user/ (Skills, Custom Tools, Anweisungen, typisierte Prefs). Framework-Updates landen sauber, ohne deine Arbeit zu ueberschreiben
• 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 (ausgefuehrt von deinem konfigurierten LLM) und sendet dem Benutzer die Bestaetigung in einem einzigen Schritt — es ersetzt das fehleranfaellige 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 Geraet erreichen
• Typisierte Writer fuer 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-Ausdruecken oder einfachen Intervallen
• Dynamische Skills — Definiere Shortcuts und Verhaltensregeln als .md-Dateien. Nur ein kompakter Index wird in den Prompt geladen; vollstaendiger Inhalt wird bei Bedarf ueber das load_skill-Tool abgerufen
• Selbstverwaltende Skills — Der Agent kann Skill-Definitionen erstellen, bearbeiten und loeschen (Schreibvorgaenge landen immer in der Benutzerschicht)
• Semantisches Gedaechtnis — 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 fuer 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
• Langzeitgedaechtnis — SQLite + FTS5-Volltextsuche als Fallback, wenn semantisches Gedaechtnis 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 laeuft nie stillschweigend weiter
• Automatische URL-Bereinigung — Wenn der Agent eine localhost-URL in einer Antwort stehen laesst, 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 Faehigkeiten registrieren
• Versionierung — Automatische Git-Versionierung fuer Workspace-Dateien; Konfigurations-Backups fuer Skills und Berechtigungen
• Web-Dashboard — Live-Uebersicht ueber Hintergrund-Jobs, anpassbar pro Benutzer. /dashboard und /api/jobs sind absichtlich nicht authentifiziert — beschraenke den Zugriff auf Netzwerkebene (Tailscale-ACL, Firewall, Reverse Proxy mit Basic Auth) oder setze DASHBOARD=false, wenn du es nicht brauchst
• HTTPS-Tunneling — Eingebaute Unterstuetzung fuer 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-Schluessel oder OAuth-Anmeldedaten fuer deinen LLM-Anbieter
• (Optional) Tailscale, ngrok oder cloudflared fuer 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 fuehrt dich durch die Auswahl eines LLM-Anbieters, die Konfiguration der Authentifizierung und die Einrichtung der Tool-Berechtigungen.

Sobald der Server laeuft, kopiere die angezeigten URLs in die PocketHook-Einstellungen:

Funktionsweise

#

1. Du sendest eine Nachricht in PocketHook
2. Der Server leitet sie an dein gewaehltes LLM weiter, zusammen mit Gespraechsverlauf, abgerufenen Erinnerungen und verfuegbaren Tools
3. Das LLM verarbeitet die Nachricht — es kann Shell-Befehle ausfuehren, Dateien lesen/schreiben, im Web suchen, Hintergrund-Jobs planen, Fakten merken oder Dev-Server starten
4. Die Antwort wird im PocketHook-Format zurueckgegeben (msg + shortcut + data + url)
5. PocketHook zeigt die Nachricht an und fuehrt alle Shortcuts auf deinem Geraet aus

Unterstuetzte LLM-Anbieter

#

Wechsle jederzeit den Anbieter mit bun run switch. Ollama und LM Studio laufen vollstaendig auf deinem Rechner — kein API-Schluessel noetig, keine Daten verlassen dein Netzwerk.

Gedaechtnis

#

Das Gedaechtnissystem hat drei Schichten, die jeweils einem anderen Zweck dienen.

Das Design des semantischen Gedaechtnisses kombiniert Ideen von MemPalace (eine Gedaechtnispalast-Architektur, die Erinnerungen in Wings, Halls und Rooms organisiert) und Tiago Fortes PARA-Methode (Projekte, Bereiche, Ressourcen, Archiv) fuer das Wissenslebenszyklus-Management.

Gespraechsgedaechtnis

#

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 ueber FTS5-Stichwortsuche
• Abruf pro Turn — Wenn das semantische Gedaechtnis 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 Langzeitgedaechtnis bleibt fuer immer bestehen

Stelle diese Werte interaktiv mit bun run memory ein.

Semantisches Gedaechtnis

#

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 Entitaet: 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 Entitaetsextraktion die Vektorsuche auf die relevantesten Wings. Ergebnisse werden mit FTS5-Stichwort-Ergebnissen mittels Reciprocal-Rank-Fusion zusammengefuehrt — so bekommst du das Beste aus Stichwort- und semantischer Suche.

Wissensgraph

#

Ein temporaler Triple-Store fuer strukturierte, dauerhafte Fakten:

• Tripel: (Subjekt, Praedikat, Objekt) mit valid_from / valid_until Zeitstempeln
• Einzelwert-Praedikate (lives_in, partner) invalidieren automatisch den alten Wert bei Aktualisierung
• Mehrwert-Praedikate (child, friend, hobby) koexistieren ohne Invalidierung
• Wissensgraph-Fakten werden zusammen mit abgerufenen Erinnerungen in jedes Gespraech 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 Aehnlichkeit, um nur die Erinnerungen dieses Projekts zu archivieren, waehrend Referenzmaterial fuer zukuenftige 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 Praedikat 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 unberuehrt. Der Agent muss nicht mehr drei separate Aufrufe in der richtigen Reihenfolge orchestrieren, weshalb auch kleinere Modelle das zuverlaessig hinbekommen.

Wenn VECTOR_MEMORY deaktiviert ist oder der Embedding-Anbieter nicht erreichbar ist, faellt das System fehlerfrei auf FTS5-only zurueck.

Skills

#

Skills sind .md-Dateien in skills/, die iOS-Shortcuts definieren, die der Agent ausloesen kann, und/oder Verhaltensregeln. Sie verwenden dynamisches Laden: Nur ein kompakter Index (Titel, Beschreibung, Shortcut-Liste) wird in den System-Prompt injiziert. Der Agent laedt den vollstaendigen Inhalt bei Bedarf ueber das load_skill-Tool, um den Token-Verbrauch niedrig zu halten, wenn du mehr Skills hinzufuegst.

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 koennen auch Verhaltensregeln ohne Shortcuts sein (z. B. “wie man eine Familienreise plant”). Verwende shortcuts: [] dafuer.

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

Shortcuts auf dem Mac-Server ausfuehren

#

Wenn ein Skill target: mac hat, werden Shortcuts still auf dem Mac-Server ueber die shortcuts run-CLI ausgefuehrt, anstatt an das iOS-Geraet gesendet zu werden. Das ist ideal fuer Aktionen, die iCloud-synchronisierte Inhalte erzeugen — Notizen, Erinnerungen, Kalenderereignisse — weil das Ergebnis automatisch auf all deine Geraete synchronisiert wird, ohne dass die PocketHook-App etwas tun muss.

So funktioniert es:

1. Der Agent entscheidet, dass ein Shortcut ausgefuehrt werden soll (z. B. “erstelle eine Notiz mit den heutigen Besprechungsnotizen”)
2. Der Server ruft shortcuts run "shortcutName" mit den als JSON ueber stdin uebergebenen Daten auf und verwendet dasselbe Wrapper-Format wie PocketHook iOS
3. Wenn sync_app gesetzt ist, oeffnet der Server diese App kurz im Hintergrund (open -gj -a Notes), um iCloud-Sync zu erzwingen, und schliesst sie nach 5 Sekunden wieder
4. Der Benutzer erhaelt eine Bestaetigung im Chat; der Shortcut selbst wird nicht an das Geraet gesendet

Voraussetzungen:

• Der Server muss auf macOS laufen — shortcuts run ist nur unter macOS verfuegbar. Auf anderen Plattformen protokolliert der Server eine Warnung und faellt auf Geraete-Ausfuehrung zurueck
• 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 Geraet
• Lang laufende Verarbeitungen, die du vom iOS-Geraet fernhalten willst
• Jeder Shortcut, der nicht mit der iPhone-Oberflaeche interagieren muss

Wann target: device (Standard) beibehalten:

• Shortcuts, die iPhone-spezifische Funktionen benoetigen (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:

• “Pruefe jeden Morgen um 8 Uhr das Wetter und erstelle eine Notiz”
• “Fuehre dieses Skript jede Stunde aus”
• “Erinnere mich in 30 Minuten, meine E-Mails zu pruefen”

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

Zwei Ausfuehrungstypen:

• Shell — Fuehrt einen Bash-Befehl aus, erfasst die Ausgabe. Kann bei Abschluss einen Shortcut ausloesen
• Prompt — Wird vom KI-Agenten mit vollem Tool-Zugriff verarbeitet, speichert die vollstaendige 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
• Oeffentlich — Startet den Server und macht ihn ueber einen HTTPS-Tunnel von ueberall zugaenglich

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. Schlaegt die Tunnel-Einrichtung nach dem Spawn fehl, wird der verwaiste Prozess gestoppt und der Agent wird ausdruecklich informiert — so kann er auf den Vorschaumodus zurueckfallen oder dich bitten, einen Tunnel zu installieren. Die zurueckgegebene URL ist immer die Tunnel-URL, wenn Tunneling aktiv ist, mit dem Hinweis, dass die lokale URL nur fuer 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-Uebersicht der Hintergrund-Jobs.

Absichtlich nicht authentifiziert. Sowohl /dashboard als auch /api/jobs sind offene GET-Endpunkte — wer den Host erreichen kann, kann Jobs auflisten. Beschraenke 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 vollstaendig anpassbar:

• Schnellbearbeitung — Platziere eine dashboard.html in workspace/dashboard/ fuer 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 Faehigkeiten registrieren — er erweitert sich selbst, ohne den Servercode zu aendern.

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

1. Die Abhaengigkeit installieren
2. Eine Tool-Definition erstellen (eine einfache .md-Datei)
3. Das neue Tool in zukuenftigen Gespraechen verwenden

Benutzerdefinierte Tools werden sofort nachgeladen — kein Neustart noetig. Loesche 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 Aenderung rueckgaengig” oder verwende git revert HEAD manuell
• Konfigurationsdateien — config/agent-instructions.md, config/personality.md, skills/ und permissions.json werden vor jeder Aenderung gesichert. Bis zu 20 Versionen pro Datei

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

Agent anpassen

#

Der Agentserver kommt mit einer minimalen Framework-Basis und erwartet, dass du deine eigenen Anpassungen darueber legst. Die Laufzeit haelt beides getrennt, damit Framework-Updates deine Arbeit nie ueberschreiben.

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 ueber dedizierte typisierte Tools (create_user_skill, create_custom_tool) geschrieben, sodass die resultierenden Dateien immer dem Format des Loaders entsprechen. Das write-Tool weist ausserdem 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 enthaelt es nur eine Vorlage (_example.md), die der Loader ignoriert — jedes Tool, das der Agent fuer dich installiert, landet in data/user/custom-tools/. Das Verzeichnis ist reserviert, damit zukuenftige Framework-Releases optionale eingebaute Tools ausliefern koennen, ohne deine Installationen zu ueberschreiben. 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 waehlt die richtige Schicht automatisch.

Typisierte Praeferenzen 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 Schluessel ({{prefs.tunnel.domain}}) funktionieren ebenfalls. Unbekannte Schluessel bleiben unveraendert, 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 haelt dich nicht davon ab, wenn du einen Dateieditor verwendest. Aber der Agent schreibt aus einem Gespraech heraus nicht in diese Pfade. Und Framework-Updates werden deine Aenderungen ueberschreiben. Bevorzuge die Benutzerschicht fuer 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 hinzufuegen — Bitte den Agenten, einen Skill zu erstellen; die Datei landet in data/user/skills/
• Verhalten aendern — Bitte den Agenten, eine globale Regel anzuwenden; sie wird an data/user/instructions.md angehaengt
• Berechtigungen konfigurieren — Fuehre bun run permissions aus, um zu steuern, welche Tools der Agent nutzen darf
• Eingebaute Tools hinzufuegen — Implementiere neue Tool-Funktionen in src/tools.ts fuer tiefere Integrationen (erfordert Forken des Servers)

Konfiguration

#

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

Die vollstaendige Konfigurationsreferenz findest du im GitHub-Repository.

Als Dienst ausfuehren

#

Installation als persistenter Dienst, der automatisch startet:

bun run service install

INSTANCE_NAME ist standardmaessig der Basisname des Projektverzeichnisses ohne das pockethook--Praefix (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 behaelt ihr eigenes data/ und ihre eigenen Logs.

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

Sicherheit

#

• HTTPS erforderlich — PocketHook erzwingt HTTPS fuer 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 eingeschraenkt
• Blockierte Muster — Gefaehrliche Befehle (sudo, rm -rf /) standardmaessig blockiert
• Arbeitsverzeichnis-Grenze — Agent kann sein zugewiesenes Verzeichnis nicht verlassen
• Sensible Dateien geschuetzt — .env, .git, *.key, *.pem vor Agentenzugriff blockiert
• Automatische Versionierung — Alle Workspace-Aenderungen werden per Git verfolgt fuer einfaches Zurueckrollen