Agentserver

Hvad er PocketHook Agent Server?

#

Agentserveren goer PocketHook til en fuld AI-assistent. I stedet for at skrive responslogik selv, forbinder du et LLM (Claude, GPT, Gemini osv.) der behandler beskeder, kalder vaerktojer og returnerer strukturerede PocketHook-svar — inklusive Shortcut-triggers.

Serveren koerer paa din egen maskine. Dine data forbliver hos dig.

Dette er et udgangspunkt. Serveren leveres med et kernesaet vaerktojer og er designet til at blive udvidet af dig. Tilfoej dine egne integrationer — e-mail, kalendere, dokumenter, APIs — og goer den til din.

Funktioner

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• OAuth-godkendelse — GitHub Copilot og OpenAI Codex via device-code-/browser-flow
• Agentvaerktojer — Shell-kommandoer, fillaesning/skrivning, mappevisning, websoegning, web scraping, dev-serveradministration
• Framework/bruger-opdeling — Framework-filer (skills/, custom-tools/, config/) forbliver skrivebeskyttede. Dine tilpasninger bor under data/user/ (skills, tilpassede vaerktojer, instruktioner, typede praeferencer). Framework-opdateringer lander rent uden at overskrive dit arbejde
• Typede brugerpraeferencer — Gem vaerdier som din foretrukne kortapp eller tunneldomaene i data/user/prefs.json. Referer til dem i skills som {{prefs.key}}, og serveren indsaetter dem ved indlaesning
• Programmeringsopgaver i ét kald — Meta-vaerktoejet run_code_job opretter et baggrundsjob af prompt-typen (koert af din konfigurerede LLM) og sender brugeren kvitteringen i ét trin, og erstatter det fejlagtige “respond + create-job”-moenster
• Typede protokolvaerktojer — Seks dedikerede respond_*-vaerktoejer (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typede jobvaerktoejer (create_once_job, create_cron_job) og typede workspace-vaerktoejer (create_project, list_projects, delete_project). Skemaer afviser fejlbehaeftede URL’er, knapsyntaks og type/schedule-kombinationer foer de naar enheden
• Typede skribenter til tilpasning — create_user_skill og create_custom_tool bygger brugerlagets markdown med korrekt frontmatter, saa loaderen altid parser dem og agenten aldrig skriver disse filer i haanden
• Baggrundsjob — Engangs- eller tilbagevendende opgaver med cron-udtryk eller enkle intervaller
• Dynamiske skills — Definer Shortcuts og adfaerdsregler som .md-filer. Kun et kompakt indeks indlaeses i prompten; fuldt indhold hentes efter behov via load_skill-vaerktoejet
• Selvadministrerende skills — Agenten kan oprette, redigere og slette skilldefinitioner (skrivninger lander altid i brugerlaget)
• Semantisk hukommelse — Vektorbaseret soegning med embeddings (Ollama, LM Studio eller OpenAI). Minder klassificeres automatisk af LLM’et i wing/room/hall/status-dimensioner
• Vidensgraf — Temporalt triple-store for varige fakta med automatisk invalidering. Multi-vaerdi-relationer sameksisterer; enkelvaerdi-fakta erstattes automatisk
• PARA-metoden med projektafslutnings-kaskade — Hvert minde tagges med en status (Projekt, Omraade, Ressource, Arkiv). Naar et projekt afsluttes, arkiverer ét enkelt complete_project-kald dets vektorer, invaliderer hvert planlaegningstriple knyttet til dets slug og registrerer afslutningen — ét kald i stedet for tre
• Hybrid recall — Kombinerer FTS5-soegeordssoegning med vektor-semantisk soegning via reciprocal rank fusion
• Langtidshukommelse — SQLite + FTS5-fuldtekstsogning som fallback naar semantisk hukommelse er deaktiveret
• Dev-serveradministration med tunnelkontrakt — Start, stop og list dev-servere. Naar tunnel: true anmodes, haandhaever serveren det baade foer-flyve og efter-spawn — en utilgaengelig localhost-server efterlades aldrig stille i koerende tilstand
• Automatisk URL-sanering — Hvis agenten efterlader en localhost-URL i et svar, omskriver respond_*-vaerktoejerne den til den matchende tunnel-URL, saa din telefon altid faar et link der virker
• Tilpassede vaerktojer — Agenten kan installere CLI-vaerktojer og registrere dem som nye kapabiliteter
• Versionering — Automatisk git-versionering for workspace-filer; konfigurationsbackup for skills og tilladelser
• Webdashboard — Live-oversigt over baggrundsjob, tilpasseligt per bruger. /dashboard og /api/jobs er bevidst uautentificerede — begraens adgang paa netvaerkslaget (Tailscale-ACL, firewall, reverse proxy med basic auth) eller saet DASHBOARD=false hvis du ikke har brug for det
• HTTPS-tunneling — Indbygget understoettelse for Tailscale, ngrok og Cloudflare Tunnel
• Systemservice — Installer som persistent service paa macOS, Linux eller Windows
• Rate limiting — Per-token anmodningsgraenser med konfigurerbare taerskler

Krav

#

• Bun runtime
• En API-noegle eller OAuth-legitimationsoplysninger til din LLM-udbyder
• (Valgfrit) Tailscale, ngrok eller cloudflared til HTTPS-tunneling

Hurtig start

#

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

# Interaktiv opsaetning — vaelg udbyder, model, auth-token, port
bun run setup

# Start server + HTTPS-tunnel
bun run dev:tunnel

Opsaetningsguiden foerer dig gennem valg af LLM-udbyder, konfiguration af godkendelse og opsaetning af vaerktoejstilladelser.

Naar serveren koerer, kopier de viste URLs til PocketHook-indstillinger:

Saadan fungerer det

#

1. Du sender en besked i PocketHook
2. Serveren videresender den til dit valgte LLM med samtalehistorik, hentede minder og tilgaengelige vaerktojer
3. LLM’et behandler beskeden — det kan koere shell-kommandoer, laese/skrive filer, soege paa nettet, planlaegge baggrundsjob, huske fakta eller starte dev-servere
4. Svaret returneres i PocketHook-format (msg + shortcut + data + url)
5. PocketHook viser beskeden og udforer alle Shortcuts paa din enhed

Understoettede LLM-udbydere

#

Skift udbyder naar som helst med bun run switch. Ollama og LM Studio koerer helt paa din maskine — ingen API-noegle noedvendig, ingen data forlader dit netvaerk.

Hukommelse

#

Hukommelsessystemet har tre lag, der hver tjener et forskelligt formaal.

Designet af den semantiske hukommelse kombinerer ideer fra MemPalace (en hukommelsespalads-arkitektur der organiserer minder i wings, halls og rooms) og Tiago Fortes PARA-metode (Projekter, Omraader, Ressourcer, Arkiv) til videns-livscyklusstyring.

Samtalehukommelse

#

SQLite med FTS5-fuldtekstsogning. Alle beskeder gemmes med tidsstempler og sessions-ID’er.

• Kort sigt — Sidste MAX_HISTORY beskeder holdt i hukommelsen per session
• Lang sigt — Alle beskeder gemt i SQLite, sogbare via FTS5-soegeordmatching
• Recall per tur — Naar semantisk hukommelse er aktiveret, styrer MAX_RECALL hvor mange relevante minder der injiceres i prompten hver tur
• Sessioner udloeber efter SESSION_TTL_MINUTES, men langtidshukommelse bestaar for altid

Justér disse interaktivt med bun run memory.

Semantisk hukommelse

#

Kraever VECTOR_MEMORY=true og en embedding-udbyder (Ollama, LM Studio eller OpenAI).

Hvert minde indlejres som en vektor og klassificeres automatisk af LLM’et i fire dimensioner:

• Wing — Entiteten: user, person:john, project:blog, place:london
• Room — Typen: facts, preferences, events, decisions, requests
• Hall — Emnet: personal, tech, health, travel, food, work
• Status — PARA-klassifikation: project, area, resource, archive

Naar du stiller et spoergsmaal, fokuserer entitetsekstraktion vektorsogningen paa de mest relevante wings. Resultater sammenflettes med FTS5-soegeordresultater via reciprocal rank fusion — saa du faar det bedste af baade soegeord- og semantisk soegning.

Vidensgraf

#

Et temporalt triple-store for strukturerede, varige fakta:

• Tripler: (subjekt, praedikat, objekt) med valid_from / valid_until tidsstempler
• Enkelvaerdi-praedikater (lives_in, partner) invaliderer automatisk den gamle vaerdi ved opdatering
• Multivaerdi-praedikater (child, friend, hobby) sameksisterer uden invalidering
• Vidensgraffakta injiceres sammen med hentede minder i enhver samtale

Naar du fortaeller agenten “Jeg er flyttet til Berlin”, invaliderer den det gamle lives_in-triple og opretter et nyt — automatisk.

PARA-livscyklus

#

Hvert minde tagges med en PARA-status:

• Projekt — Aktivt, tidsbundet arbejde
• Omraade — Loebende ansvarsomraader
• Ressource — Referencemateriale (lister, anbefalinger, vejledninger)
• Arkiv — Afsluttede eller annullerede projekter

Naar et projekt afsluttes, bruger agenten semantisk lighed til kun at arkivere det projekts minder, mens referencemateriale bevares til fremtidig brug.

Projektafslutnings-kaskade

#

Sig “Jeg aflyser min rejse til Barcelona”, og et enkelt vaerktoejskald haandterer alt:

1. Arkiverer projektets vektorer (events, decisions, requests knyttet til Barcelona).
2. Invaliderer hvert aktivt vidensgraf-triple hvis praedikat matcher projektets slug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registrerer afslutningen som et nyt triple: (user, "cancelled_visit_barcelona", "2026-04-15").

Matchning er graensebevidst — et andet projekt kaldet revisit_barcelona forbliver uroert. Agenten skal ikke laengere orkestrere tre separate kald i den rigtige raekkefoelge, saa mindre modeller rammer det ogsaa rigtigt.

Hvis VECTOR_MEMORY er deaktiveret eller embedding-udbyderen er utilgaengelig, falder systemet fejlfrit tilbage til FTS5-only.

Skills

#

Skills er .md-filer i skills/ der definerer iOS-Shortcuts agenten kan udlose og/eller adfaerdsregler. De bruger dynamisk indlaesning: kun et kompakt indeks (titel, beskrivelse, shortcutliste) injiceres i systemprompten. Agenten indlaeser fuldt indhold efter behov via load_skill-vaerktoejet, saa tokenforbruget holdes lavt efterhaanden som du tilfojer flere skills.

Hver skillfil bruger 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-felter

#

Skills kan ogsaa vaere adfaerdsregler uden shortcuts (f.eks. “hvordan man planlaegger en familieferie”). Brug shortcuts: [] til disse.

Agenten kan oprette og administrere skills naar du beder om det — bed den om at “oprette en skill til at styre mine lamper” og den skriver .md-filen for dig. Nye og redigerede skills lander altid i dit brugerlag (data/user/skills/), saa framework-opdateringer aldrig overskriver dem. Se afsnittet Customizing your agent nedenfor.

Udfoerelse af shortcuts paa Mac-serveren

#

Naar en skill har target: mac, koeres shortcuts stille paa Mac-serveren via shortcuts run-CLI’en i stedet for at blive sendt til iOS-enheden. Det er ideelt til handlinger der opretter iCloud-synkroniseret indhold — noter, paamindelser, kalenderbegivenheder — fordi resultatet automatisk synkroniseres til alle dine enheder, uden at PocketHook-appen skal goere noget.

Saadan fungerer det:

1. Agenten beslutter at en shortcut skal koere (f.eks. “opret en note med dagens moedenoter”)
2. Serveren kalder shortcuts run "shortcutNavn" med dataene sendt som JSON paa stdin, i samme wrapper-format som PocketHook iOS bruger
3. Hvis sync_app er sat, aabner serveren kort den app i baggrunden (open -gj -a Notes) for at tvinge iCloud-synkronisering og lukker den igen efter 5 sekunder
4. Brugeren modtager en bekraeftelsesbesked i chatten; selve shortcut’en sendes ikke til enheden

Krav:

• Serveren skal koere paa macOS — shortcuts run findes kun paa macOS. Paa andre platforme logger serveren en advarsel og falder tilbage til enhedsudfoerelse
• Shortcut’en skal vaere installeret i Shortcuts.app paa Mac-serveren
• Shortcut’en boer forvente en Dictionary som input (PocketHook pakker data ind i { context, timestamp, app, data })

Hvornaar du skal bruge target: mac:

• iCloud-synkroniserede handlinger (Notes, Reminders, Calendar) — resultatet naar alligevel alle enheder
• Langvarig behandling du vil holde vaek fra iOS-enheden
• Enhver shortcut der ikke skal interagere med iPhone’ens brugergraenseflade

Hvornaar du skal beholde target: device (standard):

• Shortcuts der skal bruge iPhone-specifikke funktioner (kamera, praecis lokation, lokale app-automatiseringer)
• Shortcuts der beder brugeren om interaktivt input
• Shortcuts der bruger App Intents fra iOS-kun-apps

Baggrundsjob

#

Bed agenten om at planlaegge opgaver, og den klarer resten:

• “Tjek vejret hver morgen kl. 8 og opret en note”
• “Koer dette script hver time”
• “Mind mig om at tjekke min e-mail om 30 minutter”

Job understoetter cron-udtryk (0 8 * * *) og enkle intervaller (30m, 1h, 2d). Resultater leveres til PocketHook naar den poller /jobs-endepunktet.

To udfoerelsestyper:

• Shell — Koerer en bash-kommando, opfanger output. Kan udlose en Shortcut ved faerdiggoerelse
• Prompt — Behandlet af AI-agenten med fuld vaerktoejsadgang, gemmer det komplette PocketHook-svar

Dev-servere

#

Naar agenten opretter et webprojekt i workspacet (Hugo, Astro, Next.js, Flask, Go osv.), tilbyder den proaktivt at servere det:

• Preview — Starter en lokal dev-server paa en automatisk tildelt port til hurtig visning
• Offentlig — Starter serveren og eksponerer den via HTTPS-tunnel saa den er tilgaengelig overalt

Agenten styrer livscyklussen: start, stop og list koerende servere. Alle servere ryddes op naar hovedserveren stopper.

Tunnelkontrakt

#

Naar agenten starter en server med tunneludsaettelse anmodet, haandhaever runtimen det: hvis intet tunnelvaerktoej (Tailscale, ngrok, cloudflared) er installeret, naegter serveren at starte. Hvis tunnelopsaetning fejler efter spawn, stoppes forael­dreproces­sen, og agenten faar det udtrykkeligt at vide — saa den kan falde tilbage til preview-tilstand eller bede dig installere en tunnel. Den returnerede URL er altid tunnel-URL’en naar tunneling er slaaet til, med en bemaerkning om at den lokale URL kun gaelder for vaerten.

Som et sikkerhedsnet efterbehandler hvert respond_*-vaerktoej sin besked: enhver localhost- eller 127.0.0.1-URL der smutter med i et svar, omskrives automatisk til den matchende tunnel-URL naar en administreret server har en. Naar det ikke kan omskrive, faar du en advarsel i logfilerne i stedet for et brudt link paa din telefon.

Dashboard

#

Det indbyggede webdashboard paa /dashboard viser en live-oversigt over baggrundsjob.

Bevidst uautentificeret. Baade /dashboard og /api/jobs er aabne GET-endepunkter — enhver der kan naa vaerten kan liste job. Begraens adgang paa netvaerkslaget (Tailscale-ACL, firewall, reverse proxy med basic auth) eller saet DASHBOARD=false hvis du ikke har brug for det. PocketHook iOS-appen bruger ikke disse endepunkter.

Det er fuldt tilpasseligt:

• Hurtig redigering — Placer en dashboard.html i workspace/dashboard/ til enkle tilpasninger
• Fuldt projekt — Opret et framework-projekt (Svelte, React, Vue osv.) i workspace/dashboard/ med build-output til dist/

Bed agenten om at tilpasse dit dashboard, og den klarer resten — hver bruger faar et unikt, personaliseret dashboard.

Tilpassede vaerktojer

#

Agenten kan installere CLI-vaerktojer og registrere dem som nye kapabiliteter — udvider sig selv uden at aendre serverkoden.

Sig for eksempel “installer Playwright og brug det til at tage screenshots”. Agenten vil:

1. Installere afhaengigheden
2. Oprette en vaerktoejsdefinition (en simpel .md-fil)
3. Bruge det nye vaerktoj i fremtidige samtaler

Tilpassede vaerktojer hot-reloades — ingen genstart noedvendig. Slet .md-filen for at fjerne et vaerktoj.

Versionering

#

Alle brugerdata versioneres automatisk:

• Workspace-filer — Sporet med et lokalt git-repo inde i workspace/. Hver skrivning opretter en auto-commit. Bed agenten om at “fortryde den sidste aendring” eller brug git revert HEAD manuelt
• Konfigurationsfiler — config/agent-instructions.md, config/personality.md, skills/ og permissions.json sikkerhedskopieres foer hver aendring. Op til 20 versioner per fil

Git er valgfrit — hvis det ikke er installeret, er workspace-aendringer ikke versioneret. Konfigurationsbackup fungerer altid.

Tilpas din agent

#

Agentserveren leveres med en minimal framework-base og forventer at du lagrer din egen tilpasning oven paa. Runtimen holder de to adskilt saa framework-opdateringer aldrig oedelaegger dit arbejde.

Framework vs bruger

#

pockethook-agent-server/
├── skills/                      # framework-leverede skills (skrivebeskyttet)
├── custom-tools/                # reserveret til framework-leverede vaerktojer (skrivebeskyttet)
├── config/
│   ├── agent-instructions.md    # framework-agentinstruktioner (skrivebeskyttet)
│   └── personality.md           # framework-personlighed (skrivebeskyttet)
└── data/user/                   # DIN tilpasning bor her (git-ignoreret)
    ├── skills/                  # dine egne skills (overrider base paa filnavn)
    ├── custom-tools/            # dine installerede tilpassede vaerktojer
    ├── instructions.md          # dine tilfoejelser til agentinstruktioner
    └── prefs.json               # typede vaerdier refereret som {{prefs.key}}

Brugertilpasning skrives via dedikerede typede vaerktoejer (create_user_skill, create_custom_tool), saa de resulterende filer altid matcher loaderens format. write-vaerktoejet afviser ogsaa enhver sti under skills/, custom-tools/ eller config/ og dirigerer agenten til data/user/* — saa selv direkte filredigeringer ender i brugerlaget.

Bemaerk om base-mappen custom-tools/. I dag indeholder den kun en skabelon (_example.md) som loaderen ignorerer — ethvert vaerktoej agenten installerer for dig, havner i data/user/custom-tools/. Mappen er reserveret, saa fremtidige framework-udgivelser kan levere valgfri indbyggede vaerktoejer uden at oedelaegge dine installationer. Naar det sker, vinder dine brugerlag-filer stadig ved navnekollision, saa der er intet at migrere.

Fire maader at tilpasse paa

#

Du behoever aldrig at skrive disse filer i haanden. Fortael blot agenten hvad du vil have, og den vaelger det rigtige lag automatisk.

Typede praeferencer med {{prefs.*}}

#

Sig at du skriver en ruteplanlaegger-skill der skal kende dit standardudgangspunkt. I stedet for at hardcode “Madrid” i selve skill’en, referer til praeferencen:

- **Udgangspunkt**: {{prefs.routeOrigin}}, medmindre brugeren angiver et andet udgangspunkt.

Og gem vaerdien i data/user/prefs.json:

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

Serveren indsaetter pladsholdere naar skill’en indlaeses. Indlejrede noegler ({{prefs.tunnel.domain}}) virker ogsaa. Ukendte noegler efterlades uroerte, saa tastefejl forbliver synlige.

Redigering af framework-basen direkte

#

Hvis du selvhoster og vil pille ved selve frameworket, kan du redigere config/agent-instructions.md, config/personality.md, skills/ eller custom-tools/ direkte — serveren stopper dig ikke naar du bruger en fil-editor. Men agenten vil ikke skrive til de stier fra en samtale. Og framework-opdateringer vil overskrive dine redigeringer. Foretraek brugerlaget til alt du vil beholde.

Udvid serveren

#

• Tilpassede vaerktojer — Bed agenten om at installere CLI-vaerktojer; de lander automatisk i data/user/custom-tools/
• Tilfoej skills — Bed agenten om at oprette en skill; filen ryger i data/user/skills/
• Aendr adfaerd — Bed agenten om at anvende en global regel; den tilfoejes i data/user/instructions.md
• Konfigurer tilladelser — Koer bun run permissions for at styre hvilke vaerktojer agenten kan bruge
• Tilfoej indbyggede vaerktojer — Implementer nye vaerktoejsfunktioner i src/tools.ts for dybere integrationer (kraever fork af serveren)

Konfiguration

#

Alle indstillinger gemmes i .env (oprettet af bun run setup). Vigtige muligheder:

Se den fulde konfigurationsreference i GitHub-repositoryet.

Koer som service

#

Installer som persistent service der starter automatisk:

bun run service install

INSTANCE_NAME er som standard projektmappens basisnavn med pockethook--praefikset fjernet (f.eks. bliver et checkout i pockethook-agent-server/ til agent-server). Saet det eksplicit for at koere flere checkouts paa samme maskine uden kollisioner — hver instans beholder sit eget data/ og logs.

Administrer med bun run service status, restart, stop eller uninstall.

Sikkerhed

#

• HTTPS paakraevet — PocketHook kraever HTTPS for alle URLs
• Bearer-token-godkendelse — Delt hemmelighed mellem app og server
• Rate limiting — Per-token graenser forhindrer misbrug
• Sandboxed vaerktojer — Shell-kommandoer og filadgang begraenset af tilladelser
• Blokerede moenstre — Farlige kommandoer (sudo, rm -rf /) blokeret som standard
• Arbejdsmappe-graense — Agenten kan ikke forlade sin tildelte mappe
• Foelsomme filer beskyttet — .env, .git, *.key, *.pem blokeret fra agentadgang
• Automatisk versionering — Alle workspace-aendringer git-spores for nem tilbagerulning