Agentserver

Hva er PocketHook Agent Server?

#

Agentserveren gjør PocketHook til en fullverdig AI-assistent. I stedet for å skrive responslogikk selv, kobler du til en LLM (Claude, GPT, Gemini osv.) som behandler meldinger, kaller verktøy og returnerer strukturerte PocketHook-svar — inkludert Shortcut-utløsere.

Serveren kjører på din egen maskin. Dataene dine forblir hos deg.

Dette er et utgangspunkt. Serveren leveres med et kjernesett med verktøy og er designet for å utvides av deg. Legg til dine egne integrasjoner — e-post, kalendere, dokumenter, APIer — og gjør den til din.

Funksjoner

#

• Multi-leverandør LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokal), LM Studio (lokal)
• Rask modell — Kjør en lettvekts sekundær modell for interne hjelpere (minneklassifisering, entitetsutvinning) sammen med hovedchatmodellen din — full kontroll over kostnad og latens
• Safari-utvidelse — Parre en notarisert macOS Safari-utvidelse slik at agenten kan åpne faner, inspisere sider, klikke, fylle ut skjemaer og ta skjermbilder i den ekte nettleserøkten din, på et tillatelsesnivå du velger
• OAuth-autentisering — GitHub Copilot og OpenAI Codex via enhetskode-/nettleserflyt
• Agentverktøy — Shell-kommandoer, fillesing/skriving, katalogoppføring, websøk, web scraping, dev-serveradministrasjon
• Rammeverk/bruker-deling — Rammeverksfiler (skills/, custom-tools/, config/) forblir skrivebeskyttet. Dine tilpasninger bor under data/user/ (ferdigheter, tilpassede verktøy, instruksjoner, typede preferanser). Rammeverksoppdateringer lander rent uten å overskrive arbeidet ditt
• Typede brukerpreferanser — Lagre verdier som din foretrukne kartapp eller tunneldomene i data/user/prefs.json. Referer til dem i ferdigheter som {{prefs.key}}, og serveren setter dem inn ved innlasting
• Programmeringsoppgaver i ett kall — Meta-verktøyet run_code_job oppretter en bakgrunnsjobb av prompt-typen (kjørt av din konfigurerte LLM) og sender brukeren bekreftelsen i ett trinn, og erstatter det feilutsatte mønsteret “respond + create-job”
• Typede protokollverktøy — Seks dedikerte respond_*-verktøy (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), pluss typede jobbverktøy (create_once_job, create_cron_job) og typede workspace-verktøy (create_project, list_projects, delete_project). Skjemaer avviser feilformede URL-er, knappesyntaks og type/schedule-kombinasjoner før de når enheten
• Typede skribenter for tilpasning — create_user_skill og create_custom_tool bygger brukerlagets markdown med korrekt frontmatter, så lasteren alltid parser dem og agenten aldri skriver disse filene for hånd
• Bakgrunnsjobber — Engangs- eller gjentagende oppgaver med cron-uttrykk eller enkle intervaller
• Dynamiske ferdigheter — Definer Shortcuts og atferdsregler som .md-filer. Bare en kompakt indeks lastes inn i prompten; fullt innhold hentes på forespørsel via load_skill-verktøyet
• Selvadministrerende ferdigheter — Agenten kan opprette, redigere og slette ferdighetsdefinisjoner (skrivinger lander alltid i brukerlaget)
• Semantisk minne — Vektorbasert søk med embeddings (Ollama, LM Studio eller OpenAI). Minner klassifiseres automatisk av LLM-en i wing/room/hall/status-dimensjoner
• Kunnskapsgraf — Temporalt triple-store for varige fakta med automatisk invalidering. Flerverdi-relasjoner sameksisterer; enkeltverdi-fakta erstattes automatisk
• PARA-metoden med prosjektavslutnings-kaskade — Hvert minne tagges med en status (Prosjekt, Område, Ressurs, Arkiv). Når et prosjekt avsluttes, arkiverer ett enkelt complete_project-kall vektorene, ugyldiggjør hvert planleggingstriple knyttet til prosjektets slug og registrerer fullførelsen — ett kall i stedet for tre
• Hybrid gjenkalling — Kombinerer FTS5-søkeordssøk med vektor-semantisk søk ved hjelp av reciprocal rank fusion
• Langtidsminne — SQLite + FTS5-fulltekstsøk som fallback når semantisk minne er deaktivert
• Dev-serveradministrasjon med tunnelkontrakt — Start, stopp og list dev-servere. Når tunnel: true bes om, håndhever serveren det både før-flyving og etter-spawn — en utilgjengelig localhost-server blir aldri stående stille i gang
• Automatisk URL-rensing — Hvis agenten etterlater en localhost-URL i et svar, skriver respond_*-verktøyene den om til den matchende tunnel-URL-en, så telefonen din alltid får en nåbar lenke
• Tilpassede verktøy — Agenten kan installere CLI-verktøy og registrere dem som nye evner
• Versjonering — Automatisk git-versjonering for workspace-filer; konfigurasjonsbackup for ferdigheter og tillatelser
• Webdashbord — Live-oversikt over bakgrunnsjobber, tilpassbart per bruker. /dashboard og /api/jobs er bevisst uautentiserte — begrens tilgang på nettverkslaget (Tailscale-ACL, brannmur, reverse proxy med basic auth) eller sett DASHBOARD=false hvis du ikke trenger det
• HTTPS-tunneling — Innebygd støtte for Tailscale, ngrok og Cloudflare Tunnel
• Systemtjeneste — Installer som persistent tjeneste på macOS, Linux eller Windows
• Frekvensbegrensning — Per-token forespørselsgrenser med konfigurerbare terskler

Krav

#

• Bun runtime
• En API-nøkkel eller OAuth-legitimasjon for LLM-leverandøren din
• (Valgfritt) Tailscale, ngrok eller cloudflared for HTTPS-tunneling

Hurtigstart

#

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

# Interaktivt oppsett — velg leverandør, modell, auth-token, port
bun run setup

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

Oppsettsveiviseren guider deg gjennom valg av LLM-leverandør, konfigurering av autentisering og oppsett av verktøytillatelser — inkludert om Safari-utvidelsen skal installeres (valgfritt, kan hoppes over, kun macOS).

Kjør bun run help når som helst for en full liste over kommandoer, eller bun run config for å se gjeldende konfigurasjon på et blunk (hemmeligheter maskert).

Når serveren kjører, kopier de viste URL-ene til PocketHook-innstillinger:

Hvordan det fungerer

#

1. Du sender en melding i PocketHook
2. Serveren videresender den til din valgte LLM med samtalehistorikk, hentede minner og tilgjengelige verktøy
3. LLM-en behandler meldingen — den kan kjøre shell-kommandoer, lese/skrive filer, søke på nettet, planlegge bakgrunnsjobber, huske fakta eller starte dev-servere
4. Svaret returneres i PocketHook-format (msg + shortcut + data + url)
5. PocketHook viser meldingen og kjører alle Shortcuts på enheten din

Støttede LLM-leverandører

#

Bytt leverandør når som helst med bun run switch. Ollama og LM Studio kjører helt på maskinen din — ingen API-nøkkel nødvendig, ingen data forlater nettverket ditt.

Minne

#

Minnesystemet har tre lag, som hver tjener et ulikt formål.

Designet av det semantiske minnet kombinerer ideer fra MemPalace (en minnepalassarkitektur som organiserer minner i wings, halls og rooms) og Tiago Fortes PARA-metode (Prosjekter, Områder, Ressurser, Arkiv) for kunnskapslivssyklusstyring.

Samtaleminne

#

SQLite med FTS5-fulltekstsøk. Alle meldinger lagres med tidsstempler og sesjons-IDer.

• Korttid — Siste MAX_HISTORY meldinger holdt i minnet per sesjon
• Langtid — Alle meldinger lagret i SQLite, søkbare via FTS5-søkeordmatching
• Gjenkalling per tur — Når semantisk minne er på, styrer MAX_RECALL hvor mange relevante minner som injiseres i prompten hver tur
• Sesjoner utløper etter SESSION_TTL_MINUTES, men langtidsminnet består for alltid

Juster disse interaktivt med bun run memory.

Semantisk minne

#

Krever VECTOR_MEMORY=true og en embedding-leverandør (Ollama, LM Studio eller OpenAI).

Hvert minne integreres som en vektor og klassifiseres automatisk av LLM-en i fire dimensjoner:

• 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-klassifisering: project, area, resource, archive

Når du stiller et spørsmål, fokuserer entitetsekstraksjon vektorsøket på de mest relevante wings. Resultater slås sammen med FTS5-søkeordresultater via reciprocal rank fusion — så du får det beste av både søkeords- og semantisk søk.

Kunnskapsgraf

#

Et temporalt triple-store for strukturerte, varige fakta:

• Tripler: (subjekt, predikat, objekt) med valid_from / valid_until tidsstempler
• Enkeltverdi-predikater (lives_in, partner) ugyldiggjør automatisk den gamle verdien ved oppdatering
• Flerverdi-predikater (child, friend, hobby) sameksisterer uten ugyldiggjøring
• Kunnskapsgraffakta injiseres sammen med hentede minner i hver samtale

Når du forteller agenten “Jeg har flyttet til Berlin”, ugyldiggjør den det gamle lives_in-trippelet og oppretter et nytt — automatisk.

PARA-livssyklus

#

Hvert minne tagges med en PARA-status:

• Prosjekt — Aktivt, tidsbundet arbeid
• Område — Pågående ansvarsområder
• Ressurs — Referansemateriale (lister, anbefalinger, veiledninger)
• Arkiv — Fullførte eller avbrutte prosjekter

Når et prosjekt fullføres, bruker agenten semantisk likhet for å bare arkivere det prosjektets minner mens referansemateriale bevares for fremtidig bruk.

Prosjektavslutnings-kaskade

#

Si “Jeg avbestiller turen min til Barcelona”, og ett enkelt verktøykall håndterer alt:

1. Arkiverer prosjektets vektorer (events, decisions, requests knyttet til Barcelona).
2. Ugyldiggjør hvert aktive kunnskapsgraftriple hvis predikat matcher prosjektets slug (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
3. Registrerer fullførelsen som et nytt triple: (user, "cancelled_visit_barcelona", "2026-04-15").

Matchingen er grensebevisst — et annet prosjekt kalt revisit_barcelona blir urørt. Agenten trenger ikke lenger å orkestrere tre separate kall i riktig rekkefølge, så mindre modeller får det også til.

Hvis VECTOR_MEMORY er deaktivert eller embedding-leverandøren er utilgjengelig, faller systemet feilfritt tilbake til FTS5-only.

Ferdigheter

#

Ferdigheter er .md-filer i skills/ som definerer iOS-Shortcuts agenten kan utløse og/eller atferdsregler. De bruker dynamisk lasting: bare en kompakt indeks (tittel, beskrivelse, shortcutliste) injiseres i systemprompten. Agenten laster fullt innhold på forespørsel via load_skill-verktøyet, så tokenforbruket holdes lavt når du legger til flere ferdigheter.

Hver ferdighetsfil bruker 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

#

Ferdigheter kan også være atferdsregler uten shortcuts (f.eks. “hvordan planlegge en familieferie”). Bruk shortcuts: [] for disse.

Agenten kan opprette og administrere ferdigheter når du ber om det — be den om å “opprette en ferdighet for å styre lysene mine” og den skriver .md-filen for deg. Nye og redigerte ferdigheter lander alltid i brukerlaget ditt (data/user/skills/), så rammeverksoppdateringer aldri overskriver dem. Se avsnittet Customizing your agent nedenfor.

Kjøre shortcuts på Mac-serveren

#

Når en ferdighet har target: mac, kjøres shortcuts stille på Mac-serveren via CLI-verktøyet shortcuts run i stedet for å sendes til iOS-enheten. Dette er ideelt for handlinger som oppretter iCloud-synkronisert innhold — notater, påminnelser, kalenderhendelser — fordi resultatet synkroniseres til alle enhetene dine automatisk uten at PocketHook-appen må gjøre noe.

Slik fungerer det:

1. Agenten bestemmer at en shortcut skal kjøres (f.eks. “opprett et notat med dagens møteopptak”)
2. Serveren kaller shortcuts run "shortcutNavn" med dataene sendt som JSON på stdin, i samme wrapper-format som PocketHook iOS bruker
3. Hvis sync_app er satt, åpner serveren kort den appen i bakgrunnen (open -gj -a Notes) for å tvinge iCloud-synkronisering, og lukker den etter 5 sekunder
4. Brukeren mottar en bekreftelsesmelding i chatten; selve shortcut’en sendes ikke til enheten

Krav:

• Serveren må kjøre på macOS — shortcuts run finnes kun på macOS. På andre plattformer logger serveren en advarsel og faller tilbake til enhetskjøring
• Shortcut’en må være installert i Shortcuts.app på Mac-serveren
• Shortcut’en bør forvente et Dictionary som inndata (PocketHook pakker data inn i { context, timestamp, app, data })

Når du bør bruke target: mac:

• iCloud-synkroniserte handlinger (Notes, Reminders, Calendar) — resultatet når uansett alle enheter
• Langvarig behandling du vil holde unna iOS-enheten
• Alle shortcuts som ikke trenger å interagere med iPhone’s brukergrensesnitt

Når du bør beholde target: device (standard):

• Shortcuts som trenger iPhone-spesifikke funksjoner (kamera, nøyaktig posisjon, lokale app-automatiseringer)
• Shortcuts som ber brukeren om interaktiv input
• Shortcuts som bruker App Intents fra iOS-kun-apper

Bakgrunnsjobber

#

Be agenten om å planlegge oppgaver, og den ordner resten:

• “Sjekk været hver morgen klokken 8 og lag et notat”
• “Kjør dette skriptet hver time”
• “Minn meg på å sjekke e-posten min om 30 minutter”

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

To kjøringstyper:

• Shell — Kjører en bash-kommando, fanger opp utdata. Kan utløse en Shortcut ved fullførelse
• Prompt — Behandlet av AI-agenten med full verktøytilgang, lagrer det komplette PocketHook-svaret

Dev-servere

#

Når agenten oppretter et webprosjekt i workspace (Hugo, Astro, Next.js, Flask, Go osv.), tilbyr den proaktivt å servere det:

• Forhåndsvisning — Starter en lokal dev-server på en automatisk tildelt port for rask visning
• Offentlig — Starter serveren og eksponerer den via HTTPS-tunnel så den er tilgjengelig overalt

Agenten styrer livssyklusen: start, stopp og list kjørende servere. Alle servere ryddes opp når hovedserveren stoppes.

Tunnelkontrakt

#

Når agenten starter en server med tunneleksponering bedt om, håndhever kjøretiden det: hvis ingen tunnelverktøy (Tailscale, ngrok, cloudflared) er installert, nekter serveren å starte. Hvis tunneloppsett feiler etter spawn, stoppes den foreldreløse prosessen, og agenten får beskjed eksplisitt — så den kan falle tilbake til forhåndsvisning eller be deg installere en tunnel. Den returnerte URL-en er alltid tunnel-URL-en når tunneling er på, med en merknad om at den lokale URL-en kun gjelder for verten.

Som et sikkerhetsnett etterbehandler hvert respond_*-verktøy sin melding: enhver localhost- eller 127.0.0.1-URL som sniker seg inn i et svar blir automatisk omskrevet til den matchende tunnel-URL-en når en administrert server har en. Når det ikke kan skrive om, får du en advarsel i loggene i stedet for en ødelagt lenke på telefonen.

Dashbord

#

Det innebygde webdashbordet på /dashboard viser en live-oversikt over bakgrunnsjobber.

Bevisst uautentisert. Både /dashboard og /api/jobs er åpne GET-endepunkter — hvem som helst som kan nå verten kan liste jobber. Begrens tilgang på nettverkslaget (Tailscale-ACL, brannmur, reverse proxy med basic auth) eller sett DASHBOARD=false hvis du ikke trenger det. PocketHook iOS-appen bruker ikke disse endepunktene.

Det er fullt tilpassbart:

• Hurtigredigering — Plasser en dashboard.html i workspace/dashboard/ for enkle tilpasninger
• Fullt prosjekt — Opprett et rammeverksprosjekt (Svelte, React, Vue osv.) i workspace/dashboard/ med build-utdata til dist/

Be agenten om å tilpasse dashbordet ditt, og den ordner resten — hver bruker får et unikt, personalisert dashbord.

Tilpassede verktøy

#

Agenten kan installere CLI-verktøy og registrere dem som nye evner — utvider seg selv uten å endre serverkoden.

Si for eksempel “installer Playwright og bruk det til å ta skjermbilder”. Agenten vil:

1. Installere avhengigheten
2. Opprette en verktøydefinisjon (en enkel .md-fil)
3. Bruke det nye verktøyet i fremtidige samtaler

Tilpassede verktøy lastes inn på nytt umiddelbart — ingen omstart nødvendig. Slett .md-filen for å fjerne et verktøy.

Versjonering

#

Alle brukerdata versjoneres automatisk:

• Workspace-filer — Sporet med et lokalt git-repo inne i workspace/. Hver skriving oppretter en auto-commit. Be agenten om å “angre den siste endringen” eller bruk git revert HEAD manuelt
• Konfigurasjonsfiler — config/agent-instructions.md, config/personality.md, skills/ og permissions.json sikkerhetskopieres for hver endring. Opptil 20 versjoner per fil

Git er valgfritt — hvis det ikke er installert, er workspace-endringer ikke versjonert. Konfigurasjonsbackup fungerer alltid.

Tilpass agenten din

#

Agentserveren leveres med en minimal rammeverksbase og forventer at du legger din egen tilpasning oppå. Kjøretiden holder de to adskilt så rammeverksoppdateringer aldri ødelegger arbeidet ditt.

Rammeverk vs bruker

#

pockethook-agent-server/
├── skills/                      # rammeverksleverte ferdigheter (skrivebeskyttet)
├── custom-tools/                # reservert for rammeverksleverte verktøy (skrivebeskyttet)
├── config/
│   ├── agent-instructions.md    # rammeverkets agentinstruksjoner (skrivebeskyttet)
│   └── personality.md           # rammeverkets personlighet (skrivebeskyttet)
└── data/user/                   # DIN tilpasning bor her (git-ignorert)
    ├── skills/                  # dine egne ferdigheter (overstyrer base på filnavn)
    ├── custom-tools/            # dine installerte tilpassede verktøy
    ├── instructions.md          # dine tillegg til agentinstruksjonene
    └── prefs.json               # typede verdier referert som {{prefs.key}}

Brukertilpasning skrives via dedikerte typede verktøy (create_user_skill, create_custom_tool), så de resulterende filene alltid matcher lasterens format. write-verktøyet avviser også enhver sti under skills/, custom-tools/ eller config/ og dirigerer agenten til data/user/* — så selv direkte filredigeringer ender i brukerlaget.

Merknad om base-mappen custom-tools/. I dag inneholder den bare en mal (_example.md) som lasteren ignorerer — hvert verktøy agenten installerer for deg havner i data/user/custom-tools/. Mappen er reservert slik at fremtidige rammeverksutgivelser kan levere valgfrie innebygde verktøy uten å ødelegge dine installasjoner. Når det skjer, vinner brukerlagsfilene dine fortsatt ved navnekollisjon, så det er ingenting å migrere.

Fire måter å tilpasse på

#

Du trenger aldri å skrive disse filene for hånd. Bare si til agenten hva du vil, og den velger rett lag automatisk.

Typede preferanser med {{prefs.*}}

#

Si at du skriver en ruteplanlegger-ferdighet som trenger å vite ditt standard utgangspunkt. I stedet for å hardkode “Madrid” i selve ferdigheten, referer til preferansen:

- **Utgangspunkt**: {{prefs.routeOrigin}}, med mindre brukeren angir et annet utgangspunkt.

Og lagre verdien i data/user/prefs.json:

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

Serveren setter inn plassholdere når ferdigheten lastes. Nestede nøkler ({{prefs.tunnel.domain}}) fungerer også. Ukjente nøkler blir urørt, så skrivefeil forblir synlige.

Redigere rammeverksbasen direkte

#

Hvis du selvhoster og vil fikle med selve rammeverket, kan du redigere config/agent-instructions.md, config/personality.md, skills/ eller custom-tools/ direkte — serveren stopper deg ikke når du bruker en filredigerer. Men agenten vil ikke skrive til de stiene fra en samtale. Og rammeverksoppdateringer vil overskrive redigeringene dine. Foretrekk brukerlaget for alt du vil beholde.

Utvide serveren

#

• Tilpassede verktøy — Be agenten om å installere CLI-verktøy; de havner i data/user/custom-tools/ automatisk
• Legg til ferdigheter — Be agenten om å opprette en ferdighet; filen går i data/user/skills/
• Endre atferd — Be agenten om å anvende en global regel; den legges til i data/user/instructions.md
• Konfigurer tillatelser — Kjør bun run permissions for å styre hvilke verktøy agenten kan bruke
• Legg til innebygde verktøy — Implementer nye verktøyfunksjoner i src/tools.ts for dypere integrasjoner (krever å forke serveren)

Konfigurasjon

#

Alle innstillinger lagres i .env (opprettet av bun run setup). Viktige alternativer:

Se den fullstendige konfigurasjonsreferansen i GitHub-repositoriet.

Kjøre som tjeneste

#

Installer som persistent tjeneste som starter automatisk:

bun run service install

INSTANCE_NAME er som standard prosjektmappens basenavn med pockethook--prefikset fjernet (f.eks. blir en checkout i pockethook-agent-server/ til agent-server). Sett det eksplisitt for å kjøre flere checkouts på samme maskin uten kollisjoner — hver instans beholder sitt eget data/ og logger.

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

Sikkerhet

#

• HTTPS påkrevd — PocketHook krever HTTPS for alle URLer
• Bearer-token-autentisering — Delt hemmelighet mellom app og server
• Frekvensbegrensning — Per-token grenser forhindrer misbruk
• Sandboxede verktøy — Shell-kommandoer og filtilgang begrenset av tillatelser
• Blokkerte mønstre — Farlige kommandoer (sudo, rm -rf /) blokkert som standard
• Arbeidskataloggrense — Agenten kan ikke forlate sin tildelte katalog
• Sensitive filer beskyttet — .env, .git, *.key, *.pem blokkert fra agenttilgang
• Automatisk versjonering — Alle workspace-endringer git-spores for enkel tilbakerulling