VPS پر OpenTag self-host کرنے کا طریقہ

OpenTag میں کسی agent کا ذکر کرنے پر کیا ہوتا ہے

OpenTag، Slack thread یا GitHub issue میں موجود @mention کو آپ کے زیرِ انتظام machine پر coding agent run میں تبدیل کرتا ہے۔ کوئی شخص issue پر @opentag investigate this comment کرتا ہے۔ ایک listener platform event وصول کرتا ہے، اس کے signature کی تصدیق کرتا ہے، mention کو bound project سے match کرتا ہے، local checkout کے خلاف coding agent شروع کرتا ہے، اور نتیجہ اسی thread میں واپس post کرتا ہے۔

یہ project MIT licensed ہے اور amplifthq/opentag میں موجود ہے۔ August 2026 تک تازہ ترین tagged release v0.9.0 ہے، جو 28 July 2026 کو شائع ہوئی، اور یہ npm package کے طور پر فراہم کی جاتی ہے۔ کوئی official container image موجود نہیں، اس لیے آپ کو npm version pin کرنا ہوتا ہے۔ ذیل کے ہر command میں یہی version pin کیا گیا ہے۔

یہ project GitHub کی وجہ سے laptop project کے بجائے VPS project بنتا ہے۔ GitHub repository events فراہم کرنے کے لیے اس URL پر HTTP request بھیجتا ہے جسے آپ ایک بار register کرتے ہیں، اس لیے اس URL کو اگلے دن بھی اسی address پر جواب دینا ہوگا۔

چار بنیادی اجزا

listener پلیٹ فارم کے events وصول کرتا ہے، اور ہر پلیٹ فارم کا اپنا listener ہوتا ہے۔ GitHub listener، port 3050 پر موجود ایک HTTP endpoint ہے، جس کا path /github/webhooks ہے۔ Slack Events API listener، port 3040 پر /slack/events پر موجود ہے۔ Slack کو Socket Mode میں بھی چلایا جا سکتا ہے۔ اس صورت میں app ایک outbound WebSocket کھولتی ہے اور کسی inbound port کی ضرورت نہیں رہتی۔

dispatcher رابطہ کار ہے۔ یہ بطور default port 3030 پر سنتا ہے، run state کو OPENTAG_DATABASE_PATH سے متعین local database file میں محفوظ کرتا ہے، اور ہر run کے لیے audit trail ریکارڈ کرتا ہے۔ اس port تک box کے باہر سے کبھی رسائی نہیں ہونی چاہیے۔

runner local daemon ہے۔ یہ کام کے لیے polling کرتا ہے، ایک run کو claim کرتا ہے، اس پر lease برقرار رکھتا ہے، اور run کے فعال رہنے کے دوران بطور default ہر 15 سیکنڈ بعد heartbeat بھیجتا ہے۔ اگر کسی claimed run کا project target موجود نہ ہو یا اس کے اپنے config میں موجود allowlist سے باہر ہو تو یہ اسے مسترد کر دیتا ہے۔ یہی check کسی GitHub event کو اس repository کی طرف agent بھیجنے سے روکتا ہے جسے آپ نے bind نہیں کیا۔

executor خود coding agent ہے۔ OpenTag اسے ACP (agent client protocol) کے ذریعے launch کرتا ہے۔ یہ ایک JSON-RPC protocol ہے جو standard input اور output پر استعمال ہوتا ہے، اس لیے agent، OpenTag کی فراہم کردہ working directory کے اندر child process کے طور پر چلتا ہے۔ built-in names میں echo، codex، claude-code، cursor، opencode، hermes اور openclaw شامل ہیں۔ ابتدا echo سے کریں۔ مثال config اسی executor کے ساتھ فراہم کی جاتی ہے، اور یہ ثابت کرتا ہے کہ model کے آپ کے code کو تبدیل کرنے سے پہلے پورا راستہ درست کام کر رہا ہے۔

ترتیب کبھی تبدیل نہیں ہوتی: پلیٹ فارم event، signature check، run record، claim، agent، اور thread میں reply۔

لیپ ٹاپ اور tunnel کافی کیوں نہیں ہیں

GitHub کی setup guide آپ کو ngrok http 3050 چلانے اور tunnel host کو repository webhook میں paste کرنے کی ہدایت دیتی ہے۔ یہ پہلے دس منٹ تک کام کرتا ہے۔ جب بھی process restart ہوتا ہے، free tunnel host تبدیل ہو جاتا ہے، اور laptop sleep میں جانے پر یہ موجود نہیں رہتا۔ GitHub پرانا payload URL محفوظ رکھتا ہے اور اسی پر دوبارہ requests بھیجتا رہتا ہے۔ اس لیے webhook settings کا Recent Deliveries tab failures سے بھر جاتا ہے، جبکہ thread خاموش رہتا ہے۔ کسی کو ایک ہفتے تک معلوم نہیں ہوتا، کیونکہ ایسا webhook جو کچھ نہیں کرتا، بالکل ایسے bot جیسا دکھائی دیتا ہے جس کا کسی نے ذکر نہیں کیا۔

VPS ان دونوں مسائل کو حل کرتا ہے۔ DNS name تبدیل نہیں ہوتا، اس لیے ایک بار paste کیا گیا payload URL درست رہتا ہے۔ Machine sleep میں نہیں جاتی، اس لیے 02:00 بجے کیا گیا comment بھی جواب حاصل کرتا ہے۔ پہلے box کو درست طریقے سے تیار کریں: نئے VPS پر پہلے دس منٹ میں login user اور firewall کا احاطہ کیا گیا ہے جنہیں یہ guide فرض کرتی ہے۔

Slack اس سے مستثنیٰ ہے۔ Socket Mode میں یہ outbound connection قائم کرتا ہے اور اسے public URL کی ضرورت نہیں ہوتی، اس لیے صرف Slack پر مبنی deployment بند network میں رہ سکتی ہے۔ GitHub میں اس کے مساوی سہولت نہیں ہے۔ Repository webhooks inbound HTTP ہوتے ہیں، جس کا مطلب public endpoint ہے، اور اس کے لیے TLS (transport layer security) اور signature check درکار ہوتا ہے۔

Ubuntu پر pinned release سے OpenTag کو self-host کریں

OpenTag v0.9.0 کے لیے Node.js 22 یا اس کے بعد کا ورژن درکار ہے۔ Ubuntu 24.04 اپنی repository میں Node 18 فراہم کرتا ہے، اس لیے NodeSource سے انسٹال کریں۔

curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node -v

node -v کو v22 یا اس سے زیادہ دکھانا چاہیے۔ Node 20 پر انسٹالیشن EBADENGINE warning دکھاتی ہے، اور CLI شروع ہونے کے بعد ناکام ہو سکتا ہے۔

Service کے لیے الگ account بنائیں۔ Agent اسی user کی permissions کے ساتھ چلتا ہے، اس لیے یہ آپ کا login account نہیں ہونا چاہیے اور نہ ہی root ہونا چاہیے۔ VPS پر کم از کم استحقاق والے users میں بتایا گیا ہے کہ یہ علیحدگی اضافی مرحلے کے قابل کیوں ہے۔

sudo adduser --disabled-password --gecos "" opentag
sudo loginctl enable-linger opentag
sudo npm install -g @opentag/cli@0.9.0
command -v opentag

command -v opentag کو /usr/bin/opentag جیسا path دکھانا چاہیے۔ Linux میں linger setting اہم ہے: OpenTag اپنی background service systemd کے ذریعے انسٹال کرتا ہے، اور lingering کے بغیر user service آپ کا SSH session بند ہوتے ہی رک جاتی ہے۔

Setup اسی user کے طور پر چلائیں۔

sudo -iu opentag opentag setup

Setup چھ چیزیں پوچھتا ہے: CLI کی زبان، local listening address، coding agent، وہ local project جس پر کام کرنا ہے، محفوظ کیے جانے والے platform credentials، اور چلانے کا طریقہ۔ Listening address کو 127.0.0.1 پر رکھیں، کیونکہ nginx TLS terminate کر کے درخواستیں وہاں forward کرتا ہے، اس لیے listeners کو باہر سے قابل رسائی ہونے کی ضرورت نہیں ہوتی۔ GitHub کے لیے یہ repository کو owner/repo format میں، pull requests کھولنے کی اجازت، webhook port (default طور پر 3050)، اور token بھی پوچھتا ہے۔ آخر میں background service mode منتخب کریں۔ اگر آپ کے پاس پہلے سے config موجود ہے اور prompts کے بغیر service انسٹال کرنی ہے تو opentag setup --service یہ کام کرتا ہے۔

Config /home/opentag/.config/opentag/config.json میں اور runtime state /home/opentag/.local/state/opentag میں محفوظ ہوتی ہے۔ Setup کے بعد file لکھے جانے پر ان keys کو دستی طور پر جانچنا مفید ہے۔

{
  "runnerId": "runner_local",
  "dispatcherUrl": "http://localhost:3030",
  "runnerToken": "...",
  "approvalMode": "ask",
  "repositories": []
}

پرانے shared pairingToken کے بجائے runnerToken، یعنی runner-scoped bearer token، استعمال کریں۔ Config file credentials کو plain text میں رکھتی ہے، جب تک آپ انہیں secret reference سے تبدیل نہ کریں۔ Secret reference startup کے وقت value کو environment یا disk پر موجود file سے پڑھتا ہے۔ دونوں صورتوں میں یہ file system پر سب سے حساس چیز ہے: mode 600 رکھیں، اسے opentag کی ملکیت میں رکھیں، اور اسے کبھی بھی git repository کے اندر نہ رکھیں۔ اس موضوع کی مزید وضاحت AI agents سے secrets کو الگ رکھنے میں ہے۔

کسی چیز کو public کرنے سے پہلے installation چیک کریں۔

sudo -iu opentag opentag doctor
sudo -iu opentag opentag status

opentag doctor dispatcher، bindings، checkouts اور executors کو چیک کرتا ہے۔ opentag status config اور runtime state دکھاتا ہے، اور runs موجود ہونے کے بعد اسے ایک single run تک محدود بھی کیا جا سکتا ہے۔ doctor میں جو کچھ report ہو اسے platform کو اس box کی طرف point کرنے سے پہلے درست کریں۔

TLS کو سامنے رکھیں اور صرف دو paths کھولیں

nginx TLS کو terminate کرتا ہے اور بالکل دو paths کو آگے بھیجتا ہے۔ باقی ہر درخواست 404 واپس کرتی ہے، اس لیے host تلاش کرنے والا scanner یہ معلوم نہیں کر سکتا کہ اس کے پیچھے کیا چل رہا ہے۔

/etc/nginx/sites-available/opentag پر ایک سادہ port 80 server block لکھیں، جس میں نیچے دی گئی دو locations شامل ہوں، پھر Certbot کو TLS والا حصہ شامل کرنے دیں۔

sudo apt install -y nginx certbot python3-certbot-nginx
sudo ln -s /etc/nginx/sites-available/opentag /etc/nginx/sites-enabled/opentag
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d opentag.example.com

nginx -t، syntax is ok اور test is successful دکھاتا ہے۔ یہی typo اور ایسی reload کے درمیان واحد حفاظتی رکاوٹ ہے جو site کو بند کر سکتی ہے۔ Ubuntu 24.04 پر nginx کے ساتھ Certbot میں renewal اور ان طریقوں کی وضاحت ہے جن سے ACME (automatic certificate management environment) challenge ناکام ہو سکتا ہے۔ مکمل block اس طرح ہوگا۔

server {
    listen 443 ssl;
    server_name opentag.example.com;

    ssl_certificate     /etc/letsencrypt/live/opentag.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/opentag.example.com/privkey.pem;

    client_max_body_size 2m;

    location = /github/webhooks {
        proxy_pass http://127.0.0.1:3050;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location = /slack/events {
        proxy_pass http://127.0.0.1:3040;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location / {
        return 404;
    }
}

location = /github/webhooks میں = exact match ہے، جبکہ proxy_pass، port کے بعد کسی اضافی متن کے بغیر، اصل URI کو بغیر تبدیلی کے آگے بھیجتا ہے۔ = ہٹا دیں تو /github/webhooks/ کے تحت ہر path بھی forward ہو جائے گا، جو اس listener کی ضرورت سے زیادہ سطح ہے۔

Firewall محدود رہتا ہے۔

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Ports 3030، 3040 اور 3050 کبھی نہیں کھولے جاتے۔ تصدیق کریں کہ یہ ہر interface کے بجائے loopback سے bind ہیں۔

sudo ss -tlnp

ہر OpenTag line کو 127.0.0.1:3030 یا اس سے ملتی جلتی شکل میں ہونا چاہیے۔ 0.0.0.0:3050 والی line کا مطلب ہے کہ listener خود کو پورے internet کے سامنے پیش کر رہا ہے اور اسے صرف ufw روک رہا ہے۔ یہ firewall کی ایک غلطی سے open agent trigger بن سکتا ہے۔ ufw firewall basics میں وضاحت ہے کہ یہ default deny حقیقت میں کیا کر رہا ہے۔

دو checks front door کی تصدیق کرتے ہیں۔ curl -I https://opentag.example.com/، nginx سے 404 واپس کرتا ہے، جس سے ظاہر ہوتا ہے کہ certificate درست ہے اور catch-all بند ہے۔ /slack/events یا /github/webhooks کو بغیر signature کے بھیجی گئی request کو کبھی 200 واپس نہیں کرنا چاہیے۔

ہر signature کی تصدیق کریں، کیونکہ URL public ہے

کوئی بھی payload URL تلاش کر سکتا ہے۔ یہ آپ کی repository settings، browser history یا ticket میں paste کیے گئے screenshot میں موجود ہو سکتا ہے۔ Signature ہی وہ واحد چیز ہے جو حقیقی GitHub delivery کو کسی شخص کے ہاتھ سے لکھے گئے request سے الگ کرتی ہے۔

GitHub ہر delivery پر webhook secret سے signature بناتا ہے اور نتیجہ x-hub-signature-256 header میں بھیجتا ہے۔ OpenTag اس header کی platforms.github.webhookSecret کے مقابل تصدیق کرتا ہے۔ Project کی hardening notes میں یہ اصول براہِ راست درج ہے: /github/webhooks پر unsigned source events قبول نہ کریں۔ Slack ہر request پر SLACK_SIGNING_SECRET سے signature بناتا ہے اور timestamp شامل کرتا ہے، اس لیے captured body کو کئی گھنٹے بعد دوبارہ استعمال نہیں کیا جا سکتا۔

اس مرحلے کو چھوڑنا معمولی خطرہ نہیں ہے۔ غیر مصدقہ endpoint ہاتھ سے لکھا ہوا issue_comment payload قبول کر لیتا ہے جس میں @opentag شامل ہو، اور OpenTag پھر آپ کے token کے ساتھ، آپ کے checkout میں، کسی اجنبی کی ہدایات پر coding agent چلاتا ہے۔ جواب اس thread میں بھیجا جاتا ہے جس کا نام fake payload میں دیا گیا ہو۔

OpenTag اس کے اوپر دو مزید layers شامل کرتا ہے۔ Source deliveries کو delivery ID کے ذریعے track کیا جاتا ہے، اس لیے اسی event کو دوبارہ deliver کرنے سے دوسری run شروع نہیں ہوتی۔ Runner calls idempotency keys قبول کرتی ہیں، اس لیے کسی call کو replay کرنے پر دوسری audit event شامل کیے بغیر success واپس آتا ہے۔

Rate limits configurable ہیں اور انہیں فعال رکھنا چاہیے۔ OPENTAG_RATE_LIMIT_WINDOW_MS اور OPENTAG_RATE_LIMIT_MAX_REQUESTS request rate کی حد مقرر کرتے ہیں، OPENTAG_MAX_REQUEST_BODY_BYTES body size کی حد مقرر کرتا ہے، اور حد سے بڑا payload 413 request_body_too_large کے ساتھ reject کر دیا جاتا ہے۔ OPENTAG_RATE_LIMIT_DISABLED=true local development کے لیے موجود ہے، اور public box پر اس کی کوئی جگہ نہیں۔ انہی notes کا ایک اور اصول ہے: public relay URL کے لیے HTTPS استعمال کرنا لازم ہے، جبکہ CLI صرف localhost کے لیے plain HTTP کی اجازت دیتا ہے۔

Bot کو دراصل کنک ٹوکن کے کون سے scopes درکار ہیں؟

GitHub پر OpenTag، GitHub App کے بجائے fine-grained personal access token استعمال کرتا ہے۔ دستاویزات کے مطابق App والا طریقہ زیرِ منصوبہ ہے اور آج کے default CLI setup کا حصہ نہیں ہے۔ اس کا ایک اہم نتیجہ ہے جسے لوگ نظرانداز کر دیتے ہیں: bot اس انسان کے طور پر comments کرتا ہے جس نے token بنایا ہو۔ Token ایسے account کے تحت بنائیں جس کا نام آپ ہر triage reply میں درج دیکھنے پر آمادہ ہوں۔

Scope کو setup guide کے مطابق محدود رکھیں۔ Only select repositories منتخب کریں اور ایک repository چنیں۔ Issues: Read and write اور Pull requests: Read and write کی اجازت دیں۔ کسی mention کو پڑھنے اور thread میں جواب دینے کے لیے اتنا کافی ہے۔

غور کریں کہ کیا شامل نہیں ہے: code کے لیے write access۔ OpenTag branches push نہیں کرتا، جب تک preparePullRequestBranch کو true پر set نہ کیا جائے۔ اس کے علاوہ githubApplyToken الگ موجود ہے، تاکہ code لکھنے والا token comments لکھنے والے token سے الگ رہے۔ انہیں الگ رکھیں، اور read-and-comment path کے چند ہفتے چلنے تک write token کو فعال نہ کریں۔

جس configuration سے بچنا چاہیے وہ ایسا token ہے جسے All repositories میں Contents: Read and write access حاصل ہو۔ اب ان repositories میں comment کرنے والا ہر شخص ایسے agent کو ہدایت دے سکتا ہے جس کے پاس commits کے حقوق ہیں، جبکہ audit trail میں یہ عمل token کے مالک سے منسوب ہوگا۔ Scope کو ایک وقت میں صرف ایک repository تک بڑھائیں، اور یہ agent کے قابلِ اعتماد ثابت ہونے کے بعد کریں۔

Slack پر bot کے scopes app_mentions:read، chat:write، reactions:write اور channels:history ہیں۔ Private channels کے لیے groups:history بھی درکار ہے، ساتھ ہی message.groups event کی subscription بھی ضروری ہے۔ Socket Mode کے لیے app-level token درکار ہے، جس میں connections:write شامل ہو اور جو xapp- سے شروع ہوتا ہو۔ channels:history ان public channels کی message history پڑھتا ہے جن میں bot شامل کیا گیا ہو۔ اس لیے bot کو ہر channel کے بجائے صرف مطلوبہ channels میں شامل کریں۔

ایک مسئلے کو ابتدا سے آخر تک چلائیں

Webhook پہلے ترتیب دیں۔ Repository میں Settings کھولیں، پھر Webhooks، اور اس کے بعد Add webhook منتخب کریں۔ Payload URL https://opentag.example.com/github/webhooks ہے، content type application/json ہے، اور secret وہی ہے جو setup نے بنایا تھا۔ Issue comments اور Pull request review comments کو subscribe کریں، اور کسی دوسری چیز کو نہیں۔

محفوظ کرتے ہی GitHub ایک ping delivery بھیجتا ہے۔ Recent Deliveries کھولیں اور دیکھیں کہ request سرور تک پہنچی بھی تھی یا نہیں۔ وہاں 502 کا مطلب ہے کہ nginx listener تک نہیں پہنچ سکا۔ یہ مقامی مسئلہ ہے، GitHub کا نہیں۔

اب اسے استعمال کریں۔ ایسا issue کھولیں جس میں bug بیان کیا گیا ہو، اور یہ comment کریں:

@opentag triage this. Reproduce the report against the current main branch, then reply with the file and function most likely responsible, plus the test you would write first.

ترتیب کے لحاظ سے یہ ہونا چاہیے۔ Recent Deliveries میں issue_comment delivery درج ہو اور اس کا response 2xx ہو۔ Dispatcher ایک run درج کرے۔ Runner اسے claim کرے اور heartbeat شروع کرے۔ Executor checkout کھول کر کام کرے۔ جواب اسی issue thread میں comment کے طور پر آ جائے۔ sudo -iu opentag opentag status run کے دوران اس کی حالت دکھاتا ہے، اس لیے آپ اندازے کے بجائے اسے monitor کر سکتے ہیں۔

پہلے حقیقی run سے قبل approvalMode کو ask پر set کریں۔ ask mode میں run رک جاتا ہے اور state تبدیل کرنے والا کوئی کام کرنے سے پہلے کسی شخص کی منظوری کا انتظار کرتا ہے۔ auto اور autonomous modes بھی موجود ہیں۔ انہیں بعد میں اس repository پر استعمال کرنا مناسب ہے جس کے transcripts آپ نے ایک ماہ تک پڑھے ہوں۔

Slack کی طرف اسی run کا آغاز channel میں /bind owner/repo سے ہوتا ہے، پھر mention کیا جاتا ہے۔ Bot /help، /status، /doctor، /stop اور /unbind confirm کا بھی جواب دیتا ہے۔ OPENTAG_SLACK_BINDING_ADMIN_USER_IDS کے ذریعے یہ محدود کریں کہ bindings کون تبدیل کر سکتا ہے۔ یہ Slack user IDs کی comma-separated فہرست ہے، کیونکہ binding public channel کو آپ کے سرور پر موجود checkout کے ساتھ map کرتی ہے۔

Triage ایک اچھا ابتدائی راستہ ہے، کیونکہ یہ data پڑھتا ہے اور لکھتا نہیں، جبکہ جواب کی جانچ آسان ہوتی ہے۔ اگلا مرحلہ Review ہے، جہاں agent issue کے بجائے diff پر comment کرتا ہے: self-hosted pull request review agent یہی architecture pull requests کے لیے استعمال کرتا ہے۔ اگر آپ چاہتے ہیں کہ agent کام کے دوران اپنے systems تک پہنچ سکے، تو اس کے لیے VPS پر MCP servers استعمال ہوتے ہیں۔ Web search وہ دوسری capability ہے جس کا Triage بار بار تقاضا کرتا ہے، اور agent کو اپنی SearXNG instance سے جوڑنا یہ lookups آپ کے زیر انتظام hardware پر رکھتا ہے، لیکن اس کے نتیجے میں ایک اور channel شامل ہو جاتا ہے جس کے ذریعے کسی اجنبی کا متن agent تک پہنچ سکتا ہے۔

جب agent سب کے سامنے غلط ہو جائے تو کیا ہوتا ہے؟

یہ غلط ہوگا۔ سوال یہ ہے کہ اس کی قیمت کیا ہوگی۔

Public issue پر غلط جواب ایسی comment ہوتا ہے جو اس نام کے تحت شائع ہوتی ہے جسے آپ کی ٹیم پہچانتی ہے، اور شائع ہوتے ہی GitHub اسے subscribed تمام افراد کو email کر دیتا ہے۔ Comment delete کرنے سے email واپس نہیں لیا جا سکتا۔ Slack notification کے ساتھ بھی یہی ہوتا ہے۔ اس لیے منصوبہ اس صورتِ حال کے لیے بنائیں کہ جواب public طور پر غلط ہوگا، نہ کہ اس مفروضے پر کہ وہ private طور پر درست ہوگا۔

چار انتخاب نقصان کو محدود کرتے ہیں، اور ان کی اہمیت آپ کے لکھے ہوئے کسی بھی prompt سے زیادہ ہے۔

• ask mode میں چلائیں، تاکہ agent تجویز دے، کوئی شخص منظوری دے، اور غلط plan کی قیمت صرف ایک click ہو۔
• preparePullRequestBranch کو false کی default قدر پر رہنے دیں، تاکہ خراب run کا بدترین نتیجہ غلط comment ہو، غلط branch نہ ہو۔
• ابتدا میں ایک repository اور ایک channel bind کریں۔ Runner ایسے ہر run کو مسترد کر دیتا ہے جس کا project target اس کی local allowlist سے باہر ہو، اس لیے unbound repository agent کو اپنے اندر نہیں لا سکتی۔
• Commenting token کو کسی بھی apply token سے الگ رکھیں، تاکہ write access واپس لینے سے triage بھی بند نہ ہو۔

Slack میں غلط سمت جانے والے run کے لیے /stop command موجود ہے۔ ہر run ایک audit record بھی چھوڑتا ہے جس میں وہ mention محفوظ ہوتا ہے جس نے اسے شروع کیا اور agent نے کیا کارروائی کی۔ بعد میں اسی record سے معلوم کیا جا سکتا ہے کہ خرابی کہاں ہوئی۔

سماجی پہلو configuration جتنا ہی اہم ہے۔ Bot کو ایسے ایک channel میں رکھیں جہاں لوگ machine کی موجودگی کی توقع رکھتے ہوں اور جانتے ہوں کہ یہ غلط ہو سکتی ہے۔ چالیس افراد کے channel میں پراعتماد مگر غلط جواب، جہاں سب یہ سمجھتے ہوں کہ کسی انسان نے اس کا جائزہ لیا ہے، بچائے گئے triage وقت سے زیادہ نقصان دہ ہوتا ہے۔ Channel description میں لکھیں کہ bot کا مالک کون ہے اور اس کے output کی جانچ کون کرتا ہے۔

بیک اپ، اپ گریڈ اور ورژن pin کرنا

دو paths میں تمام ضروری ڈیٹا موجود ہے: /home/opentag/.config/opentag/config.json اور /home/opentag/.local/state/opentag۔ پہلے path میں credentials ہیں، جبکہ دوسرے میں run history اور database file ہے۔ دونوں کا mode 600 کے ساتھ بیک اپ لیں اور انہیں box سے باہر محفوظ رکھیں۔ ان کے ضائع ہونے کا مطلب tokens اور bindings دوبارہ بنانا ہے، پورا server دوبارہ بنانا نہیں۔

اپ گریڈ کے لیے version bump اور restart درکار ہوتا ہے۔

sudo npm install -g @opentag/cli@0.9.0
sudo -iu opentag opentag service stop
sudo -iu opentag opentag service start
sudo -iu opentag opentag doctor

@latest کو track کرنے کے بجائے version pin کریں۔ یہ software آپ کی repository پر live token کے ساتھ coding agent چلاتا ہے۔ اس لیے رات کے وقت publish ہونے والی release اس configuration میں ایک غیر نظرثانی شدہ تبدیلی بن جاتی ہے۔ اس software کی security policy پچھلی versions میں fixes backport نہیں کرتی، اور fixes صرف newest release میں شامل ہوتی ہیں۔ اس لیے pinning کا مطلب ہے کہ آپ changelog پڑھیں اور جان بوجھ کر version تبدیل کریں۔ اس کا مطلب یہ نہیں کہ ہمیشہ v0.9.0 پر رہیں۔ July 2026 تک کی history میں ہر ماہ کئی releases موجود ہیں، اس لیے ہر bump سے پہلے release notes پڑھنا مناسب ہے۔

FAQ

کیا OpenTag چلانے کے لیے VPS ضروری ہے، یا laptop کافی ہے؟

صرف Slack کے لیے laptop کافی ہے، کیونکہ Socket Mode ایک outbound WebSocket کھولتا ہے اور کسی inbound port کی ضرورت نہیں ہوتی۔ GitHub مختلف ہے۔ Repository webhooks inbound HTTP کے ذریعے اس URL پر delivery کرتے ہیں جسے آپ ایک بار register کرتے ہیں، اس لیے یہ address مستقل رہنا چاہیے اور آپ کے سونے کے دوران بھی جواب دینا چاہیے۔ مفت account کا tunnel host ہر restart پر بدل جاتا ہے، اور GitHub پرانے host پر requests بھیجتا رہتا ہے۔ یہ repository کے Recent Deliveries tab میں failed entries اور thread میں خاموشی کی صورت میں ظاہر ہوتا ہے۔ مقررہ DNS name اور certificate والا VPS دونوں مسائل ختم کر دیتا ہے۔

OpenTag کو GitHub کی کون سی permissions درکار ہیں؟

ایک fine-grained personal access token جو Only select repositories تک محدود ہو، اور جس میں Issues: Read and write اور Pull requests: Read and write شامل ہوں۔ یہ mention پڑھنے اور thread میں جواب دینے کے لیے کافی ہے۔ code تک write access کی ضرورت نہیں، جب تک آپ preparePullRequestBranch کو true پر set نہ کریں تاکہ OpenTag branches push کرے۔ الگ githubApplyToken اسی لیے موجود ہے کہ code لکھنے والا token commenting token سے الگ رہے۔ تمام repositories کے لیے ایسا token استعمال نہ کریں جس میں contents write ہو، کیونکہ ان repositories میں comment کرنے والا کوئی بھی شخص پھر ایسے agent کو ہدایت دے سکتا ہے جو commit کر سکتا ہو۔

اگر کوئی run غلط سمت میں جا رہا ہو تو اسے کیسے روکوں؟

Slack میں اسی مقصد کے لیے /stop command موجود ہے۔ server پر opentag status سے معلوم ہوتا ہے کہ کیا چل رہا ہے، جبکہ opentag service stop daemon روک دیتا ہے۔ اس سے پورا pipeline ختم ہوتا ہے، صرف ایک run نہیں۔ دونوں commands کی ضرورت سے بچنے کے لیے approvalMode کو ask پر set کریں، تاکہ کسی بھی تبدیلی سے پہلے run انسانی منظوری کا انتظار کرے۔ preparePullRequestBranch کو false رہنے دیں، تاکہ خراب run branch بنانے کے بجائے comment پیدا کرے۔

میرے webhook سے 502 کیوں آتا ہے جبکہ thread خاموش رہتا ہے؟

502 nginx کی طرف سے آتا ہے، OpenTag کی طرف سے نہیں، اور اس کا مطلب ہے کہ proxy listener تک نہیں پہنچ سکا۔ /var/log/nginx/error.log سے connect() failed (111: Connection refused) while connecting to upstream دکھائی دے گا۔ یا تو listener بند ہے، یا وہ proxy_pass line میں درج port سے مختلف port پر چل رہا ہے۔ sudo ss -tlnp چلائیں اور تصدیق کریں کہ GitHub کے لیے 127.0.0.1:3050 اور Slack کے لیے 127.0.0.1:3040 پر کوئی process listening کر رہا ہے۔ اس کے بعد bindings اور executors دیکھنے کے لیے opentag doctor چلائیں۔