Agentserver

Vad aer PocketHook Agent Server?

#

Agentservern goer PocketHook till en fullstaendig AI-assistent. Istaellet foer att skriva responslogik sjaelv ansluter du en LLM (Claude, GPT, Gemini osv.) som bearbetar meddelanden, anropar verktyg och returnerar strukturerade PocketHook-svar — inklusive Shortcut-triggers.

Servern koers paa din egen maskin. Dina data stannar hos dig.

Detta aer en startpunkt. Servern levereras med en grunduppsaettning verktyg och aer designad foer att utvidgas av dig. Laegg till dina egna integrationer — e-post, kalendrar, dokument, APIs — och goer den till din.

Funktioner

#

• Multi-provider LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• OAuth-autentisering — GitHub Copilot och OpenAI Codex via device-code-/webblaesarflow
• Agentverktyg — Shell-kommandon, fillaesning/skrivning, kataloglistning, webbsoekning, web scraping, dev-serverhantering
• Ramverks-/anvaendaruppdelning — Ramverksfiler (skills/, custom-tools/, config/) foerblir skrivskyddade. Dina anpassningar bor under data/user/ (skills, anpassade verktyg, instruktioner, typade preferenser). Ramverksuppdateringar landar rent utan att skriva oever ditt arbete
• Typade anvaendarpreferenser — Lagra vaerden som din foredragna kartapp eller tunneldomaen i data/user/prefs.json. Referera till dem i skills som {{prefs.key}}, och servern saetter in dem vid laddning
• Programmeringsuppgifter i ett anrop — Meta-verktyget run_code_job skapar ett bakgrundsjobb av prompt-typ (koert av din konfigurerade LLM) och skickar anvaendaren bekraeftelsen i ett steg, och ersaetter det felbenaegna moenstret “respond + create-job”
• Typade protokollverktyg — Sex dedikerade respond_*-verktyg (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus typade jobbverktyg (create_once_job, create_cron_job) och typade workspace-verktyg (create_project, list_projects, delete_project). Scheman avvisar felaktiga URL:er, knappsyntax och type/schedule-kombinationer innan de naar enheten
• Typade skribenter foer anpassning — create_user_skill och create_custom_tool bygger anvaendarlagrets markdown med korrekt frontmatter, saa laddaren alltid parsar dem och agenten aldrig skriver dessa filer foer hand
• Bakgrundsjobb — Engaangs- eller aaterkommande uppgifter med cron-uttryck eller enkla intervall
• Dynamiska skills — Definiera Shortcuts och beteenderegler som .md-filer. Bara ett kompakt index laaddas i prompten; fullstaendigt innehaall haemtas vid behov via load_skill-verktyget
• Sjaelvhanterande skills — Agenten kan skapa, redigera och ta bort skilldefinitioner (skrivningar landar alltid i anvaendarlagret)
• Semantiskt minne — Vektorbaserad soekning med embeddings (Ollama, LM Studio eller OpenAI). Minnen klassificeras automatiskt av LLM:et i wing/room/hall/status-dimensioner
• Kunskapsgraf — Temporalt triple-store foer varaktiga fakta med automatisk invalidering. Multivaerelationer samexisterar; enkelvaerefakta ersaetts automatiskt
• PARA-metoden med projektavslutnings-kaskad — Varje minne taggas med en status (Projekt, Omraade, Resurs, Arkiv). Naer ett projekt avslutas arkiverar ett enda complete_project-anrop dess vektorer, invaliderar varje planeringstripel knuten till projektets slug och registrerar slutfoerandet — ett anrop i staelet foer tre
• Hybrid recall — Kombinerar FTS5-soekordssoekning med vektor-semantisk soekning via reciprocal rank fusion
• Laangtidsminne — SQLite + FTS5-fulltextsoekning som fallback naer semantiskt minne aer inaktiverat
• Dev-serverhantering med tunnelkontrakt — Starta, stoppa och lista dev-servrar. Naer tunnel: true begaers, genomdriver servern det baade foere flight och efter spawn — en onabar localhost-server laemnas aldrig tyst i gaang
• Automatisk URL-sanering — Om agenten laemnar en localhost-URL i ett svar skriver respond_*-verktygen om den till den matchande tunnel-URL:en, saa din telefon alltid faar en naabar laenk
• Anpassade verktyg — Agenten kan installera CLI-verktyg och registrera dem som nya foermaagar
• Versionshantering — Automatisk git-versionshantering foer workspace-filer; konfigurationssaekerhetskopiering foer skills och behorigheter
• Webbdashboard — Live-oeversikt oever bakgrundsjobb, anpassningsbart per anvaendare. /dashboard och /api/jobs aer avsiktligt oautentiserade — begraensa aatkomst paa naetverkslagret (Tailscale-ACL, brandvaegg, reverse proxy med basic auth) eller saett DASHBOARD=false om du inte behoever den
• HTTPS-tunnling — Inbyggt stoed foer Tailscale, ngrok och Cloudflare Tunnel
• Systemtjaenst — Installera som persistent tjaenst paa macOS, Linux eller Windows
• Rate limiting — Per-token begraensningar med konfigurerbara troesklar

Krav

#

• Bun runtime
• En API-nyckel eller OAuth-uppgifter foer din LLM-leverantoer
• (Valfritt) Tailscale, ngrok eller cloudflared foer HTTPS-tunnling

Snabbstart

#

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

# Interaktiv installation — vaelj leverantoer, modell, auth-token, port
bun run setup

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

Installationsguiden vagleder dig genom valet av LLM-leverantoer, konfiguration av autentisering och instaellning av verktygsbehorigheter.

Naer servern koers, kopiera de visade URL:erna till PocketHook-instaellningar:

Hur det fungerar

#

1. Du skickar ett meddelande i PocketHook
2. Servern vidarebefordrar det till din valda LLM med konversationshistorik, haemtade minnen och tillgaengliga verktyg
3. LLM:et bearbetar meddelandet — det kan koera shell-kommandon, laesa/skriva filer, soeka paa webben, schemalaegg bakgrundsjobb, minnas fakta eller starta dev-servrar
4. Svaret returneras i PocketHook-format (msg + shortcut + data + url)
5. PocketHook visar meddelandet och koer alla Shortcuts paa din enhet

Stoedda LLM-leverantoerer

#

Byt leverantoer naer som helst med bun run switch. Ollama och LM Studio koers helt paa din maskin — ingen API-nyckel behoevs, inga data laemnar ditt naetverk.

Minne

#

Minnessystemet har tre lager, vart och ett med ett olika syfte.

Designen av det semantiska minnet kombinerar ideer fraan MemPalace (en minnespalats-arkitektur som organiserar minnen i wings, halls och rooms) och Tiago Fortes PARA-metod (Projekt, Omraaden, Resurser, Arkiv) foer kunskapslivscykelhantering.

Konversationsminne

#

SQLite med FTS5-fulltextsoekning. Alla meddelanden lagras med tidsstaeemplar och sessions-ID:n.

• Kortsiktigt — Senaste MAX_HISTORY meddelanden haalls i minnet per session
• Laangsiktigt — Alla meddelanden sparade i SQLite, soekbara via FTS5-soekordsmatchning
• Recall per tur — Naer semantiskt minne aer paa styr MAX_RECALL hur maanga relevanta minnen som injiceras i prompten varje tur
• Sessioner gaar ut efter SESSION_TTL_MINUTES, men laangtidsminnet bestaaar foer alltid

Justera dessa interaktivt med bun run memory.

Semantiskt minne

#

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

Varje minne baeddas in som en vektor och klassificeras automatiskt av LLM:et i fyra dimensioner:

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

Naer du staeller en fraaga fokuserar entitetsextraktion vektorsoekningen paa de mest relevanta wings. Resultat sammanfogas med FTS5-soekordresultat via reciprocal rank fusion — saa du faar det baesta av baade soekords- och semantisk soekning.

Kunskapsgraf

#

Ett temporalt triple-store foer strukturerade, varaktiga fakta:

• Tripplar: (subjekt, predikat, objekt) med valid_from / valid_until tidsstaeemplar
• Enkelvaerde-predikat (lives_in, partner) invaliderar automatiskt det gamla vaerdet vid uppdatering
• Multivaerde-predikat (child, friend, hobby) samexisterar utan invalidering
• Kunskapsgraffakta injiceras tillsammans med haemtade minnen i varje konversation

Naer du beraetar foer agenten “Jag har flyttat till Berlin”, invaliderar den den gamla lives_in-trippeln och skapar en ny — automatiskt.

PARA-livscykel

#

Varje minne taggas med en PARA-status:

• Projekt — Aktivt, tidsbundet arbete
• Omraade — Paagaaende ansvarsomraaden
• Resurs — Referensmaterial (listor, rekommendationer, guider)
• Arkiv — Avslutade eller avbrutna projekt

Naer ett projekt avslutas anvaender agenten semantisk likhet foer att bara arkivera det projektets minnen medan referensmaterial bevaras foer framtida bruk.

Projektavslutnings-kaskad

#

Saeg “Jag staeller in min resa till Barcelona”, och ett enda verktygsanrop skoeter allt:

1. Arkiverar projektets vektorer (events, decisions, requests knutna till Barcelona).
2. Invaliderar varje aktivt kunskapsgraf-tripel vars predikat matchar projektets slug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registrerar slutfoerandet som ett nytt tripel: (user, "cancelled_visit_barcelona", "2026-04-15").

Matchningen aer graensmedveten — ett annat projekt som heter revisit_barcelona foerblir oroert. Agenten behoever inte laengre orkestrera tre separata anrop i raett ordning, saa mindre modeller klarar det ocksaa.

Om VECTOR_MEMORY aer inaktiverat eller embedding-leverantoeren aer onabar, faller systemet tillbaka till FTS5-only utan fel.

Skills

#

Skills aer .md-filer i skills/ som definierar iOS-Shortcuts agenten kan utloesa och/eller beteenderegler. De anvaender dynamisk laddning: bara ett kompakt index (titel, beskrivning, shortcutlista) injiceras i systemprompten. Agenten laddar fullstaendigt innehaall vid behov via load_skill-verktyget, saa tokenanvaendningen haalls laag naer du laegger till fler skills.

Varje skillfil anvaender 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-faelt

#

Skills kan ocksaa vara beteenderegler utan shortcuts (t.ex. “hur man planerar en familjeresa”). Anvaend shortcuts: [] foer dessa.

Agenten kan skapa och hantera skills naer du ber om det — be den att “skapa en skill foer att styra mina lampor” och den skriver .md-filen aat dig. Nya och redigerade skills landar alltid i ditt anvaendarlager (data/user/skills/), saa ramverksuppdateringar skriver aldrig oever dem. Se avsnittet Customizing your agent nedan.

Koera shortcuts paa Mac-servern

#

Naer en skill har target: mac koerts shortcuts tyst paa Mac-servern via CLI-verktyget shortcuts run i staelet foer att skickas till iOS-enheten. Det aer idealiskt foer aatgaerder som skapar iCloud-synkat innehaall — anteckningar, paaminnelser, kalenderhaendelser — eftersom resultatet synkas till alla dina enheter automatiskt utan att PocketHook-appen behoeer goera naagot.

Saa haer fungerar det:

1. Agenten bestaemmer att en shortcut ska koera (t.ex. “skapa en anteckning med dagens moetesanteckningar”)
2. Servern anropar shortcuts run "shortcutNamn" med datan skickad som JSON paa stdin, i samma wrapper-format som PocketHook iOS anvaender
3. Om sync_app aer satt oppnar servern kortfattat den appen i bakgrunden (open -gj -a Notes) foer att tvinga iCloud-synkronisering, och staenger den sedan efter 5 sekunder
4. Anvaendaren faar ett bekraeftelsemeddelande i chatten; sjaelva shortcut’en skickas inte till enheten

Krav:

• Servern maaste koera paa macOS — shortcuts run finns bara paa macOS. Paa andra plattformar loggar servern en varning och faller tillbaka till enhetskoerning
• Shortcut’en maaste vara installerad i Shortcuts.app paa Mac-servern
• Shortcut’en ska foerv-ta ett Dictionary som indata (PocketHook packar in datan i { context, timestamp, app, data })

Naer du ska anvaenda target: mac:

• iCloud-synkade aatgaerder (Notes, Reminders, Calendar) — resultatet naar aendaa alla enheter
• Laangvarig bearbetning du vill haalla borta fraan iOS-enheten
• Alla shortcuts som inte behoeer interagera med iPhone’ns anvaendargraenssnitt

Naer du ska behaalla target: device (standard):

• Shortcuts som behoeer iPhone-specifika funktioner (kamera, exakt plats, lokala app-automatiseringar)
• Shortcuts som ber anvaendaren om interaktiv inmatning
• Shortcuts som anvaender App Intents fraan iOS-enbart-appar

Bakgrundsjobb

#

Be agenten att schemalaegg uppgifter och den skoeter resten:

• “Kontrollera vaedret varje morgon kl. 8 och skapa en anteckning”
• “Koer det haer skriptet varje timme”
• “Paeminn mig att kolla min e-post om 30 minuter”

Jobb stoeder cron-uttryck (0 8 * * *) och enkla intervall (30m, 1h, 2d). Resultat levereras till PocketHook naer den pollar /jobs-slutpunkten.

Tvaa koerningstyper:

• Shell — Koer ett bash-kommando, faangar utdata. Kan utloesa en Shortcut vid slutfoerande
• Prompt — Bearbetas av AI-agenten med full verktygstillgaang, lagrar det kompletta PocketHook-svaret

Dev-servrar

#

Naer agenten skapar ett webbprojekt i workspace:t (Hugo, Astro, Next.js, Flask, Go osv.) erbjuder den proaktivt att servera det:

• Foerhandsgranskning — Startar en lokal dev-server paa en automatiskt tilldelad port foer snabb visning
• Offentlig — Startar servern och exponerar den via HTTPS-tunnel saa den aer tillgaenglig oeverallt

Agenten hanterar livscykeln: starta, stoppa och lista koerande servrar. Alla servrar staedas upp naer huvudservern stoppas.

Tunnelkontrakt

#

Naer agenten startar en server med tunnelexponering begaerd genomdriver koertiden det: om inget tunnelverktyg (Tailscale, ngrok, cloudflared) aer installerat vaegrar servern att starta. Om tunnelupplaegget misslyckas efter spawn stoppas den foeraeldraloesa processen och agenten faar explicit besked — saa den kan falla tillbaka till foerhandsgranskning eller be dig installera en tunnel. Den returnerade URL:en aer alltid tunnel-URL:en naer tunneling aer paa, med en notering om att den lokala URL:en endast gaeller foer vaerden.

Som skyddsnaet efterbehandlar varje respond_*-verktyg sitt meddelande: varje localhost- eller 127.0.0.1-URL som smyger sig in i ett svar skrivs automatiskt om till den matchande tunnel-URL:en naer en hanterad server har en. Naer det inte kan skrivas om faar du en varning i loggarna i staelet foer en trasig laenk paa telefonen.

Dashboard

#

Den inbyggda webbdashboarden paa /dashboard visar en live-oeversikt oever bakgrundsjobb.

Avsiktligt oautentiserad. Baade /dashboard och /api/jobs aer oeppna GET-slutpunkter — vem som helst som naar vaerden kan lista jobb. Begraensa aatkomst paa naetverkslagret (Tailscale-ACL, brandvaegg, reverse proxy med basic auth) eller saett DASHBOARD=false om du inte behoever den. PocketHook iOS-appen anvaender inte dessa slutpunkter.

Den aer helt anpassningsbar:

• Snabbredigering — Placera en dashboard.html i workspace/dashboard/ foer enkla anpassningar
• Fullt projekt — Skapa ett ramverksprojekt (Svelte, React, Vue osv.) i workspace/dashboard/ med build-utdata till dist/

Be agenten att anpassa din dashboard och den skoeter resten — varje anvaendare faar en unik, personaliserad dashboard.

Anpassade verktyg

#

Agenten kan installera CLI-verktyg och registrera dem som nya foermaagar — utvidgar sig sjaelv utan att aendra serverkoden.

Saeg till exempel “installera Playwright och anvaend det foer att ta skaermbilder”. Agenten kommer att:

1. Installera beroendet
2. Skapa en verktygsdefinition (en enkel .md-fil)
3. Anvaenda det nya verktyget i framtida konversationer

Anpassade verktyg laddas om direkt — ingen omstart behoevs. Ta bort .md-filen foer att ta bort ett verktyg.

Versionshantering

#

All anvaendardata versionshanteras automatiskt:

• Workspace-filer — Spaarade med ett lokalt git-repo inuti workspace/. Varje skrivning skapar en auto-commit. Be agenten att “aangra den senaste aendringen” eller anvaend git revert HEAD manuellt
• Konfigurationsfiler — config/agent-instructions.md, config/personality.md, skills/ och permissions.json saekerhetskopieras foere varje aendring. Upp till 20 versioner per fil

Git aer valfritt — om det inte aer installerat aer workspace-aendringar inte versionshanterade. Konfigurationssaekerhetskopiering fungerar alltid.

Anpassa din agent

#

Agentservern levereras med en minimal ramverksbas och foervaentar sig att du laegger din egen anpassning ovanpaa. Koertiden haaller de tvaa aatskilda saa ramverksuppdateringar aldrig foerstoer ditt arbete.

Ramverk vs anvaendare

#

pockethook-agent-server/
├── skills/                      # ramverksleverade skills (skrivskyddat)
├── custom-tools/                # reserverat foer ramverksleverade verktyg (skrivskyddat)
├── config/
│   ├── agent-instructions.md    # ramverkets agentinstruktioner (skrivskyddat)
│   └── personality.md           # ramverkets personlighet (skrivskyddat)
└── data/user/                   # DIN anpassning bor haer (git-ignorerad)
    ├── skills/                  # dina egna skills (oeverrider basen paa filnamn)
    ├── custom-tools/            # dina installerade anpassade verktyg
    ├── instructions.md          # dina tillaegg till agentinstruktionerna
    └── prefs.json               # typade vaerden refererade som {{prefs.key}}

Anvaendaranpassning skrivs via dedikerade typade verktyg (create_user_skill, create_custom_tool) saa de resulterande filerna alltid matchar laddarens format. write-verktyget avvisar ocksaa varje soekvaeg under skills/, custom-tools/ eller config/ och dirigerar om agenten till data/user/* — saa aeven direkta filaendringar hamnar i anvaendarlagret.

Notering om bas-katalogen custom-tools/. Idag innehaaller den bara en mall (_example.md) som laddaren ignorerar — varje verktyg agenten installerar aat dig hamnar i data/user/custom-tools/. Katalogen aer reserverad saa framtida ramverksslaepp kan leverera valfria inbyggda verktyg utan att foerstoera dina installationer. Naer det haender vinner dina anvaendarlager-filer fortfarande vid namnkollision, saa det finns inget att migrera.

Fyra saett att anpassa paa

#

Du behoever aldrig skriva dessa filer foer hand. Saeg bara till agenten vad du vill ha, saa vaeljer den raett lager automatiskt.

Typade preferenser med {{prefs.*}}

#

Saeg att du skriver en ruttplanerar-skill som behoever veta din standardstartpunkt. I staelet foer att hardkoda “Madrid” i sjaelva skillen, referera till preferensen:

- **Startpunkt**: {{prefs.routeOrigin}}, saavida anvaendaren inte anger en annan startpunkt.

Och lagra vaerdet i data/user/prefs.json:

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

Servern saetter in plats-haallare naer skillen laddas. Naestlade nycklar ({{prefs.tunnel.domain}}) fungerar ocksaa. Okaenda nycklar laemnas oroerda saa typos foerblir synliga.

Redigera ramverksbasen direkt

#

Om du sjaelvhostar och vill pilla med sjaelva ramverket kan du redigera config/agent-instructions.md, config/personality.md, skills/ eller custom-tools/ direkt — servern stoppar dig inte naer du anvaender en filredigerare. Men agenten kommer inte att skriva till de soekvaegarna fraan en konversation. Och ramverksuppdateringar kommer att skriva oever dina aendringar. Foeredra anvaendarlagret foer allt du vill behaalla.

Utvidga servern

#

• Anpassade verktyg — Be agenten att installera CLI-verktyg; de hamnar automatiskt i data/user/custom-tools/
• Laegg till skills — Be agenten att skapa en skill; filen hamnar i data/user/skills/
• Aendra beteende — Be agenten att tillaempa en global regel; den laeggs till i data/user/instructions.md
• Konfigurera behorigheter — Koer bun run permissions foer att styra vilka verktyg agenten kan anvaenda
• Laegg till inbyggda verktyg — Implementera nya verktygsfunktioner i src/tools.ts foer djupare integrationer (kraever en fork av servern)

Konfiguration

#

Alla instaellningar lagras i .env (skapad av bun run setup). Viktiga alternativ:

Se den fullstaendiga konfigurationsreferensen i GitHub-repositoryt.

Koera som tjaenst

#

Installera som persistent tjaenst som startar automatiskt:

bun run service install

INSTANCE_NAME aer som standard projektkatalogens basnamn med pockethook--prefixet borttaget (t.ex. blir en checkout i pockethook-agent-server/ till agent-server). Saett det explicit foer att koera flera checkouts paa samma maskin utan kollisioner — varje instans behaaller sina egna data/ och loggar.

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

Saekerhet

#

• HTTPS kraevs — PocketHook kraever HTTPS foer alla URL:er
• Bearer-token-autentisering — Delad hemlighet mellan app och server
• Rate limiting — Per-token begraensningar foerhindrar missbruk
• Sandboxade verktyg — Shell-kommandon och filaakomst begraensade av behorigheter
• Blockerade moenster — Farliga kommandon (sudo, rm -rf /) blockerade som standard
• Arbetskataloggraens — Agenten kan inte laemna sin tilldelade katalog
• Kaensliga filer skyddade — .env, .git, *.key, *.pem blockerade fraan agentaakomst
• Automatisk versionshantering — Alla workspace-aendringar git-spaaras foer enkel aaterstaellning