एजेंट सर्वर

PocketHook Agent Server क्या है?

#

एजेंट सर्वर PocketHook को एक पूर्ण AI सहायक में बदल देता है। अपना रिस्पॉन्स लॉजिक खुद लिखने के बजाय, आप एक LLM (Claude, GPT, Gemini, आदि) कनेक्ट करते हैं जो संदेश प्रोसेस करता है, टूल्स कॉल करता है, और संरचित PocketHook रिस्पॉन्स लौटाता है — जिसमें Shortcut ट्रिगर भी शामिल हैं।

सर्वर आपकी अपनी मशीन पर चलता है। आपका डेटा आपके पास रहता है।

यह एक शुरुआती बिंदु है। सर्वर कोर टूल्स के एक सेट के साथ आता है और इसे आपके द्वारा विस्तारित करने के लिए डिज़ाइन किया गया है। अपने इंटीग्रेशन जोड़ें — ईमेल, कैलेंडर, डॉक्यूमेंट, APIs — और इसे अपना बनाएं।

विशेषताएं

#

• मल्टी-प्रोवाइडर LLM — Anthropic, OpenAI, GitHub Copilot, Google, Mistral, Groq, xAI, OpenRouter, Ollama (लोकल), LM Studio (लोकल)
• OAuth प्रमाणीकरण — GitHub Copilot और OpenAI Codex डिवाइस कोड / ब्राउज़र फ़्लो के माध्यम से
• एजेंट टूल्स — शेल कमांड, फ़ाइल रीड/राइट, डायरेक्टरी लिस्टिंग, वेब सर्च, वेब स्क्रैपिंग, डेव सर्वर प्रबंधन
• फ़्रेमवर्क / उपयोगकर्ता विभाजन — फ़्रेमवर्क फ़ाइलें (skills/, custom-tools/, config/) केवल-पठनीय रहती हैं। आपके कस्टमाइज़ेशन data/user/ के अंतर्गत रहते हैं (स्किल्स, कस्टम टूल्स, इंस्ट्रक्शन, टाइप्ड प्रेफ्स)। फ़्रेमवर्क अपडेट आपके काम को ओवरराइट किए बिना लगते हैं
• टाइप्ड यूज़र प्रेफ्स — अपनी पसंदीदा मैप्स ऐप या टनल डोमेन जैसी वैल्यूज़ data/user/prefs.json में स्टोर करें। स्किल्स में उन्हें {{prefs.key}} के रूप में रेफ़रेंस करें और सर्वर लोड पर उन्हें सब्स्टिट्यूट कर देता है
• एक कॉल में प्रोग्रामिंग कार्य — run_code_job मेटा-टूल एक prompt-प्रकार की बैकग्राउंड जॉब बनाता है (आपके कॉन्फ़िगर किए गए LLM द्वारा चलाई गई) और उपयोगकर्ता को एक ही स्टेप में ack भेजता है, जो त्रुटि-प्रवण “respond + create-job” पैटर्न की जगह लेता है
• टाइप्ड प्रोटोकॉल टूल्स — छह समर्पित respond_* टूल्स (respond_text, respond_image, respond_buttons, respond_shortcut, respond_html, respond_sequence), साथ ही टाइप्ड जॉब टूल्स (create_once_job, create_cron_job) और टाइप्ड वर्कस्पेस टूल्स (create_project, list_projects, delete_project)। डिवाइस तक पहुँचने से पहले स्कीमा खराब URLs, बटन सिंटैक्स, और type/schedule संयोजनों को अस्वीकार करता है
• कस्टमाइज़ेशन के लिए टाइप्ड राइटर्स — create_user_skill और create_custom_tool सही frontmatter के साथ यूज़र-लेयर मार्कडाउन बनाते हैं, ताकि लोडर हमेशा उन्हें पार्स कर सके और एजेंट कभी इन फ़ाइलों को हाथ से न लिखे
• बैकग्राउंड जॉब्स — एक बार या आवर्ती कार्य cron एक्सप्रेशन या सरल इंटरवल के साथ
• डायनामिक स्किल्स — Shortcuts और व्यवहार नियमों को .md फ़ाइलों के रूप में परिभाषित करें। प्रॉम्प्ट में केवल एक कॉम्पैक्ट इंडेक्स लोड होता है; पूरा कंटेंट load_skill टूल के माध्यम से मांग पर फ़ेच होता है
• सेल्फ-मैनेजिंग स्किल्स — एजेंट स्किल डेफ़िनिशन बना, संपादित और हटा सकता है (राइट्स हमेशा यूज़र लेयर में लगते हैं)
• सिमेंटिक मेमोरी — एम्बेडिंग्स (Ollama, LM Studio, या OpenAI) के साथ वेक्टर-आधारित सर्च। मेमोरीज़ LLM द्वारा स्वचालित रूप से विंग/रूम/हॉल/स्टेटस आयामों में वर्गीकृत होती हैं
• नॉलेज ग्राफ — टिकाऊ तथ्यों के लिए टेम्पोरल ट्रिपल स्टोर जिसमें ऑटो-इनवैलिडेशन है। मल्टी-वैल्यू रिलेशनशिप सह-अस्तित्व में रहते हैं; सिंगल-वैल्यू फ़ैक्ट्स ऑटो-रिप्लेस होते हैं
• प्रोजेक्ट-एंड कैस्केड के साथ PARA मेथड — हर मेमोरी को एक स्टेटस (प्रोजेक्ट, एरिया, रिसोर्स, आर्काइव) से टैग किया जाता है। जब कोई प्रोजेक्ट समाप्त होता है, तो एक ही complete_project कॉल उसके वेक्टरों को आर्काइव करता है, उसके स्लग से बंधे हर प्लानिंग ट्रिपल को इनवैलिडेट करता है, और समापन रिकॉर्ड करता है — तीन के बजाय एक कॉल
• हाइब्रिड रिकॉल — FTS5 कीवर्ड सर्च और वेक्टर सिमेंटिक सर्च को रेसिप्रोकल रैंक फ़्यूज़न से जोड़ता है
• दीर्घकालिक मेमोरी — सिमेंटिक मेमोरी अक्षम होने पर फ़ॉलबैक के रूप में SQLite + FTS5 फ़ुल-टेक्स्ट सर्च
• टनल कॉन्ट्रैक्ट के साथ डेव सर्वर प्रबंधन — डेव सर्वर शुरू, बंद और सूचीबद्ध करें। जब tunnel: true का अनुरोध किया जाता है, तो सर्वर इसे प्री-फ़्लाइट और पोस्ट-स्पॉन पर लागू करता है — एक अनुपलब्ध localhost सर्वर कभी भी चुपचाप चलता नहीं छोड़ा जाता
• स्वचालित URL स्वच्छीकरण — यदि एजेंट रिस्पॉन्स में localhost URL छोड़ देता है, तो respond_* टूल्स उसे मैचिंग टनल URL से पुनः लिख देते हैं ताकि आपके फ़ोन को हमेशा एक पहुँच योग्य लिंक मिले
• कस्टम टूल्स — एजेंट CLI टूल्स इंस्टॉल कर सकता है और उन्हें नई क्षमताओं के रूप में रजिस्टर कर सकता है
• वर्शनिंग — वर्कस्पेस फ़ाइलों के लिए स्वचालित git वर्शनिंग; स्किल्स और अनुमतियों के लिए कॉन्फ़िग बैकअप
• वेब डैशबोर्ड — बैकग्राउंड जॉब्स का लाइव ओवरव्यू, प्रति उपयोगकर्ता कस्टमाइज़ करने योग्य। /dashboard और /api/jobs डिज़ाइन से अनप्रमाणित हैं — नेटवर्क लेयर पर एक्सेस सीमित करें (Tailscale ACL, फ़ायरवॉल, बेसिक ऑथ के साथ रिवर्स प्रॉक्सी) या यदि आपको इसकी आवश्यकता नहीं है तो DASHBOARD=false सेट करें
• HTTPS टनलिंग — Tailscale, ngrok और Cloudflare Tunnel के लिए बिल्ट-इन सपोर्ट
• सिस्टम सर्विस — macOS, Linux, या Windows पर परसिस्टेंट सर्विस के रूप में इंस्टॉल करें
• रेट लिमिटिंग — कॉन्फ़िगर करने योग्य थ्रेशोल्ड के साथ प्रति-टोकन रिक्वेस्ट लिमिट

आवश्यकताएं

#

• Bun रनटाइम
• आपके LLM प्रोवाइडर के लिए API कुंजी या OAuth क्रेडेंशियल
• (वैकल्पिक) HTTPS टनलिंग के लिए Tailscale, ngrok, या cloudflared

त्वरित शुरुआत

#

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

# इंटरैक्टिव सेटअप — प्रोवाइडर, मॉडल, ऑथ टोकन, पोर्ट चुनें
bun run setup

# सर्वर + HTTPS टनल शुरू करें
bun run dev:tunnel

सेटअप विज़ार्ड आपको LLM प्रोवाइडर चुनने, प्रमाणीकरण कॉन्फ़िगर करने और टूल अनुमतियां सेट करने में मार्गदर्शन करेगा।

चलने के बाद, प्रदर्शित URL को PocketHook सेटिंग्स में कॉपी करें:

यह कैसे काम करता है

#

1. आप PocketHook में एक संदेश भेजते हैं
2. सर्वर इसे आपके चुने हुए LLM को बातचीत के इतिहास, याद की गई मेमोरीज़ और उपलब्ध टूल्स के साथ फ़ॉरवर्ड करता है
3. LLM संदेश को प्रोसेस करता है — यह शेल कमांड चला सकता है, फ़ाइलें पढ़/लिख सकता है, वेब सर्च कर सकता है, बैकग्राउंड जॉब्स शेड्यूल कर सकता है, तथ्य याद रख सकता है, या डेव सर्वर शुरू कर सकता है
4. रिस्पॉन्स PocketHook फ़ॉर्मेट (msg + shortcut + data + url) में लौटाया जाता है
5. PocketHook संदेश प्रदर्शित करता है और आपके डिवाइस पर कोई भी Shortcuts निष्पादित करता है

समर्थित LLM प्रोवाइडर

#

bun run switch से कभी भी प्रोवाइडर बदलें। Ollama और LM Studio पूरी तरह आपकी मशीन पर चलते हैं — कोई API कुंजी नहीं चाहिए, कोई डेटा आपके नेटवर्क से बाहर नहीं जाता।

मेमोरी

#

मेमोरी सिस्टम में तीन लेयर हैं, प्रत्येक एक अलग उद्देश्य पूरा करती है।

सिमेंटिक मेमोरी डिज़ाइन MemPalace (एक मेमोरी पैलेस आर्किटेक्चर जो मेमोरीज़ को विंग्स, हॉल्स और रूम्स में व्यवस्थित करता है) और Tiago Forte की PARA मेथड (प्रोजेक्ट्स, एरियाज़, रिसोर्सेज़, आर्काइव) के विचारों को ज्ञान जीवनचक्र प्रबंधन के लिए जोड़ता है।

कन्वर्सेशन मेमोरी

#

FTS5 फ़ुल-टेक्स्ट सर्च के साथ SQLite। सभी संदेश टाइमस्टैम्प और सेशन ID के साथ स्टोर होते हैं।

• शॉर्ट-टर्म — प्रति सेशन मेमोरी में अंतिम MAX_HISTORY संदेश रखे जाते हैं
• लॉन्ग-टर्म — सभी संदेश SQLite में पर्सिस्ट होते हैं, FTS5 कीवर्ड मैचिंग से सर्च करने योग्य
• प्रति टर्न रिकॉल — जब सिमेंटिक मेमोरी चालू होती है, तो MAX_RECALL नियंत्रित करता है कि हर टर्न में प्रॉम्प्ट में कितनी प्रासंगिक मेमोरीज़ इंजेक्ट होंगी
• सेशन SESSION_TTL_MINUTES के बाद समाप्त होते हैं, लेकिन लॉन्ग-टर्म मेमोरी हमेशा बनी रहती है

इन्हें इंटरैक्टिव रूप से bun run memory से ट्यून करें।

सिमेंटिक मेमोरी

#

VECTOR_MEMORY=true और एक एम्बेडिंग प्रोवाइडर (Ollama, LM Studio, या OpenAI) आवश्यक है।

हर मेमोरी को एक वेक्टर के रूप में एम्बेड किया जाता है और LLM द्वारा चार आयामों में स्वचालित रूप से वर्गीकृत किया जाता है:

• विंग — इकाई: user, person:john, project:blog, place:london
• रूम — प्रकार: facts, preferences, events, decisions, requests
• हॉल — विषय: personal, tech, health, travel, food, work
• स्टेटस — PARA वर्गीकरण: project, area, resource, archive

जब आप कोई प्रश्न पूछते हैं, तो इकाई निष्कर्षण सबसे प्रासंगिक विंग्स पर वेक्टर सर्च को केंद्रित करता है। परिणाम FTS5 कीवर्ड परिणामों के साथ रेसिप्रोकल रैंक फ़्यूज़न का उपयोग करके मर्ज किए जाते हैं — ताकि आपको कीवर्ड और सिमेंटिक मैचिंग दोनों का सर्वश्रेष्ठ मिले।

नॉलेज ग्राफ

#

संरचित, टिकाऊ तथ्यों के लिए एक टेम्पोरल ट्रिपल स्टोर:

• ट्रिपल: (विषय, प्रेडिकेट, ऑब्जेक्ट) valid_from / valid_until टाइमस्टैम्प के साथ
• सिंगल-वैल्यू प्रेडिकेट (lives_in, partner) अपडेट पर पुरानी वैल्यू को ऑटो-इनवैलिडेट करते हैं
• मल्टी-वैल्यू प्रेडिकेट (child, friend, hobby) बिना इनवैलिडेशन के सह-अस्तित्व में रहते हैं
• नॉलेज ग्राफ तथ्य हर बातचीत में याद की गई मेमोरीज़ के साथ इंजेक्ट किए जाते हैं

जब आप एजेंट को बताते हैं “मैं बर्लिन चला गया”, तो यह पुरानी lives_in ट्रिपल को इनवैलिडेट करता है और एक नई बनाता है — स्वचालित रूप से।

PARA जीवनचक्र

#

हर मेमोरी को PARA स्टेटस से टैग किया जाता है:

• प्रोजेक्ट — सक्रिय, समय-सीमित कार्य
• एरिया — चल रही ज़िम्मेदारियां
• रिसोर्स — संदर्भ सामग्री (सूचियां, सिफ़ारिशें, गाइड)
• आर्काइव — पूर्ण या रद्द किए गए प्रोजेक्ट

जब कोई प्रोजेक्ट पूरा होता है, तो एजेंट सिमेंटिक सिमिलैरिटी का उपयोग करके केवल उस प्रोजेक्ट की मेमोरीज़ को आर्काइव करता है, जबकि भविष्य के उपयोग के लिए रेफ़रेंस मटीरियल को संरक्षित रखता है।

प्रोजेक्ट-एंड कैस्केड

#

कहें “मैं बार्सिलोना की अपनी यात्रा रद्द कर रहा हूँ” और एक ही टूल कॉल सब कुछ संभाल लेता है:

1. प्रोजेक्ट के वेक्टरों को आर्काइव करता है (बार्सिलोना से जुड़े इवेंट्स, डिसिज़न्स, रिक्वेस्ट्स)।
2. हर सक्रिय नॉलेज-ग्राफ ट्रिपल को इनवैलिडेट करता है जिसका प्रेडिकेट प्रोजेक्ट स्लग से मेल खाता हो (scheduled_visit_barcelona, planning_visit_barcelona, confirmed_visit_barcelona)।
3. समापन को एक नए ट्रिपल के रूप में रिकॉर्ड करता है: (user, "cancelled_visit_barcelona", "2026-04-15")।

मिलान बाउंड्री-अवेयर है — revisit_barcelona नाम का एक अलग प्रोजेक्ट अछूता रहता है। एजेंट को अब तीन अलग कॉल सही क्रम में ऑर्केस्ट्रेट नहीं करनी पड़तीं, इसलिए छोटे मॉडल भी इसे सही कर लेते हैं।

यदि VECTOR_MEMORY अक्षम है या एम्बेडिंग प्रोवाइडर उपलब्ध नहीं है, तो सिस्टम बिना किसी त्रुटि के केवल FTS5 पर वापस आ जाता है।

स्किल्स

#

स्किल्स skills/ में .md फ़ाइलें हैं जो iOS Shortcuts परिभाषित करती हैं जिन्हें एजेंट ट्रिगर कर सकता है और/या व्यवहार नियम। ये डायनामिक लोडिंग का उपयोग करती हैं: सिस्टम प्रॉम्प्ट में केवल एक कॉम्पैक्ट इंडेक्स (शीर्षक, विवरण, शॉर्टकट सूची) इंजेक्ट होता है। एजेंट load_skill टूल के माध्यम से मांग पर पूरा कंटेंट लोड करता है, जिससे आप जितनी अधिक स्किल्स जोड़ते हैं टोकन उपयोग कम रहता है।

प्रत्येक स्किल फ़ाइल 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 फ़ील्ड्स

#

स्किल्स बिना शॉर्टकट के व्यवहार नियम भी हो सकती हैं (जैसे, “पारिवारिक यात्रा कैसे प्लान करें”)। इनके लिए shortcuts: [] का उपयोग करें।

एजेंट मांगने पर स्किल्स बना और प्रबंधित कर सकता है — इससे कहें “मेरी लाइट्स कंट्रोल करने के लिए एक स्किल बनाओ” और यह आपके लिए .md फ़ाइल लिख देगा। नई और संपादित स्किल्स हमेशा आपकी यूज़र लेयर (data/user/skills/) में लगती हैं, इसलिए फ़्रेमवर्क अपडेट कभी उन्हें ओवरराइट नहीं करते। नीचे अपने एजेंट को कस्टमाइज़ करना सेक्शन देखें।

Mac सर्वर पर शॉर्टकट निष्पादित करना

#

जब किसी स्किल में target: mac होता है, तो शॉर्टकट iOS डिवाइस पर भेजे जाने के बजाय shortcuts run CLI के माध्यम से Mac सर्वर पर चुपचाप चलते हैं। यह उन एक्शनों के लिए आदर्श है जो iCloud-सिंक कंटेंट बनाते हैं — नोट्स, रिमाइंडर, कैलेंडर इवेंट्स — क्योंकि परिणाम PocketHook ऐप को कुछ भी किए बिना स्वचालित रूप से आपके सभी डिवाइसों में सिंक हो जाते हैं।

यह कैसे काम करता है:

1. एजेंट तय करता है कि एक शॉर्टकट चलना चाहिए (जैसे “आज की मीटिंग नोट्स के साथ एक नोट बनाओ”)
2. सर्वर shortcuts run "shortcutName" को इनवोक करता है, डेटा को stdin पर JSON के रूप में पास करके, उसी wrapper फ़ॉर्मेट में जो PocketHook iOS उपयोग करता है
3. यदि sync_app सेट है, तो सर्वर iCloud सिंक को मजबूर करने के लिए उस ऐप को बैकग्राउंड में कुछ पलों के लिए खोलता है (open -gj -a Notes), फिर 5 सेकंड बाद बंद कर देता है
4. उपयोगकर्ता को चैट में पुष्टिकरण संदेश मिलता है; शॉर्टकट स्वयं डिवाइस पर नहीं भेजा जाता

आवश्यकताएँ:

• सर्वर macOS पर चल रहा होना चाहिए — shortcuts run केवल macOS के लिए है। अन्य प्लेटफ़ॉर्म पर, सर्वर एक चेतावनी लॉग करता है और डिवाइस निष्पादन पर वापस जाता है
• शॉर्टकट सर्वर Mac के Shortcuts.app में इंस्टॉल होना चाहिए
• शॉर्टकट को इनपुट के रूप में Dictionary की अपेक्षा करनी चाहिए (PocketHook डेटा को { context, timestamp, app, data } में रैप करता है)

target: mac का उपयोग कब करें:

• iCloud-सिंक एक्शन्स (Notes, Reminders, Calendar) — परिणाम वैसे भी हर डिवाइस तक पहुँच जाता है
• लंबे समय तक चलने वाली प्रोसेसिंग जिसे आप iOS डिवाइस से हटाना चाहते हैं
• कोई भी शॉर्टकट जिसे iPhone के UI के साथ इंटरैक्ट करने की ज़रूरत नहीं है

target: device (डिफ़ॉल्ट) कब बनाए रखें:

• ऐसे शॉर्टकट जिन्हें iPhone-केवल फ़ीचर्स (कैमरा, सटीक स्थान, लोकल ऐप ऑटोमेशन) चाहिए
• ऐसे शॉर्टकट जो उपयोगकर्ता से इंटरैक्टिव इनपुट मांगते हैं
• ऐसे शॉर्टकट जो केवल-iOS ऐप्स के App Intents का उपयोग करते हैं

बैकग्राउंड जॉब्स

#

एजेंट से कार्य शेड्यूल करने के लिए कहें और यह बाकी संभाल लेगा:

• “हर सुबह 8 बजे मौसम जांचो और एक नोट बनाओ”
• “हर घंटे यह स्क्रिप्ट चलाओ”
• “30 मिनट में मुझे ईमेल जांचने की याद दिलाओ”

जॉब्स cron एक्सप्रेशन (0 8 * * *) और सरल इंटरवल (30m, 1h, 2d) का समर्थन करती हैं। /jobs एंडपॉइंट पोल करने पर परिणाम PocketHook को डिलीवर होते हैं।

दो निष्पादन प्रकार:

• शेल — एक bash कमांड चलाता है, आउटपुट कैप्चर करता है। पूरा होने पर Shortcut ट्रिगर कर सकता है
• प्रॉम्प्ट — AI एजेंट द्वारा पूर्ण टूल एक्सेस के साथ प्रोसेस किया जाता है, पूर्ण PocketHook रिस्पॉन्स स्टोर करता है

डेव सर्वर

#

जब एजेंट वर्कस्पेस में एक वेब प्रोजेक्ट बनाता है (Hugo, Astro, Next.js, Flask, Go, आदि), तो यह सक्रिय रूप से इसे सर्व करने की पेशकश करता है:

• प्रीव्यू — त्वरित देखने के लिए ऑटो-असाइन किए गए पोर्ट पर एक लोकल डेव सर्वर शुरू करता है
• पब्लिक — सर्वर शुरू करता है और इसे HTTPS टनल के माध्यम से एक्सपोज़ करता है ताकि यह कहीं से भी एक्सेसिबल हो

एजेंट जीवनचक्र प्रबंधित करता है: शुरू, बंद, और चल रहे सर्वर सूचीबद्ध करें। मुख्य सर्वर बंद होने पर सभी सर्वर साफ़ कर दिए जाते हैं।

टनल कॉन्ट्रैक्ट

#

जब एजेंट टनल एक्सपोज़र के अनुरोध के साथ सर्वर शुरू करता है, तो रनटाइम इसे लागू करता है: यदि कोई टनल टूल (Tailscale, ngrok, cloudflared) इंस्टॉल नहीं है, तो सर्वर शुरू करने से इनकार करता है। यदि स्पॉन के बाद टनल सेटअप विफल हो जाता है, तो ऑर्फ़न प्रोसेस बंद कर दी जाती है और एजेंट को स्पष्ट रूप से बताया जाता है — ताकि वह प्रीव्यू मोड पर वापस जा सके या आपसे टनल इंस्टॉल करने के लिए कह सके। टनलिंग चालू होने पर लौटाया गया URL हमेशा टनल URL होता है, इस नोट के साथ कि लोकल URL केवल-होस्ट है।

सुरक्षा जाल के रूप में, हर respond_* टूल अपने संदेश को पोस्ट-प्रोसेस करता है: जवाब में चुपके से आने वाला कोई भी localhost या 127.0.0.1 URL स्वचालित रूप से मैचिंग टनल URL से पुनः लिखा जाता है जब एक प्रबंधित सर्वर के पास टनल URL होता है। जब पुनः नहीं लिख सकता, तो आपको फ़ोन पर टूटे लिंक के बजाय लॉग में चेतावनी मिलती है।

डैशबोर्ड

#

/dashboard पर बिल्ट-इन वेब डैशबोर्ड बैकग्राउंड जॉब्स का लाइव ओवरव्यू दिखाता है।

डिज़ाइन से अनप्रमाणित। /dashboard और /api/jobs दोनों खुले GET एंडपॉइंट हैं — कोई भी जो होस्ट तक पहुँच सकता है, जॉब्स की सूची देख सकता है। नेटवर्क लेयर पर एक्सेस सीमित करें (Tailscale ACL, फ़ायरवॉल, बेसिक ऑथ के साथ रिवर्स प्रॉक्सी) या यदि आपको इसकी आवश्यकता नहीं है तो DASHBOARD=false सेट करें। PocketHook iOS ऐप इन एंडपॉइंट्स का उपयोग नहीं करता।

यह पूरी तरह कस्टमाइज़ करने योग्य है:

• क्विक एडिट — सरल कस्टमाइज़ेशन के लिए workspace/dashboard/ में एक dashboard.html रखें
• पूर्ण प्रोजेक्ट — workspace/dashboard/ में एक फ़्रेमवर्क प्रोजेक्ट (Svelte, React, Vue, आदि) बनाएं जिसका बिल्ड आउटपुट dist/ में हो

एजेंट से अपना डैशबोर्ड कस्टमाइज़ करने के लिए कहें और यह बाकी संभाल लेगा — हर उपयोगकर्ता को एक अद्वितीय, व्यक्तिगत डैशबोर्ड मिलता है।

कस्टम टूल्स

#

एजेंट CLI टूल्स इंस्टॉल कर सकता है और उन्हें नई क्षमताओं के रूप में रजिस्टर कर सकता है — सर्वर कोड को संशोधित किए बिना खुद को विस्तारित करता है।

उदाहरण के लिए, कहें “Playwright इंस्टॉल करो और इसका उपयोग स्क्रीनशॉट लेने के लिए करो”। एजेंट:

1. डिपेंडेंसी इंस्टॉल करेगा
2. एक टूल डेफ़िनिशन बनाएगा (एक सरल .md फ़ाइल)
3. भविष्य की बातचीत में नए टूल का उपयोग करेगा

कस्टम टूल्स हॉट-रीलोड होते हैं — रीस्टार्ट की ज़रूरत नहीं। टूल हटाने के लिए .md फ़ाइल हटाएं।

वर्शनिंग

#

सभी उपयोगकर्ता डेटा स्वचालित रूप से वर्शन किया जाता है:

• वर्कस्पेस फ़ाइलें — workspace/ के अंदर लोकल git रिपो से ट्रैक की जाती हैं। हर राइट एक ऑटो-कमिट बनाता है। एजेंट से कहें “आखिरी बदलाव वापस करो” या मैन्युअल रूप से git revert HEAD का उपयोग करें
• कॉन्फ़िग फ़ाइलें — config/agent-instructions.md, config/personality.md, skills/, और permissions.json हर संशोधन से पहले बैकअप होती हैं। प्रति फ़ाइल 20 वर्शन तक

Git वैकल्पिक है — यदि इंस्टॉल नहीं है, तो वर्कस्पेस परिवर्तन अनवर्शन्ड होते हैं। कॉन्फ़िग बैकअप हमेशा काम करते हैं।

अपने एजेंट को कस्टमाइज़ करना

#

एजेंट सर्वर एक न्यूनतम फ़्रेमवर्क बेस के साथ आता है और उम्मीद करता है कि आप अपना कस्टमाइज़ेशन ऊपर लेयर करें। रनटाइम दोनों को अलग रखता है ताकि फ़्रेमवर्क अपडेट आपके काम को कभी ख़त्म न करें।

फ़्रेमवर्क बनाम उपयोगकर्ता

#

pockethook-agent-server/
├── skills/                      # फ़्रेमवर्क-शिप्ड स्किल्स (केवल-पठनीय)
├── custom-tools/                # फ़्रेमवर्क-शिप्ड टूल्स के लिए आरक्षित (केवल-पठनीय)
├── config/
│   ├── agent-instructions.md    # फ़्रेमवर्क एजेंट इंस्ट्रक्शन (केवल-पठनीय)
│   └── personality.md           # फ़्रेमवर्क व्यक्तित्व (केवल-पठनीय)
└── data/user/                   # आपका कस्टमाइज़ेशन यहाँ रहता है (git-ignored)
    ├── skills/                  # आपकी अपनी स्किल्स (फ़ाइलनाम पर बेस को ओवरराइड करती हैं)
    ├── custom-tools/            # आपके इंस्टॉल किए गए कस्टम टूल्स
    ├── instructions.md          # एजेंट इंस्ट्रक्शन में आपके जोड़
    └── prefs.json               # {{prefs.key}} के रूप में रेफ़रेंस की गईं टाइप्ड वैल्यूज़

उपयोगकर्ता कस्टमाइज़ेशन समर्पित टाइप्ड टूल्स (create_user_skill, create_custom_tool) के माध्यम से लिखा जाता है ताकि परिणामी फ़ाइलें हमेशा लोडर के फ़ॉर्मेट से मेल खाएँ। write टूल skills/, custom-tools/, या config/ के अंतर्गत किसी भी पथ को भी अस्वीकार करता है और एजेंट को data/user/* पर पुनर्निर्देशित करता है — इसलिए सीधे फ़ाइल संपादन भी अंततः यूज़र लेयर में जाते हैं।

बेस custom-tools/ डायरेक्टरी के बारे में नोट। आज यह केवल एक टेम्पलेट (_example.md) रखती है जिसे लोडर अनदेखा कर देता है — एजेंट आपके लिए जो भी टूल इंस्टॉल करता है, वह data/user/custom-tools/ में जाता है। डायरेक्टरी इसलिए आरक्षित है कि भविष्य के फ़्रेमवर्क रिलीज़ आपके इंस्टॉल्स को ओवरराइट किए बिना वैकल्पिक बिल्ट-इन टूल्स शिप कर सकें। जब ऐसा हो, तब भी टूल-नाम टकराव पर आपकी यूज़र-लेयर फ़ाइलें ही जीतती हैं, इसलिए माइग्रेट करने को कुछ नहीं है।

कस्टमाइज़ करने के चार तरीक़े

#

आपको ये फ़ाइलें कभी हाथ से नहीं लिखनी पड़तीं। बस एजेंट को बताएँ कि आप क्या चाहते हैं और यह स्वचालित रूप से सही लेयर चुन लेता है।

{{prefs.*}} के साथ टाइप्ड प्रेफ़रेंस

#

मान लीजिए आप एक रूट-प्लानर स्किल लिखते हैं जिसे आपका डिफ़ॉल्ट स्टार्टिंग पॉइंट जानना है। “मैड्रिड” को स्किल में हार्डकोड करने के बजाय, प्रेफ को रेफ़रेंस करें:

- **स्टार्टिंग पॉइंट**: {{prefs.routeOrigin}}, जब तक उपयोगकर्ता कोई भिन्न ऑरिजिन निर्दिष्ट न करे।

और वैल्यू data/user/prefs.json में स्टोर करें:

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

स्किल लोड होने पर सर्वर प्लेसहोल्डर्स को सब्स्टिट्यूट करता है। नेस्टेड कुंजियाँ ({{prefs.tunnel.domain}}) भी काम करती हैं। अज्ञात कुंजियाँ अछूती रहती हैं ताकि टाइपो दिखाई दें।

फ़्रेमवर्क बेस को सीधे संपादित करना

#

अगर आप सेल्फ-होस्टिंग कर रहे हैं और फ़्रेमवर्क को ख़ुद ट्वीक करना चाहते हैं, तो आप config/agent-instructions.md, config/personality.md, skills/, या custom-tools/ को सीधे संपादित कर सकते हैं — जब आप फ़ाइल एडिटर का उपयोग करते हैं तो सर्वर आपको नहीं रोकता। लेकिन एजेंट किसी बातचीत से उन पथों पर नहीं लिखेगा। और फ़्रेमवर्क अपडेट आपके एडिट्स को ओवरराइट कर देंगे। जो कुछ भी आप रखना चाहते हैं उसके लिए यूज़र लेयर को प्राथमिकता दें।

सर्वर का विस्तार

#

• कस्टम टूल्स — एजेंट से CLI टूल्स इंस्टॉल करने के लिए कहें; वे स्वचालित रूप से data/user/custom-tools/ में लगते हैं
• स्किल्स जोड़ें — एजेंट से स्किल बनाने के लिए कहें; फ़ाइल data/user/skills/ में जाती है
• व्यवहार बदलें — एजेंट से ग्लोबल नियम लागू करने के लिए कहें; यह data/user/instructions.md में जुड़ जाता है
• अनुमतियां कॉन्फ़िगर करें — एजेंट कौन से टूल्स उपयोग कर सकता है इसे नियंत्रित करने के लिए bun run permissions चलाएं
• बिल्ट-इन टूल्स जोड़ें — गहरे इंटीग्रेशन के लिए src/tools.ts में नई टूल फ़ंक्शन इम्प्लीमेंट करें (सर्वर को फ़ोर्क करने की आवश्यकता है)

कॉन्फ़िगरेशन

#

सभी सेटिंग्स .env (जो bun run setup द्वारा बनाया जाता है) में स्टोर होती हैं। मुख्य विकल्प:

पूर्ण कॉन्फ़िगरेशन संदर्भ GitHub रिपॉज़िटरी में देखें।

सर्विस के रूप में चलाना

#

स्वचालित रूप से शुरू होने वाली परसिस्टेंट सर्विस के रूप में इंस्टॉल करें:

bun run service install

INSTANCE_NAME डिफ़ॉल्ट रूप से प्रोजेक्ट डायरेक्टरी का बेसनेम होता है जिसमें pockethook- उपसर्ग हटा दिया जाता है (उदाहरण के लिए, pockethook-agent-server/ में चेकआउट agent-server बन जाता है)। एक ही मशीन पर कई चेकआउट को बिना टकराव के चलाने के लिए स्पष्ट रूप से सेट करें — हर इंस्टेंस अपना data/ और लॉग्स रखता है।

bun run service status, restart, stop, या uninstall से प्रबंधित करें।

सुरक्षा

#

• HTTPS आवश्यक — PocketHook सभी URL के लिए HTTPS लागू करता है
• Bearer टोकन प्रमाणीकरण — ऐप और सर्वर के बीच साझा सीक्रेट
• रेट लिमिटिंग — प्रति-टोकन लिमिट दुरुपयोग रोकती हैं
• सैंडबॉक्स्ड टूल्स — शेल कमांड और फ़ाइल एक्सेस अनुमतियों से प्रतिबंधित
• ब्लॉक किए गए पैटर्न — खतरनाक कमांड (sudo, rm -rf /) डिफ़ॉल्ट रूप से ब्लॉक
• वर्किंग डायरेक्टरी सीमा — एजेंट अपनी निर्दिष्ट डायरेक्टरी से बाहर नहीं जा सकता
• संवेदनशील फ़ाइलें सुरक्षित — .env, .git, *.key, *.pem एजेंट एक्सेस से ब्लॉक
• स्वचालित वर्शनिंग — आसान रोलबैक के लिए सभी वर्कस्पेस परिवर्तन git-ट्रैक्ड