Agentserver

Hvad er PocketHook Agent Server?

#

Agentserveren gør 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 værktøjer og returnerer strukturerede PocketHook-svar — inklusive Shortcut-triggers.

Serveren kører på din egen maskine. Dine data forbliver hos dig.

Dette er et udgangspunkt. Serveren leveres med et kernesæt værktøjer og er designet til at blive udvidet af dig. Tilføj dine egne integrationer — e-mail, kalendere, dokumenter, APIs — og gør den til din.

Funktioner

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• Hurtig model — Kør en letvægts sekundær model til interne hjælpere (hukommelsesklassificering, entitetsudtrækning) sammen med din primære chatmodel — fuld kontrol over omkostninger og latenstid
• Safari-udvidelse — Par en notariseret macOS Safari-udvidelse, så agenten kan åbne faner, inspicere sider, klikke, udfylde formularer og tage skærmbilleder i din rigtige browsersession, med det tilladelsesniveau du vælger
• OAuth-godkendelse — GitHub Copilot og OpenAI Codex via device-code-/browser-flow
• Agentværktøjer — Shell-kommandoer, fillæsning/skrivning, mappevisning, websøgning, web scraping, dev-serveradministration
• Framework/bruger-opdeling — Framework-filer (skills/, custom-tools/, config/) forbliver skrivebeskyttede. Dine tilpasninger bor under data/user/ (skills, tilpassede værktøjer, instruktioner, typede præferencer). Framework-opdateringer lander rent uden at overskrive dit arbejde
• Typede brugerpræferencer — Gem værdier som din foretrukne kortapp eller tunneldomæne i data/user/prefs.json. Referer til dem i skills som {{prefs.key}}, og serveren indsætter dem ved indlæsning
• Programmeringsopgaver i ét kald — Meta-værktøjet run_code_job opretter et baggrundsjob af prompt-typen (kørt af din konfigurerede LLM) og sender brugeren kvitteringen i ét trin, og erstatter det fejlagtige “respond + create-job”-mønster
• Typede protokolværktøjer — Seks dedikerede respond_*-værktøjer (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typede jobværktøjer (create_once_job, create_cron_job) og typede workspace-værktøjer (create_project, list_projects, delete_project). Skemaer afviser fejlbehæftede URL’er, knapsyntaks og type/schedule-kombinationer før de når enheden
• Typede skribenter til tilpasning — create_user_skill og create_custom_tool bygger brugerlagets markdown med korrekt frontmatter, så loaderen altid parser dem og agenten aldrig skriver disse filer i hånden
• Baggrundsjob — Engangs- eller tilbagevendende opgaver med cron-udtryk eller enkle intervaller
• Dynamiske skills — Definer Shortcuts og adfærdsregler som .md-filer. Kun et kompakt indeks indlæses i prompten; fuldt indhold hentes efter behov via load_skill-værktøjet
• Selvadministrerende skills — Agenten kan oprette, redigere og slette skilldefinitioner (skrivninger lander altid i brugerlaget)
• Semantisk hukommelse — Vektorbaseret søgning 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-værdi-relationer sameksisterer; enkelværdi-fakta erstattes automatisk
• PARA-metoden med projektafslutnings-kaskade — Hvert minde tagges med en status (Projekt, Område, Ressource, Arkiv). Når et projekt afsluttes, arkiverer ét enkelt complete_project-kald dets vektorer, invaliderer hvert planlægningstriple knyttet til dets slug og registrerer afslutningen — ét kald i stedet for tre
• Hybrid recall — Kombinerer FTS5-søgeordssøgning med vektor-semantisk søgning via reciprocal rank fusion
• Langtidshukommelse — SQLite + FTS5-fuldtekstsogning som fallback når semantisk hukommelse er deaktiveret
• Dev-serveradministration med tunnelkontrakt — Start, stop og list dev-servere. Når tunnel: true anmodes, håndhæver serveren det både før-flyve og efter-spawn — en utilgængelig localhost-server efterlades aldrig stille i kørende tilstand
• Automatisk URL-sanering — Hvis agenten efterlader en localhost-URL i et svar, omskriver respond_*-værktøjerne den til den matchende tunnel-URL, så din telefon altid får et link der virker
• Tilpassede værktøjer — Agenten kan installere CLI-værktøjer 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 — begræns adgang på netværkslaget (Tailscale-ACL, firewall, reverse proxy med basic auth) eller sæt DASHBOARD=false hvis du ikke har brug for det
• HTTPS-tunneling — Indbygget understøttelse for Tailscale, ngrok og Cloudflare Tunnel
• Systemservice — Installer som persistent service på macOS, Linux eller Windows
• Rate limiting — Per-token anmodningsgrænser med konfigurerbare tærskler

Krav

#

• Bun runtime
• En API-nøgle 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

Opsætningsguiden fører dig gennem valg af LLM-udbyder, konfiguration af godkendelse og opsætning af værktøjstilladelser — inklusive om Safari-udvidelsen skal installeres (valgfrit, kan springes over, kun macOS).

Kør bun run help når som helst for en fuld liste over kommandoer, eller bun run config for at se din nuværende konfiguration i et overblik (hemmeligheder maskeret).

Når serveren kører, kopier de viste URLs til PocketHook-indstillinger:

Sådan fungerer det

#

1. Du sender en besked i PocketHook
2. Serveren videresender den til dit valgte LLM med samtalehistorik, hentede minder og tilgængelige værktøjer
3. LLM’et behandler beskeden — det kan køre shell-kommandoer, læse/skrive filer, søge på nettet, planlægge 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 på din enhed

Understøttede LLM-udbydere

#

Skift udbyder når som helst med bun run switch. Ollama og LM Studio kører helt på din maskine — ingen API-nøgle nødvendig, ingen data forlader dit netværk.

Hukommelse

#

Hukommelsessystemet har tre lag, der hver tjener et forskelligt formål.

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, Områder, 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, søgbare via FTS5-søgeordmatching
• Recall per tur — Når semantisk hukommelse er aktiveret, styrer MAX_RECALL hvor mange relevante minder der injiceres i prompten hver tur
• Sessioner udløber efter SESSION_TTL_MINUTES, men langtidshukommelse består for altid

Justér disse interaktivt med bun run memory.

Semantisk hukommelse

#

Kræver 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

Når du stiller et spørgsmål, fokuserer entitetsekstraktion vektorsogningen på de mest relevante wings. Resultater sammenflettes med FTS5-søgeordresultater via reciprocal rank fusion — så du får det bedste af både søgeord- og semantisk søgning.

Vidensgraf

#

Et temporalt triple-store for strukturerede, varige fakta:

• Tripler: (subjekt, praedikat, objekt) med valid_from / valid_until tidsstempler
• Enkelværdi-prædikater (lives_in, partner) invaliderer automatisk den gamle værdi ved opdatering
• Multiværdi-prædikater (child, friend, hobby) sameksisterer uden invalidering
• Vidensgraffakta injiceres sammen med hentede minder i enhver samtale

Når du fortæller 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
• Område — Løbende ansvarsområder
• Ressource — Referencemateriale (lister, anbefalinger, vejledninger)
• Arkiv — Afsluttede eller annullerede projekter

Når 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 værktøjskald håndterer alt:

1. Arkiverer projektets vektorer (events, decisions, requests knyttet til Barcelona).
2. Invaliderer hvert aktivt vidensgraf-triple hvis prædikat 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 grænsebevidst — et andet projekt kaldet revisit_barcelona forbliver urørt. Agenten skal ikke længere orkestrere tre separate kald i den rigtige rækkefølge, så mindre modeller rammer det også rigtigt.

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

Skills

#

Skills er .md-filer i skills/ der definerer iOS-Shortcuts agenten kan udlose og/eller adfærdsregler. De bruger dynamisk indlæsning: kun et kompakt indeks (titel, beskrivelse, shortcutliste) injiceres i systemprompten. Agenten indlæser fuldt indhold efter behov via load_skill-værktøjet, så tokenforbruget holdes lavt efterhånden 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 også være adfærdsregler uden shortcuts (f.eks. “hvordan man planlægger en familieferie”). Brug shortcuts: [] til disse.

Agenten kan oprette og administrere skills når 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/), så framework-opdateringer aldrig overskriver dem. Se afsnittet Customizing your agent nedenfor.

Udførelse af shortcuts på Mac-serveren

#

Når en skill har target: mac, køres shortcuts stille på 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, påmindelser, kalenderbegivenheder — fordi resultatet automatisk synkroniseres til alle dine enheder, uden at PocketHook-appen skal gøre noget.

Sådan fungerer det:

1. Agenten beslutter at en shortcut skal køre (f.eks. “opret en note med dagens mødenoter”)
2. Serveren kalder shortcuts run "shortcutNavn" med dataene sendt som JSON på stdin, i samme wrapper-format som PocketHook iOS bruger
3. Hvis sync_app er sat, åbner 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 bekræftelsesbesked i chatten; selve shortcut’en sendes ikke til enheden

Krav:

• Serveren skal køre på macOS — shortcuts run findes kun på macOS. På andre platforme logger serveren en advarsel og falder tilbage til enhedsudførelse
• Shortcut’en skal være installeret i Shortcuts.app på Mac-serveren
• Shortcut’en bør forvente en Dictionary som input (PocketHook pakker data ind i { context, timestamp, app, data })

Hvornår du skal bruge target: mac:

• iCloud-synkroniserede handlinger (Notes, Reminders, Calendar) — resultatet når alligevel alle enheder
• Langvarig behandling du vil holde væk fra iOS-enheden
• Enhver shortcut der ikke skal interagere med iPhone’ens brugergrænseflade

Hvornår du skal beholde target: device (standard):

• Shortcuts der skal bruge iPhone-specifikke funktioner (kamera, præcis 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 planlægge opgaver, og den klarer resten:

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

Job understøtter cron-udtryk (0 8 * * *) og enkle intervaller (30m, 1h, 2d). Resultater leveres til PocketHook når den poller /jobs-endepunktet.

To udførelsestyper:

• Shell — Kører en bash-kommando, opfanger output. Kan udlose en Shortcut ved færdiggørelse
• Prompt — Behandlet af AI-agenten med fuld værktøjsadgang, gemmer det komplette PocketHook-svar

Dev-servere

#

Når 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 på en automatisk tildelt port til hurtig visning
• Offentlig — Starter serveren og eksponerer den via HTTPS-tunnel så den er tilgængelig overalt

Agenten styrer livscyklussen: start, stop og list kørende servere. Alle servere ryddes op når hovedserveren stopper.

Tunnelkontrakt

#

Når agenten starter en server med tunneludsættelse anmodet, håndhæver runtimen det: hvis intet tunnelværktøj (Tailscale, ngrok, cloudflared) er installeret, nægter serveren at starte. Hvis tunnelopsætning fejler efter spawn, stoppes den forældreløse proces, og agenten får det udtrykkeligt at vide — så den kan falde tilbage til preview-tilstand eller bede dig installere en tunnel. Den returnerede URL er altid tunnel-URL’en når tunneling er slået til, med en bemærkning om at den lokale URL kun gælder for værten.

Som et sikkerhedsnet efterbehandler hvert respond_*-værktøj sin besked: enhver localhost- eller 127.0.0.1-URL der smutter med i et svar, omskrives automatisk til den matchende tunnel-URL når en administreret server har en. Når det ikke kan omskrive, får du en advarsel i logfilerne i stedet for et brudt link på din telefon.

Dashboard

#

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

Bevidst uautentificeret. Både /dashboard og /api/jobs er åbne GET-endepunkter — enhver der kan nå værten kan liste job. Begræns adgang på netværkslaget (Tailscale-ACL, firewall, reverse proxy med basic auth) eller sæt 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 får et unikt, personaliseret dashboard.

Tilpassede værktøjer

#

Agenten kan installere CLI-værktøjer og registrere dem som nye kapabiliteter — udvider sig selv uden at ændre serverkoden.

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

1. Installere afhængigheden
2. Oprette en værktøjsdefinition (en simpel .md-fil)
3. Bruge det nye værktøj i fremtidige samtaler

Tilpassede værktøjer hot-reloades — ingen genstart nødvendig. Slet .md-filen for at fjerne et værktøj.

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 ændring” eller brug git revert HEAD manuelt
• Konfigurationsfiler — config/agent-instructions.md, config/personality.md, skills/ og permissions.json sikkerhedskopieres før hver ændring. Op til 20 versioner per fil

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

Tilpas din agent

#

Agentserveren leveres med en minimal framework-base og forventer at du lagrer din egen tilpasning oven på. Runtimen holder de to adskilt så framework-opdateringer aldrig ødelægger 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 værktøjer (create_user_skill, create_custom_tool), så de resulterende filer altid matcher loaderens format. write-værktøjet afviser også enhver sti under skills/, custom-tools/ eller config/ og dirigerer agenten til data/user/* — så selv direkte filredigeringer ender i brugerlaget.

Bemærk om base-mappen custom-tools/. I dag indeholder den kun en skabelon (_example.md) som loaderen ignorerer — ethvert værktøj agenten installerer for dig, havner i data/user/custom-tools/. Mappen er reserveret, så fremtidige framework-udgivelser kan levere valgfri indbyggede værktøjer uden at ødelægge dine installationer. Når det sker, vinder dine brugerlag-filer stadig ved navnekollision, så der er intet at migrere.

Fire måder at tilpasse på

#

Du behøver aldrig at skrive disse filer i hånden. Fortæl blot agenten hvad du vil have, og den vælger det rigtige lag automatisk.

Typede præferencer med {{prefs.*}}

#

Sig at du skriver en ruteplanlægger-skill der skal kende dit standardudgangspunkt. I stedet for at hardcode “Madrid” i selve skill’en, referer til præferencen:

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

Og gem værdien i data/user/prefs.json:

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

Serveren indsætter pladsholdere når skill’en indlæses. Indlejrede nøgler ({{prefs.tunnel.domain}}) virker også. Ukendte nøgler efterlades urørte, så 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 når du bruger en fil-editor. Men agenten vil ikke skrive til de stier fra en samtale. Og framework-opdateringer vil overskrive dine redigeringer. Foretræk brugerlaget til alt du vil beholde.

Udvid serveren

#

• Tilpassede værktøjer — Bed agenten om at installere CLI-værktøjer; de lander automatisk i data/user/custom-tools/
• Tilføj skills — Bed agenten om at oprette en skill; filen ryger i data/user/skills/
• Ændr adfærd — Bed agenten om at anvende en global regel; den tilføjes i data/user/instructions.md
• Konfigurer tilladelser — Kør bun run permissions for at styre hvilke værktøjer agenten kan bruge
• Tilføj indbyggede værktøjer — Implementer nye værktøjsfunktioner i src/tools.ts for dybere integrationer (kræver fork af serveren)

Konfiguration

#

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

Se den fulde konfigurationsreference i GitHub-repositoryet.

Kør som service

#

Installer som persistent service der starter automatisk:

bun run service install

INSTANCE_NAME er som standard projektmappens basisnavn med pockethook--præfikset fjernet (f.eks. bliver et checkout i pockethook-agent-server/ til agent-server). Sæt det eksplicit for at køre flere checkouts på samme maskine uden kollisioner — hver instans beholder sit eget data/ og logs.

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

Sikkerhed

#

• HTTPS påkrævet — PocketHook kræver HTTPS for alle URLs
• Bearer-token-godkendelse — Delt hemmelighed mellem app og server
• Rate limiting — Per-token grænser forhindrer misbrug
• Sandboxed værktøjer — Shell-kommandoer og filadgang begrænset af tilladelser
• Blokerede mønstre — Farlige kommandoer (sudo, rm -rf /) blokeret som standard
• Arbejdsmappe-grænse — Agenten kan ikke forlade sin tildelte mappe
• Følsomme filer beskyttet — .env, .git, *.key, *.pem blokeret fra agentadgang
• Automatisk versionering — Alle workspace-ændringer git-spores for nem tilbagerulning