Otiđi na glavni sadržaj
  1. Dokumentacija/

Agentski posluzitelj

Sto je PocketHook Agent Server?
#

Agentski posluzitelj pretvara PocketHook u potpunog AI asistenta. Umjesto da sami pisete logiku odgovora, povezujete LLM (Claude, GPT, Gemini itd.) koji obraduje poruke, poziva alate i vraca strukturirane PocketHook odgovore — ukljucujuci pokretace Shortcuts.

Posluzitelj radi na vasem vlastitom racunalu. Vasi podaci ostaju kod vas.

Ovo je polazna tocka. Posluzitelj dolazi s osnovnim skupom alata i dizajniran je da ga prosirujete. Dodajte vlastite integracije — e-posta, kalendari, dokumenti, API-ji — i prilagodite ga sebi.

Znacajke
#

  • Vise LLM pruzatelja — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (lokalno), LM Studio (lokalno)
  • OAuth autentifikacija — GitHub Copilot i OpenAI Codex putem device code / browser flow
  • Agentski alati — Shell naredbe, citanje/pisanje datoteka, popis direktorija, web pretraga, web scraping, upravljanje razvojnim posluziteljima
  • Podjela framework / korisnik — Datoteke frameworka (skills/, custom-tools/, config/) ostaju samo za citanje. Vase prilagodbe zive pod data/user/ (vjestine, prilagodeni alati, upute, tipizirane preferencije). Azuriranja frameworka dolaze cisto, bez prebrisavanja vaseg rada
  • Tipizirane korisnicke preferencije — Pohranite vrijednosti poput omiljene aplikacije za karte ili tunelske domene u data/user/prefs.json. Referencirajte ih u vjestinama kao {{prefs.key}} i posluzitelj ih zamjenjuje pri ucitavanju
  • Programerski zadaci u jednom pozivu — Meta-alat run_code_job stvara pozadinski posao tipa prompt (pokrece ga vas konfigurirani LLM) i salje korisniku potvrdu u jednom koraku, zamjenjujuci pogreskama sklon obrazac „respond + create-job"
  • Tipizirani protokolski alati — Sest namjenskih respond_* alata (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), plus tipizirani alati za poslove (create_once_job, create_cron_job) i tipizirani alati za radni prostor (create_project, list_projects, delete_project). Sheme odbijaju neispravno formatirane URL-ove, sintaksu gumba i kombinacije type/schedule prije nego sto stignu do uredaja
  • Tipizirani zapisivaci za prilagodbucreate_user_skill i create_custom_tool grade markdown korisnickog sloja s ispravnim frontmatterom, tako da ga ucitavac uvijek parsira, a agent nikad ne pise te datoteke rucno
  • Pozadinski zadaci — Jednokratni ili ponavljajuci zadaci s cron izrazima ili jednostavnim intervalima
  • Dinamicke vjestine — Definirajte shortcuts i pravila ponasanja kao .md datoteke. U prompt se ucitava samo kompaktni indeks; puni sadrzaj se dohvaca na zahtjev putem alata load_skill
  • Samoupravne vjestine — Agent moze stvarati, uredivati i brisati definicije vjestina (zapisi uvijek zavrsavaju u korisnickom sloju)
  • Semanticka memorija — Vektorsko pretrazivanje s embeddingima (Ollama, LM Studio ili OpenAI). Sjecanja se automatski klasificiraju od strane LLM-a u dimenzije wing/room/hall/status
  • Graf znanja — Temporalno spremiste trojki za trajne cinjenice s automatskom invalidacijom. Visevrijednosni odnosi koegzistiraju; jednovrijednosne cinjenice se automatski zamjenjuju
  • PARA metoda s kaskadom na zavrsetku projekta — Svako sjecanje je oznaceno statusom (Projekt, Podrucje, Resurs, Arhiv). Kada projekt zavrsi, jedan poziv complete_project arhivira njegove vektore, invalidira svaku planersku trojku vezanu za slug projekta i biljezi zavrsetak — jedan poziv umjesto tri
  • Hibridno dozivljavanje — Kombinira FTS5 pretrazivanje po kljucnim rijecima s vektorskim semantickim pretrazivanjem koristeci reciprocal rank fusion
  • Dugotrajna memorija — SQLite + FTS5 punotekstno pretrazivanje kao rezervna opcija kada je semanticka memorija iskljucena
  • Upravljanje razvojnim posluziteljima s tunelskim ugovorom — Pokretanje, zaustavljanje i popis razvojnih posluzitelja. Kada se zatrazi tunnel: true, posluzitelj to provjerava prije i nakon pokretanja — nedostupni localhost posluzitelj nikada ne ostaje tiho raditi
  • Automatsko sanitiziranje URL-ova — Ako agent u odgovoru ostavi localhost URL, alati respond_* ga prepisuju u odgovarajuci tunelski URL tako da vas telefon uvijek dobije dostupan link
  • Prilagodeni alati — Agent moze instalirati CLI alate i registrirati ih kao nove sposobnosti
  • Verzioniranje — Automatsko git verzioniranje za datoteke workspace-a; sigurnosne kopije konfiguracije za vjestine i dozvole
  • Web nadzorna ploca — Pregled pozadinskih zadataka uzivo, prilagodljiv po korisniku. /dashboard i /api/jobs su namjerno neautenticirani — ogranicite pristup na razini mreze (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postavite DASHBOARD=false ako vam ne trebaju
  • HTTPS tuneliranje — Ugradena podrska za Tailscale, ngrok i Cloudflare Tunnel
  • Sistemska usluga — Instalacija kao trajna usluga na macOS, Linux ili Windows
  • Ogranicavanje zahtjeva — Limiti po tokenu s konfigurabilnim pragovima

Zahtjevi
#

Brzi pocetak
#

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

# Interaktivno postavljanje — odaberite pruzatelja, model, autentifikacijski token, port
bun run setup

# Pokrenite posluzitelj + HTTPS tunel
bun run dev:tunnel

Carobnjak za postavljanje vodit ce vas kroz odabir LLM pruzatelja, konfiguraciju autentifikacije i postavljanje dozvola alata.

Nakon pokretanja, kopirajte prikazane URL-ove u PocketHook Postavke:

PocketHook PostavkaURL
Server URLhttps://your-host
Health Check URLhttps://your-host/health
Polling URLhttps://your-host/jobs

Kako radi
#

  1. Posaljete poruku u PocketHook
  2. Posluzitelj je prosljeduje vasem odabranom LLM-u s povijescu razgovora, dozvanim sjecanjima i dostupnim alatima
  3. LLM obraduje poruku — moze pokretati shell naredbe, citati/pisati datoteke, pretrazivati web, planirati pozadinske zadatke, pamtiti cinjenice ili pokretati razvojne posluzitelje
  4. Odgovor se vraca u PocketHook formatu (msg + shortcut + data + url)
  5. PocketHook prikazuje poruku i izvrsava sve Shortcuts na vasem uredaju

Podrzani LLM pruzatelji
#

PruzateljAutentifikacijaZadani model
AnthropicAPI kljucclaude-sonnet-4-20250514
OpenAIAPI kljucgpt-4.1-mini
OpenAI CodexOAuthgpt-5.1-codex-mini
GitHub CopilotOAuthclaude-sonnet-4
Google (Gemini)API kljucgemini-2.5-flash
MistralAPI kljucmistral-medium-latest
GroqAPI kljucllama-3.3-70b-versatile
xAI (Grok)API kljucgrok-3-mini-fast
OpenRouterAPI kljucanthropic/claude-sonnet-4
Ollama (lokalno)Nemallama3.2
LM Studio (lokalno)Nemaqwen3.5-4b-mlx

Promijenite pruzatelja bilo kada pomocu bun run switch. Ollama i LM Studio rade u potpunosti na vasem racunalu — nije potreban API kljuc, nikakvi podaci ne napustaju vasu mrezu.

Memorija
#

Sustav memorije ima tri sloja, od kojih svaki sluzi razlicitoj svrsi.

Dizajn semanticke memorije kombinira ideje iz MemPalace (arhitektura memorijskog dvorca koja organizira sjecanja u krila, hodnike i sobe) i PARA metode Tiaga Fortea (Projekti, Podrucja, Resursi, Arhiv) za upravljanje zivotnim ciklusom znanja.

Konverzacijska memorija
#

SQLite s FTS5 punotekstnim pretrazivanjem. Sve poruke se pohranjuju s vremenskim oznakama i identifikatorima sesija.

  • Kratkorocna — Zadnjih MAX_HISTORY poruka drzanih u memoriji po sesiji
  • Dugorocna — Sve poruke pohranjene u SQLite, pretrazive putem FTS5 podudaranja kljucnih rijeci
  • Dozivljavanje po potezu — Kada je semanticka memorija ukljucena, MAX_RECALL kontrolira koliko se relevantnih sjecanja ubacuje u prompt po svakom potezu
  • Sesije istjecu nakon SESSION_TTL_MINUTES, ali dugorocna memorija traje zauvijek

Ove vrijednosti interaktivno podesite naredbom bun run memory.

Semanticka memorija
#

Zahtijeva VECTOR_MEMORY=true i pruzatelja embeddinga (Ollama, LM Studio ili OpenAI).

Svako sjecanje je umetnuto kao vektor i automatski klasificirano od strane LLM-a u cetiri dimenzije:

  • Wing — Entitet: user, person:john, project:blog, place:london
  • Room — Tip: facts, preferences, events, decisions, requests
  • Hall — Tema: personal, tech, health, travel, food, work
  • Status — PARA klasifikacija: project, area, resource, archive

Kada postavite pitanje, ekstrakcija entiteta usmjerava vektorsko pretrazivanje na najrelevantnije krilo. Rezultati se spajaju s FTS5 rezultatima kljucnih rijeci koristeci reciprocal rank fusion — tako dobivate najbolje od oba pristupa.

Graf znanja
#

Temporalno spremiste trojki za strukturirane, trajne cinjenice:

  • Trojke: (subjekt, predikat, objekt) s vremenskim oznakama valid_from / valid_until
  • Jednovrijednosni predikati (lives_in, partner) automatski invalidiraju staru vrijednost pri azuriranju
  • Visevrijednosni predikati (child, friend, hobby) koegzistiraju bez invalidacije
  • Cinjenice iz grafa znanja se ubacuju zajedno s dozvanim sjecanjima u svaki razgovor

Kada agentu kazete „Preselio sam se u Berlin", invalidira staru trojku lives_in i stvara novu — automatski.

PARA zivotni ciklus
#

Svako sjecanje je oznaceno PARA statusom:

  • Projekt — Aktivni, vremenski ograniceni rad
  • Podrucje — Tekuce odgovornosti
  • Resurs — Referencni materijal (popisi, preporuke, upute)
  • Arhiv — Zavrseni ili otkazani projekti

Kada se projekt zavrsi, agent koristi semanticku slicnost za arhiviranje samo sjecanja tog projekta uz ocuvanje referencnog materijala za buducu upotrebu.

Kaskada na zavrsetku projekta
#

Recite „Otkazujem put u Barcelonu" i jedan poziv alata obavlja sve:

  1. Arhivira vektore projekta (dogadaje, odluke, zahtjeve vezane uz Barcelonu).
  2. Invalidira svaku aktivnu trojku grafa znanja ciji predikat odgovara slugu projekta (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona).
  3. Biljezi zavrsetak kao novu trojku: (user, "cancelled_visit_barcelona", "2026-04-15").

Podudaranje postuje granice — drugi projekt zvan revisit_barcelona ostaje netaknut. Agent vise ne mora orkestrirati tri odvojena poziva u pravom redoslijedu, pa i manji modeli to ispravno obave.

Ako je VECTOR_MEMORY iskljucen ili je pruzatelj embeddinga nedostupan, sustav se vraca na FTS5 bez gresaka.

Vjestine
#

Vjestine su .md datoteke u direktoriju skills/ koje definiraju iOS Shortcuts koje agent moze pokrenuti i/ili pravila ponasanja. Koriste dinamicko ucitavanje: u sistemski prompt se ubacuje samo kompaktni indeks (naslov, opis, popis shortcuts). Agent ucitava puni sadrzaj na zahtjev putem alata load_skill, odrzavajuci nisku potrosnju tokena kako dodajete vise vjestina.

Svaka datoteka vjestine koristi 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

Polja frontmattera
#

PoljeObaveznoOpis
titleDaCitljivo ime
descriptionDaJedna recenica koristena u indeksu vjestina koji se prikazuje agentu
shortcutsDaNiz imena shortcuts definiranih u datoteci. Za vjestine koje sadrze samo pravila ponasanja koristite []
targetNeGdje se shortcuts izvrsavaju: device (zadano, salje se na iOS) ili mac (pokrece se na posluzitelju)
sync_appNeAplikacija koja se nakratko otvara u pozadini nakon izvrsavanja na posluzitelju kako bi se pokrenula iCloud sinkronizacija (npr. Notes, Calendar, Reminders). Izostavite ili koristite none za preskakanje

Vjestine takoder mogu biti pravila ponasanja bez shortcuts (npr. „kako planirati obiteljsko putovanje"). Koristite shortcuts: [] za takve.

Agent moze stvarati i upravljati vjestinama na zahtjev — zamolite ga da „stvori vjestinu za upravljanje mojim svjetlima" i napisat ce .md datoteku za vas. Nove i uredene vjestine uvijek zavrsavaju u vasem korisnickom sloju (data/user/skills/), pa ih azuriranja frameworka nikada ne prebrisuju. Pogledajte odjeljak Customizing your agent nize.

Izvrsavanje shortcuts na Mac posluzitelju
#

Kada vjestina ima target: mac, shortcuts se tiho pokrecu na Mac posluzitelju putem CLI alata shortcuts run, umjesto da se salju na iOS uredaj. Ovo je idealno za akcije koje stvaraju sadrzaj sinkroniziran s iCloud-om — biljeske, podsjetnike, kalendarske dogadaje — jer se rezultat automatski sinkronizira na sve vase uredaje bez potrebe da PocketHook aplikacija bilo sto radi.

Kako radi:

  1. Agent odlucuje da se shortcut mora pokrenuti (npr. „stvori biljesku s danasnjim zabiljeskama sa sastanka")
  2. Posluzitelj poziva shortcuts run "imeShortcuta" s podacima proslijedjenim kao JSON na stdin, koristeci isti wrapper format koji koristi PocketHook iOS
  3. Ako je sync_app postavljen, posluzitelj nakratko otvara tu aplikaciju u pozadini (open -gj -a Notes) kako bi prisilio iCloud sinkronizaciju, a zatim je zatvara nakon 5 sekundi
  4. Korisnik dobiva potvrdnu poruku u chatu; sam shortcut se ne salje na uredaj

Zahtjevi:

  • Posluzitelj mora raditi na macOS-ushortcuts run postoji samo na macOS-u. Na drugim platformama posluzitelj biljezi upozorenje i vraca se na izvrsavanje na uredaju
  • Shortcut mora biti instaliran u Shortcuts.app na Mac posluzitelju
  • Shortcut bi trebao ocekivati Dictionary kao ulaz (PocketHook omata podatke u { context, timestamp, app, data })

Kada koristiti target: mac:

  • iCloud-sinkronizirane akcije (Notes, Reminders, Calendar) — rezultat svejedno dolazi do svakog uredaja
  • Dugotrajna obrada koju zelite drzati izvan iOS uredaja
  • Bilo koji shortcut koji ne treba interakciju s iPhone sucaljem

Kada zadrzati target: device (zadano):

  • Shortcuts koji trebaju znacajke dostupne samo na iPhone-u (kamera, precizna lokacija, lokalne automatizacije aplikacija)
  • Shortcuts koji od korisnika traze interaktivni unos
  • Shortcuts koji koriste App Intents iz aplikacija dostupnih samo na iOS-u

Pozadinski zadaci
#

Zamolite agenta da planira zadatke i ostatak ce rijesiti sam:

  • „Provjeri vrijeme svako jutro u 8 i stvori biljesku"
  • „Pokreni ovu skriptu svaki sat"
  • „Podsjeti me da provjerim e-postu za 30 minuta"

Zadaci podrzavaju cron izraze (0 8 * * *) i jednostavne intervale (30m, 1h, 2d). Rezultati se isporucuju u PocketHook kada upituje krajnju tocku /jobs.

Dva tipa izvrsavanja:

  • Shell — Pokrece bash naredbu, hvata izlaz. Moze pokrenuti Shortcut po zavrsetku
  • Prompt — Obraduje AI agent s punim pristupom alatima, pohranjuje kompletan PocketHook odgovor

Razvojni posluzitelji
#

Kada agent stvori web projekt u workspace-u (Hugo, Astro, Next.js, Flask, Go itd.), proaktivno nudi njegovo posluzivanje:

  • Pregled — Pokrece lokalni razvojni posluzitelj na automatski dodijeljenom portu za brzo pregledavanje
  • Javni — Pokrece posluzitelj i izlaze ga putem HTTPS tunela tako da je dostupan s bilo kojeg mjesta

Agent upravlja zivotnim ciklusom: pokretanje, zaustavljanje i popis pokrenutih posluzitelja. Svi posluzitelji se ciste kada se glavni posluzitelj zaustavi.

Tunelski ugovor
#

Kada agent pokrene posluzitelj sa zatrazenim izlaganjem kroz tunel, runtime to provodi: ako nije instaliran nijedan tunelski alat (Tailscale, ngrok, cloudflared), posluzitelj odbija startati. Ako postavljanje tunela ne uspije nakon pokretanja, proces-sirot se zaustavlja i agent se o tome eksplicitno obavjestava — tako da moze preci u nacin pregleda ili vas pitati da instalirate tunel. Vraceni URL je uvijek tunelski URL kada je tuneliranje ukljuceno, uz napomenu da je lokalni URL dostupan samo na racunalu-domacinu.

Kao sigurnosna mreza, svaki respond_* alat naknadno obraduje svoju poruku: svaki localhost ili 127.0.0.1 URL koji se provuce u odgovor automatski se prepisuje u odgovarajuci tunelski URL kada upravljani posluzitelj ima takav. Kada prepisivanje nije moguce, dobivate upozorenje u logovima umjesto pokvarenog linka na telefonu.

Nadzorna ploca
#

Ugradena web nadzorna ploca na /dashboard prikazuje pregled pozadinskih zadataka uzivo.

Namjerno neautenticirano. I /dashboard i /api/jobs su otvoreni GET endpointi — svatko tko moze doci do hosta moze ispisati zadatke. Ogranicite pristup na razini mreze (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postavite DASHBOARD=false ako vam ne trebaju. PocketHook iOS aplikacija ne koristi te endpointe.

Potpuno je prilagodljiva:

  • Brza uredba — Stavite datoteku dashboard.html u workspace/dashboard/ za jednostavne prilagodbe
  • Puni projekt — Stvorite framework projekt (Svelte, React, Vue itd.) u workspace/dashboard/ s izlazom gradnje u dist/

Zamolite agenta da prilagodi vasu nadzornu plocu i ostatak ce rijesiti sam — svaki korisnik dobiva jedinstvenu, personaliziranu nadzornu plocu.

Prilagodeni alati
#

Agent moze instalirati CLI alate i registrirati ih kao nove sposobnosti — prosirujuci se bez mijenjanja koda posluzitelja.

Na primjer, recite „instaliraj Playwright i koristi ga za snimanje zaslona". Agent ce:

  1. Instalirati ovisnost
  2. Stvoriti definiciju alata (jednostavna .md datoteka)
  3. Koristiti novi alat u buducim razgovorima

Prilagodeni alati se vruce ucitavaju — restart nije potreban. Obrisite .md datoteku za uklanjanje alata.

Verzioniranje
#

Svi korisnicki podaci se automatski verzioniraju:

  • Datoteke workspace-a — Pracene lokalnim git repozitorijem unutar workspace/. Svaki zapis stvara auto-commit. Zamolite agenta da „ponisti zadnju promjenu" ili koristite git revert HEAD rucno
  • Konfiguracijske datotekeconfig/agent-instructions.md, config/personality.md, skills/ i permissions.json se kopiraju prije svake izmjene. Do 20 verzija po datoteci

Git je opcionalan — ako nije instaliran, promjene workspace-a nisu verzionirane. Sigurnosne kopije konfiguracije uvijek rade.

Customizing your agent
#

Agentski posluzitelj dolazi s minimalnom bazom frameworka i ocekuje da vlastite prilagodbe dodate iznad nje. Runtime drzi to dvoje odvojeno kako azuriranja frameworka nikad ne bi unistila vas rad.

Framework nasuprot korisnika
#

pockethook-agent-server/
├── skills/                      # vjestine isporucene s frameworkom (samo za citanje)
├── custom-tools/                # rezervirano za alate isporucene s frameworkom (samo za citanje)
├── config/
│   ├── agent-instructions.md    # upute agenta iz frameworka (samo za citanje)
│   └── personality.md           # osobnost iz frameworka (samo za citanje)
└── data/user/                   # VASE prilagodbe zive ovdje (ignorirano u gitu)
    ├── skills/                  # vase vlastite vjestine (nadjacavaju bazu po imenu datoteke)
    ├── custom-tools/            # vasi instalirani prilagodeni alati
    ├── instructions.md          # vasi dodaci uputama agenta
    └── prefs.json               # tipizirane vrijednosti referencirane kao {{prefs.key}}

Korisnicke prilagodbe pisu se preko namjenskih tipiziranih alata (create_user_skill, create_custom_tool) tako da rezultirajuce datoteke uvijek odgovaraju formatu ucitavaca. Alat write takoder odbija svaku putanju pod skills/, custom-tools/ ili config/ i preusmjerava agenta u data/user/* — pa cak i izravne izmjene datoteka zavrsavaju u korisnickom sloju.

Napomena o osnovnom direktoriju custom-tools/. Danas on sadrzi samo predlozak (_example.md) koji ucitavac ignorira — svaki alat koji agent instalira za vas ide u data/user/custom-tools/. Direktorij je rezerviran kako bi buduce verzije frameworka mogle isporuciti opcionalne ugradene alate bez prebrisavanja vasih instalacija. Kada se to dogodi, vase datoteke u korisnickom sloju i dalje pobjeduju pri sudaru imena alata, pa nema sto migrirati.

Cetiri nacina prilagodbe
#

Sto zelite promijenitiKamo idePrimjer
Vjestina sa shortcutom ili pravilom ponasanjadata/user/skills/<ime>.md„Stvori vjestinu za biljezenje mojih treninga"
CLI alat omotan kao agentska sposobnostdata/user/custom-tools/<ime>.md„Instaliraj ffmpeg i daj mi ga koristiti za konverzije"
Globalno pravilo („uvijek odgovaraj na engleskom", „nikad ne koristi tablice")data/user/instructions.md„Od sada uvijek sazimaj clanke u 3 natuknice"
Tipizirana zadana vrijednost na koju se pozivaju vjestinedata/user/prefs.json„Moje zadano polaziste rute je Madrid"{"routeOrigin": "Madrid"}

Ove datoteke nikada ne morate pisati rucno. Samo recite agentu sto zelite i on automatski bira pravi sloj.

Tipizirane preferencije s {{prefs.*}}
#

Recimo da pisete vjestinu planera ruta kojoj treba znati vase zadano polaziste. Umjesto da „Madrid" ukodirate u vjestinu, referencirajte preferenciju:

- **Polaziste**: {{prefs.routeOrigin}}, osim ako korisnik navede drugo polaziste.

I pohranite vrijednost u data/user/prefs.json:

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

Posluzitelj zamjenjuje rezervirana mjesta pri ucitavanju vjestine. Ugnijezdeni kljucevi ({{prefs.tunnel.domain}}) takoder rade. Nepoznati kljucevi ostaju netaknuti kako bi tipografske pogreske ostale vidljive.

Izravno uredivanje baze frameworka
#

Ako se sami hostate i zelite ugoditi sam framework, mozete izravno urediti config/agent-instructions.md, config/personality.md, skills/ ili custom-tools/ — posluzitelj vas ne zaustavlja kada koristite uredivac datoteka. Ali agent nece pisati na te putanje iz razgovora. A azuriranja frameworka prepisat ce vase izmjene. Za sve sto zelite zadrzati radije koristite korisnicki sloj.

Prosirenje posluzitelja
#

  • Prilagodeni alati — Zamolite agenta da instalira CLI alate; zavrsavaju u data/user/custom-tools/ automatski
  • Dodajte vjestine — Zamolite agenta da stvori vjestinu; datoteka ide u data/user/skills/
  • Promijenite ponasanje — Zamolite agenta da primijeni globalno pravilo; ono se dodaje u data/user/instructions.md
  • Konfigurirajte dozvole — Pokrenite bun run permissions za kontrolu koje alate agent moze koristiti
  • Dodajte ugradene alate — Implementirajte nove funkcije alata u src/tools.ts za dublje integracije (zahtijeva forkanje posluzitelja)

Konfiguracija
#

Sve postavke su pohranjene u .env (stvorenom pomocu bun run setup). Kljucne opcije:

VarijablaZadanoOpis
AUTH_TOKEN(obavezno)Dijeljeni tajni kljuc s PocketHook
LLM_API_KEY(obavezno)API kljuc LLM pruzatelja
LLM_PROVIDERanthropicNaziv pruzatelja
LLM_MODELclaude-sonnet-4-20250514ID modela
LLM_REASONINGoffRazina rezoniranja: off, minimal, low, medium, high, xhigh. Vise razine dodaju skrivene tokene razmisljanja (sporije + skuplje). Modeli koji to ne podrzavaju to ignoriraju
PORT3000Port posluzitelja
AGENT_NAMEPocketHook AssistantPrikazano ime agenta
MAX_HISTORY50Poruke u kratkorocnoj memoriji
MAX_RECALL5Sjecanja vracena po potezu semantickim dozivljavanjem (samo kada VECTOR_MEMORY=true)
SESSION_TTL_MINUTES60Istjecanje sesije
VECTOR_MEMORYfalseOmoguci semanticku memoriju (zahtijeva pruzatelja embeddinga)
EMBEDDING_PROVIDERollamaPruzatelj embeddinga: ollama, lm-studio ili openai
EMBEDDING_MODELnomic-embed-textNaziv modela embeddinga
EMBEDDING_URL(auto)URL API-ja embeddinga
EMBEDDING_API_KEYAPI kljuc za OpenAI embeddinge
LOG_LEVELinfoRazina logiranja: debug, info, warn, error
RATE_LIMIT_MAX30Maksimalan broj zahtjeva po prozoru
DASHBOARDtrueOmoguci web nadzornu plocu (ruta /dashboard)
INSTANCE_NAME(osnovno ime direktorija projekta, s uklonjenim prefiksom pockethook-)Sufiks koristen za oznaku sistemske usluge, direktorij logova i podudaranje procesa. Postavite eksplicitno kada na istom racunalu radi vise kopija

Potpunu referencu konfiguracije pogledajte u GitHub repozitoriju.

Pokretanje kao usluga
#

Instalirajte kao trajnu uslugu koja se automatski pokrece:

bun run service install
PlatformaBackendLokacija usluge
macOSlaunchd~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist
Linuxsystemd (user)~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service
WindowsNSSMPocketHook-${PascalCase(INSTANCE_NAME)} u Upravitelju usluga sustava Windows

INSTANCE_NAME se po zadanom postavlja na osnovno ime direktorija projekta s uklonjenim prefiksom pockethook- (npr. kopija u pockethook-agent-server/ postaje agent-server). Postavite ga eksplicitno za pokretanje vise kopija na istom racunalu bez sudara — svaka instanca cuva vlastite data/ i logove.

Upravljajte pomocu bun run service status, restart, stop ili uninstall.

Sigurnost
#

  • Obavezan HTTPS — PocketHook zahtijeva HTTPS za sve URL-ove
  • Bearer token autentifikacija — Dijeljeni tajni kljuc izmedu aplikacije i posluzitelja
  • Ogranicavanje zahtjeva — Limiti po tokenu sprijecavaju zloporabu
  • Izolirani alati — Shell naredbe i pristup datotekama ograniceni dozvolama
  • Blokirani obrasci — Opasne naredbe (sudo, rm -rf /) blokirane prema zadanom
  • Granica radnog direktorija — Agent ne moze napustiti svoj odredeni direktorij
  • Zasticene osjetljive datoteke.env, .git, *.key, *.pem blokirane od pristupa agenta
  • Automatsko verzioniranje — Sve promjene workspace-a prate se gitom za lako vracanje