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 poddata/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_jobstvara 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 kombinacijetype/scheduleprije nego sto stignu do uredaja - Tipizirani zapisivaci za prilagodbu —
create_user_skillicreate_custom_toolgrade 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
.mddatoteke. U prompt se ucitava samo kompaktni indeks; puni sadrzaj se dohvaca na zahtjev putem alataload_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_projectarhivira 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
localhostURL, alatirespond_*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.
/dashboardi/api/jobssu namjerno neautenticirani — ogranicite pristup na razini mreze (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postaviteDASHBOARD=falseako 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#
- Bun runtime
- API kljuc ili OAuth vjerodajnice za vaseg LLM pruzatelja
- (Opcionalno) Tailscale, ngrok ili cloudflared za HTTPS tuneliranje
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 Postavka | URL |
|---|---|
| Server URL | https://your-host |
| Health Check URL | https://your-host/health |
| Polling URL | https://your-host/jobs |
Kako radi#
- Posaljete poruku u PocketHook
- Posluzitelj je prosljeduje vasem odabranom LLM-u s povijescu razgovora, dozvanim sjecanjima i dostupnim alatima
- LLM obraduje poruku — moze pokretati shell naredbe, citati/pisati datoteke, pretrazivati web, planirati pozadinske zadatke, pamtiti cinjenice ili pokretati razvojne posluzitelje
- Odgovor se vraca u PocketHook formatu (
msg+shortcut+data+url) - PocketHook prikazuje poruku i izvrsava sve Shortcuts na vasem uredaju
Podrzani LLM pruzatelji#
| Pruzatelj | Autentifikacija | Zadani model |
|---|---|---|
| Anthropic | API kljuc | claude-sonnet-4-20250514 |
| OpenAI | API kljuc | gpt-4.1-mini |
| OpenAI Codex | OAuth | gpt-5.1-codex-mini |
| GitHub Copilot | OAuth | claude-sonnet-4 |
| Google (Gemini) | API kljuc | gemini-2.5-flash |
| Mistral | API kljuc | mistral-medium-latest |
| Groq | API kljuc | llama-3.3-70b-versatile |
| xAI (Grok) | API kljuc | grok-3-mini-fast |
| OpenRouter | API kljuc | anthropic/claude-sonnet-4 |
| Ollama (lokalno) | Nema | llama3.2 |
| LM Studio (lokalno) | Nema | qwen3.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_HISTORYporuka 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_RECALLkontrolira 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 oznakamavalid_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:
- Arhivira vektore projekta (dogadaje, odluke, zahtjeve vezane uz Barcelonu).
- Invalidira svaku aktivnu trojku grafa znanja ciji predikat odgovara slugu projekta (
scheduled_visit_barcelona,planning_visit_barcelona,confirmed_visit_barcelona). - 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#
| Polje | Obavezno | Opis |
|---|---|---|
title | Da | Citljivo ime |
description | Da | Jedna recenica koristena u indeksu vjestina koji se prikazuje agentu |
shortcuts | Da | Niz imena shortcuts definiranih u datoteci. Za vjestine koje sadrze samo pravila ponasanja koristite [] |
target | Ne | Gdje se shortcuts izvrsavaju: device (zadano, salje se na iOS) ili mac (pokrece se na posluzitelju) |
sync_app | Ne | Aplikacija 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:
- Agent odlucuje da se shortcut mora pokrenuti (npr. „stvori biljesku s danasnjim zabiljeskama sa sastanka")
- Posluzitelj poziva
shortcuts run "imeShortcuta"s podacima proslijedjenim kao JSON na stdin, koristeci isti wrapper format koji koristi PocketHook iOS - Ako je
sync_apppostavljen, posluzitelj nakratko otvara tu aplikaciju u pozadini (open -gj -a Notes) kako bi prisilio iCloud sinkronizaciju, a zatim je zatvara nakon 5 sekundi - Korisnik dobiva potvrdnu poruku u chatu; sam shortcut se ne salje na uredaj
Zahtjevi:
- Posluzitelj mora raditi na macOS-u —
shortcuts runpostoji 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
/dashboardi/api/jobssu otvoreniGETendpointi — svatko tko moze doci do hosta moze ispisati zadatke. Ogranicite pristup na razini mreze (Tailscale ACL, vatrozid, reverse proxy s basic auth) ili postaviteDASHBOARD=falseako vam ne trebaju. PocketHook iOS aplikacija ne koristi te endpointe.
Potpuno je prilagodljiva:
- Brza uredba — Stavite datoteku
dashboard.htmluworkspace/dashboard/za jednostavne prilagodbe - Puni projekt — Stvorite framework projekt (Svelte, React, Vue itd.) u
workspace/dashboard/s izlazom gradnje udist/
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:
- Instalirati ovisnost
- Stvoriti definiciju alata (jednostavna
.mddatoteka) - 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 koristitegit revert HEADrucno - Konfiguracijske datoteke —
config/agent-instructions.md,config/personality.md,skills/ipermissions.jsonse 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 udata/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 promijeniti | Kamo ide | Primjer |
|---|---|---|
| Vjestina sa shortcutom ili pravilom ponasanja | data/user/skills/<ime>.md | „Stvori vjestinu za biljezenje mojih treninga" |
| CLI alat omotan kao agentska sposobnost | data/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 vjestine | data/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 permissionsza kontrolu koje alate agent moze koristiti - Dodajte ugradene alate — Implementirajte nove funkcije alata u
src/tools.tsza dublje integracije (zahtijeva forkanje posluzitelja)
Konfiguracija#
Sve postavke su pohranjene u .env (stvorenom pomocu bun run setup). Kljucne opcije:
| Varijabla | Zadano | Opis |
|---|---|---|
AUTH_TOKEN | (obavezno) | Dijeljeni tajni kljuc s PocketHook |
LLM_API_KEY | (obavezno) | API kljuc LLM pruzatelja |
LLM_PROVIDER | anthropic | Naziv pruzatelja |
LLM_MODEL | claude-sonnet-4-20250514 | ID modela |
LLM_REASONING | off | Razina rezoniranja: off, minimal, low, medium, high, xhigh. Vise razine dodaju skrivene tokene razmisljanja (sporije + skuplje). Modeli koji to ne podrzavaju to ignoriraju |
PORT | 3000 | Port posluzitelja |
AGENT_NAME | PocketHook Assistant | Prikazano ime agenta |
MAX_HISTORY | 50 | Poruke u kratkorocnoj memoriji |
MAX_RECALL | 5 | Sjecanja vracena po potezu semantickim dozivljavanjem (samo kada VECTOR_MEMORY=true) |
SESSION_TTL_MINUTES | 60 | Istjecanje sesije |
VECTOR_MEMORY | false | Omoguci semanticku memoriju (zahtijeva pruzatelja embeddinga) |
EMBEDDING_PROVIDER | ollama | Pruzatelj embeddinga: ollama, lm-studio ili openai |
EMBEDDING_MODEL | nomic-embed-text | Naziv modela embeddinga |
EMBEDDING_URL | (auto) | URL API-ja embeddinga |
EMBEDDING_API_KEY | — | API kljuc za OpenAI embeddinge |
LOG_LEVEL | info | Razina logiranja: debug, info, warn, error |
RATE_LIMIT_MAX | 30 | Maksimalan broj zahtjeva po prozoru |
DASHBOARD | true | Omoguci 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
| Platforma | Backend | Lokacija usluge |
|---|---|---|
| macOS | launchd | ~/Library/LaunchAgents/com.pockethook.${INSTANCE_NAME}.plist |
| Linux | systemd (user) | ~/.config/systemd/user/pockethook-${INSTANCE_NAME}.service |
| Windows | NSSM | PocketHook-${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,*.pemblokirane od pristupa agenta - Automatsko verzioniranje — Sve promjene workspace-a prate se gitom za lako vracanje