Open Connector کو اپنے سرور پر کیسے ہوسٹ کریں

AI ایجنٹ کے لیے Open Connector کیا کرتا ہے

Open Connector کو self-host کرنے کا مطلب ہے کہ آپ کے AI ایجنٹس اور ان کے استعمال کردہ ہر software as a service (SaaS) API کے درمیان ایک auth gateway کا قیام، تاکہ ایجنٹ کے پاس کبھی بھی provider token نہ رہے۔ یہ OOMOL Lab کا ایک اوپن سورس گیٹ وے ہے جو Apache 2.0 لائسنس کے تحت دستیاب ہے۔ یہ ایک container کے طور پر چلتا ہے، اپنی حالت (state) کو ایک واحد SQLite فائل میں محفوظ رکھتا ہے، اور provider actions کو HTTP اور MCP (model context protocol) کے ذریعے پیش کرتا ہے۔

مشکلات دوسری integration سے شروع ہوتی ہیں۔ ہر provider کا اپنا OAuth (open authorization) فلو، refresh token کی اپنی لائف ٹائم، اور scope کے اپنے نام ہوتے ہیں۔ کسی ایجنٹ میں پانچ providers کو دستی طور پر جوڑنے کا مطلب ہے پانچ redirect handlers، پانچ credential stores، اور پانچ ایسے refresh loops جو token ختم ہونے سے پہلے چلنے چاہئیں۔ تقریباً کوئی بھی یہ کوڈ نہیں لکھتا۔ لوگ ہر سروس کے لیے ایک طویل مدتی personal access token بناتے ہیں اور اسے ایجنٹ کی config، environment فائل، یا خود prompt میں پیسٹ کر دیتے ہیں۔ وہ ٹوکن پھر ایجنٹ کے چلائے گئے ہر ٹول کے لیے قابلِ مطالعہ ہوتا ہے، اور یہ transcript میں چلا جاتا ہے، جو کہ وہ ناکامی ہے جس کا ذکر AI ایجنٹس سے خفیہ معلومات کو دور رکھنا میں کیا گیا ہے۔

ایک auth gateway اسناد (credentials) کو دو حصوں میں تقسیم کر دیتا ہے۔ گیٹ وے provider کی اسناد کو اسٹور کرتا ہے اور OAuth فلو کو چلاتا ہے۔ ایجنٹ کو ایک runtime token ملتا ہے جو صرف گیٹ وے کے خلاف کارآمد ہوتا ہے۔ جب ایجنٹ کوئی action کال کرتا ہے، تو گیٹ وے اسٹور شدہ اسناد کو لوڈ کرتا ہے، انہیں سرور سائیڈ پر آؤٹ باؤنڈ درخواست میں شامل کرتا ہے، اور صرف response body واپس کرتا ہے۔ ایجنٹ کو کبھی بھی provider access token موصول نہیں ہوتا، لہذا ایجنٹ کے transcript کے لیک ہونے کی صورت میں آپ کو صرف ایک منسوخ ہونے کے قابل runtime token کا نقصان ہوتا ہے، نہ کہ آپ کے پورے GitHub اکاؤنٹ کا۔

اس کا کیٹلاگ 1,000 سے زیادہ providers اور 10,000 سے زیادہ پہلے سے تیار کردہ actions کا دعویٰ کرتا ہے، جو کہ پروجیکٹ کے اپنے اعداد و شمار ہیں اور ایسی چیز نہیں ہے جس کی آپ باہر سے تصدیق کر سکیں۔ جو چیز آپ تصدیق کر سکتے ہیں وہ اس کی ساخت ہے: ہر action کے لیے ایک HTTP endpoint، ہر provider کے لیے ایک اسٹور شدہ کنکشن، اور ہر ایجنٹ کے لیے ایک ٹوکن۔

ہوسٹڈ کنیکٹر سروس کے بجائے Open Connector کو خود ہوسٹ (self-host) کیوں کریں

ایک ہوسٹڈ کنیکٹر سروس وہی کام کرتی ہے، اور یہ ان تمام پرووائیڈرز کے ریفریش ٹوکنز (refresh tokens) کو محفوظ رکھتی ہے جنہیں آپ اس سے منسلک کرتے ہیں۔ Google یا GitHub کا ریفریش ٹوکن آپ کی ای میل اور ریپوزٹریز کے لیے ایک طویل مدتی کلید (key) ہے، اور یہ عام طور پر پاس ورڈ تبدیل ہونے کے بعد بھی کارآمد رہتا ہے۔ ان کی سیکیورٹی کی خلاف ورزی آپ کی خلاف ورزی بن جاتی ہے۔ خود ہوسٹ کرنے سے یہ ریکارڈز آپ کے کرائے پر لیے گئے اور زیر انتظام مشین پر موجود SQLite ڈیٹا بیس میں منتقل ہو جاتے ہیں، جو ایک ایسی کلید سے محفوظ ہوتے ہیں جو کبھی آپ کے سرور سے باہر نہیں جاتی۔

شروع کرنے سے پہلے اس کی قیمت کا اندازہ لگا لیں۔ یہ VPS آپ کے چلائے جانے والے سرورز میں سب سے قیمتی سرور بن جاتا ہے۔ یہ ایک ہی فائل میں درجنوں سروسز کے فعال اسناد (credentials) رکھتا ہے، اس لیے اسے پاس ورڈ مینیجر ہوسٹ جیسا درجہ دیں: ایک فائر وال جو صرف 443 پورٹ کو کھولتی ہو، کوئی مشترکہ لاگ ان نہ ہو، ایک ایسا بیک اپ جسے آپ نے کم از کم ایک بار بحال (restore) کر کے دیکھا ہو، اور سرور کے جواب دینا بند کرنے پر الرٹ کا نظام موجود ہو۔ اگر آپ اپنے پاس ورڈ والٹ (password vault) کو اس مشین پر نہیں رکھیں گے، تو کنیکٹر کو بھی اس پر نہ رکھیں۔

کسی بھی چیز کو انسٹال کرنے سے پہلے ورژن کو پن (Pin) کریں

Open Connector ایک نیا پروجیکٹ ہے۔ اس کی ریپوزٹری پہلی بار 29 June 2026 کو سامنے آئی، اور 1 August 2026 تک تازہ ترین tagged ریلیز v1.3.3 ہے، جسے 30 July 2026 کو شائع کیا گیا اور اس پر latest ٹیگ بھی موجود ہے۔ رجسٹری ایک tip ٹیگ بھی شائع کرتی ہے، جو main پر موجود تازہ ترین کمٹ (commit) سے بنایا گیا ہے۔

اتنے نئے پروجیکٹ پر متحرک ٹیگز اکثر تبدیل ہوتے رہتے ہیں۔ ایک docker compose pull جو دو ریلیزز کے درمیان چھلانگ لگاتا ہے، وہ اس اینڈ پوائنٹ کو تبدیل کر سکتا ہے جس پر آپ کا ایجنٹ انحصار کرتا ہے، اور آپ پوری شام اسے ایجنٹ کا مسئلہ سمجھ کر ڈی بگنگ میں گزار دیں گے۔ امیج کو ایک ریلیز ٹیگ پر پن (Pin) کریں، اور ریلیز نوٹس پڑھنے کے بعد، جب آپ خود فیصلہ کریں تب اسے اپ گریڈ کریں۔

اپنے VPS پر TLS کے پیچھے Open Connector کو تعینات کریں

کنٹینر شروع کرنے سے پہلے آپ کو درج ذیل چیزوں کی ضرورت ہے:

• Ubuntu 24.04 یا اس سے ملتے جلتے سسٹم پر Docker بمعہ Compose پلگ ان
• ایک hostname جس کا A record اس VPS کی طرف اشارہ کرتا ہو، مثال کے طور پر connect.example.com
• ایک reverse proxy جو اس hostname کے لیے پہلے سے TLS (transport layer security) کو ٹرمینیٹ کر رہا ہو
• دو بے ترتیب secrets، جو نیچے دیے گئے طریقے سے تیار کیے جائیں

متعدد Docker Compose ایپس کے لیے Traefik reverse proxy گائیڈ پراکسی کے حصے کا احاطہ کرتی ہے۔ ایک ہی ایپ کے لیے سرٹیفکیٹ کی مکمل تنصیب Docker اور HTTPS کے ساتھ VPS پر n8n گائیڈ میں موجود ہے۔

پہلے secrets تیار کریں۔ encryption key ذخیرہ شدہ اسناد (credentials) کو محفوظ بناتی ہے۔ admin token ویب کنسول اور پورے /api سرفیس کو تحفظ فراہم کرتا ہے۔ ان میں سے کسی کی بھی کوئی ڈیفالٹ ویلیو نہیں ہے، اور runtime ان کے بغیر بھی خوشی سے شروع ہو جاتا ہے۔

mkdir -p ~/open-connector && cd ~/open-connector
umask 077
printf 'OOMOL_CONNECT_ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" > .env
printf 'OOMOL_CONNECT_ADMIN_TOKEN=%s\n' "$(openssl rand -base64 32)" >> .env
chmod 600 .env

دونوں ویلیوز کو ابھی اپنے پاس ورڈ مینیجر میں کاپی کر لیں، پہلی بار شروع کرنے سے پہلے۔ encryption key کا کوئی ریکوری راستہ نہیں ہے، اور اس کی وجہ نیچے دی گئی ناکامیوں کی فہرست میں موجود ہے۔

اب compose.yaml بنائیں۔ یہ upstream مثال سے دو جگہوں پر مختلف ہے، اور دونوں اہم ہیں۔

services:
  connector:
    image: ghcr.io/oomol-lab/open-connector:v1.3.3
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - connector-data:/app/data
    environment:
      OOMOL_CONNECT_DATA_DIR: /app/data
      OOMOL_CONNECT_ORIGIN: "https://connect.example.com"
      OOMOL_CONNECT_ENCRYPTION_KEY: "${OOMOL_CONNECT_ENCRYPTION_KEY:?set this in .env}"
      OOMOL_CONNECT_ADMIN_TOKEN: "${OOMOL_CONNECT_ADMIN_TOKEN:?set this in .env}"

volumes:
  connector-data:

پہلی تبدیلی latest کے بجائے pinned tag کا استعمال ہے۔ دوسری تبدیلی پورٹ ہے۔ upstream فائل 3000:3000 کو پبلش کرتی ہے، جو ہوسٹ کے تمام انٹرفیسز پر bind ہو جاتی ہے۔ Docker اپنی پبلش شدہ پورٹس کو NAT (network address translation) ٹیبل میں اس وقت لکھ دیتا ہے جب ufw فلٹر چین پیکٹ کو دیکھ بھی نہیں پاتی، اس لیے ufw deny 3000 اس پورٹ کو بند نہیں کرتا، یہ وہ جال ہے جس کی تفصیل کیوں Docker پورٹس ufw کو بائی پاس کرتی ہیں میں دی گئی ہے۔ 127.0.0.1:3000:3000 لکھنے سے یہ صرف loopback انٹرفیس پر پبلش ہوتی ہے، اور آپ کی reverse proxy اسی ہوسٹ سے کنیکٹ ہوتی ہے۔

:? ہر متغیر (variable) کو لازمی قرار دیتا ہے، لہذا جب .env غائب ہو تو اسٹیک شروع ہونے سے انکار کر دیتا ہے، بجائے اس کے کہ غیر محفوظ اسناد کے ساتھ شروع ہو۔ اقدار کو compose فائل کے بجائے .env میں رکھنا Docker Compose env فائلیں اور secrets کا طریقہ کار ہے۔

docker compose up -d
docker compose logs -n 30 connector
curl -s http://127.0.0.1:3000/health
sudo ss -tlnp | grep 3000

ایک بار جب runtime چل جائے تو /health، { "ok": true } کا جواب دیتا ہے۔ ss کو لازمی طور پر 127.0.0.1:3000 پرنٹ کرنا چاہیے۔ 0.0.0.0:3000 پڑھنے والی لائن کا مطلب ہے کہ پورٹ میپنگ ابھی بھی upstream والی ہے، اور گیٹ وے براہ راست پورے انٹرنیٹ کو جواب دے رہا ہے۔ ہیلتھ چیک پر Connection refused کا مطلب ہے کہ کنٹینر ابھی تک لسن (listen) نہیں کر رہا، لہذا پراکسی کو چھیڑنے سے پہلے logs پڑھیں۔

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.connector.rule=Host(`connect.example.com`)"
      - "traefik.http.routers.connector.entrypoints=websecure"
      - "traefik.http.routers.connector.tls.certresolver=le"
      - "traefik.http.services.connector.loadbalancer.server.port=3000"

OAuth کے لیے حقیقی hostname کا ہونا کیوں ضروری ہے

OOMOL_CONNECT_ORIGIN وہ سیٹنگ ہے جسے لوگ نظر انداز کر دیتے ہیں، اور اسے چھوڑ دینے سے OAuth اس طرح ٹوٹ جاتا ہے جیسے کوئی پرووائیڈر کا بگ ہو۔ رن ٹائم اس origin سے اپنا redirect URI بناتا ہے، جو <origin>/oauth/callback کی شکل میں ہوتا ہے۔ اگر اسے سیٹ نہ کیا جائے تو origin بائی ڈیفالٹ http://localhost:3000 ہو جاتا ہے، لہذا رن ٹائم پرووائیڈر کو http://localhost:3000/oauth/callback کا redirect URI بھیجتا ہے جبکہ آپ کی OAuth ایپ میں https://connect.example.com/oauth/callback رجسٹرڈ ہوتا ہے۔ یہ دونوں سٹرنگز مختلف ہیں، اس لیے GitHub یہ جواب دیتا ہے:

The redirect_uri MUST match the registered callback URL for this application.

ایک OAuth پرووائیڈر براؤزر کو واپس اس URI پر ری ڈائریکٹ کرتا ہے، جس کا مطلب ہے کہ یہ ایسا ایڈریس ہونا چاہیے جسے بیرونی دنیا تک رسائی حاصل ہو، اور پرووائیڈرز localhost کے علاوہ کسی بھی چیز کے لیے سادہ http:// کو مسترد کر دیتے ہیں۔ یہی وہ واحد وجہ ہے جس کی بنا پر اس ڈیپلائمنٹ کو ایک hostname اور سرٹیفکیٹ کی ضرورت ہوتی ہے۔ پہلی بار اسٹارٹ کرنے سے پہلے origin سیٹ کریں، کیونکہ یہ ویلیو اسٹارٹ اپ پر پڑھی جاتی ہے: .env یا compose.yaml میں ترمیم کرنے کے بعد، اسے لاگو کرنے کے لیے دوبارہ docker compose up -d چلائیں۔

اپنے پہلے پرووائیڈر کو OAuth کے ذریعے منسلک کریں

سب سے پہلے پرووائیڈر کے پاس OAuth ایپ بنائیں۔ GitHub پر اس کا راستہ Settings، پھر Developer settings، پھر OAuth Apps، اور پھر New OAuth App ہے۔ Authorization callback URL کو https://connect.example.com/oauth/callback پر سیٹ کریں۔ Client ID اور client secret کو محفوظ رکھیں۔

ہر /api کال میں admin token شامل ہوتا ہے، لہذا اسے shell سیشن کے لیے ایک بار export کر لیں۔

export ADMIN_TOKEN='paste-the-admin-token'
curl -s https://connect.example.com/api/oauth/configs \
  -H "authorization: Bearer $ADMIN_TOKEN"

یہ فہرست ہر پرووائیڈر کے لیے درکار redirect URI دکھاتی ہے، جو اس بات کی تصدیق کا تیز ترین طریقہ ہے کہ آپ کی تبدیلیاں لاگو ہو چکی ہیں۔ اگر یہ اب بھی localhost دکھا رہا ہے، تو کنٹینر پرانی ویلیو کے ساتھ چل رہا ہے اور OAuth کا عمل آخری مرحلے پر ناکام ہو جائے گا۔

Client credentials کو محفوظ کریں، پھر authorization شروع کریں۔

curl -s -X PUT https://connect.example.com/api/oauth/configs/github \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

curl -s -X POST https://connect.example.com/api/oauth/authorizations \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

دوسری کال ایک authorizationUrl واپس کرتی ہے۔ اسے براؤزر میں کھولیں، scopes کو منظور کریں، اور پرووائیڈر براؤزر کو واپس /oauth/callback پر بھیج دے گا، جہاں runtime کوڈ کا تبادلہ کرتا ہے اور credential کو محفوظ کر لیتا ہے۔ آپ کے origin پر موجود web console اسی admin token کے پیچھے، ایک فارم کے ذریعے انہی مراحل کو مکمل کرتا ہے۔ جو پرووائیڈرز سادہ API key استعمال کرتے ہیں وہ ان تمام مراحل کو چھوڑ دیتے ہیں: {"authType":"api_key","values":{"apiKey":"..."}} کے ساتھ PUT /api/connections/<service> کلید کو براہ راست محفوظ کر لیتا ہے۔

ہر ایجنٹ کو ایک رن ٹائم ٹوکن دیں، نہ کہ اسناد

ایجنٹ ایک رن ٹائم ٹوکن کے ذریعے گیٹ وے سے تصدیق کرتا ہے، جسے ایڈمن API جاری کرتی ہے۔

curl -s -X POST https://connect.example.com/api/runtime-tokens \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"research-agent"}'

جواب میں ایک ٹوکن ہوتا ہے جو oct_ سے شروع ہوتا ہے۔ ہر ایجنٹ کے لیے ایک ٹوکن جاری کریں اور اسے اسی ایجنٹ کے نام سے منسوب کریں، کیونکہ جس ٹوکن کی شناخت نہ ہو اسے منسوخ کرنے کا مطلب سب کو منسوخ کرنا ہے۔ اس کے بعد ایجنٹ عام HTTP کے ذریعے ایکشنز کال کرتا ہے۔

curl -s -X POST https://connect.example.com/v1/actions/github.get_current_user \
  -H "authorization: Bearer oct_..." \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

ایک درست جواب ایک لفافہ (envelope) ہوتا ہے جس کا success فیلڈ true ہوتا ہے، اور پرووائیڈر کا پے لوڈ data کے تحت ہوتا ہے۔ GitHub ٹوکن اس جواب میں کہیں نہیں ہوتا۔ MCP کلائنٹ کے لیے، اسے اسی بیئرر ہیڈر کے ساتھ https://connect.example.com/mcp پر پوائنٹ کریں، اور گیٹ وے ہر API کے لیے ایک ٹول کے بجائے search_actions اور execute_action جیسے ڈسکوری ٹولز پیش کرتا ہے، جس سے ایجنٹ کی ٹول لسٹ مختصر رہتی ہے۔ VPS پر MCP سرورز چلانا اس کنکشن کے کلائنٹ والے حصے کا احاطہ کرتا ہے۔

اسے مکمل قرار دینے سے پہلے ایک اور چیک چلائیں۔ authorization ہیڈر کو ہٹا کر ایکشن کال کو دہرائیں۔ پروجیکٹ کا اپنا کوئیک سٹارٹ بغیر کسی بیئرر کے /v1 کال کرتا ہے، لہذا اگر رن ٹائم آتھنٹیکیشن کنفیگر نہ ہو تو انسٹالیشن پورٹ تک رسائی رکھنے والے کسی بھی شخص کے لیے ایکشنز انجام دے سکتی ہے۔ اگر آپ کی غیر تصدیق شدہ کال کامیاب ہو جائے، تو آپ کے پاس دو راستے ہیں: رن ٹائم ٹوکنز کنفیگر کریں اور تصدیق کریں کہ اب گمنام کال ناکام ہو رہی ہے، یا ریورس پراکسی پر /api، /v1 اور /mcp کو صرف ان ایڈریسز تک محدود کریں جہاں سے آپ کے ایجنٹس آتے ہیں۔ صرف /oauth/callback کو دنیا کے لیے کھلا رہنا چاہیے، کیونکہ یہ وہ واحد راستہ ہے جس کی پرووائیڈر کے براؤزر ری ڈائریکٹ کو ضرورت ہوتی ہے۔

ایجنٹ کی ضرورت کے مطابق ایکشن لسٹ کو محدود کریں

ایک گیٹ وے جس کے پیچھے ہزاروں پرووائیڈرز ہوں، لینگویج ماڈل کو دینے کے لیے ایک وسیع سطح ہے۔ یہ سطح اس وقت اور بھی وسیع ہو جاتی ہے جب ماڈل ایسا متن پڑھنا شروع کرتا ہے جو اس نے خود نہیں لکھا، کیونکہ آپ کے اپنے SearXNG انسٹینس کی طرف سے ایجنٹ کی ویب سرچز کے جواب میں واپس آنے والا صفحہ ایسی ہدایات کا حامل ہو سکتا ہے جو ایجنٹ کے پاس موجود کسی بھی ایکشن کو ہدف بنا سکتی ہیں۔ وہی احتیاط جو ایک کوڈنگ ایجنٹ کو سب سے چھوٹی کارآمد تبدیلی کرنے پر مجبور کرتی ہے، اس کی اجازتوں پر بھی لاگو ہونی چاہیے: صرف ان چند ایکشنز کی اجازت دیں جن کی کام کے لیے واقعی ضرورت ہے، اور اس سے زیادہ کچھ نہیں۔ دو کنٹرولز اسے محدود کرتے ہیں۔

OOMOL_CONNECT_ALLOWED_ACTIONS کوما سے الگ کردہ ایک allowlist لیتا ہے اور service.* اور * کو سمجھتا ہے۔ OOMOL_CONNECT_BLOCKED_ACTIONS ڈین لسٹ (denylist) ہے، اور ڈین لسٹ کو فوقیت حاصل ہوتی ہے۔ allowlist کو github.get_current_user,github.list_issues پر سیٹ کرنے کا مطلب ہے کہ ایجنٹ چاہے کچھ بھی مانگے، ہر دوسرے ایکشن کو مسترد کر دیا جائے گا، جو کہ ایک غلطی اور ایک سیکیورٹی واقعے کے درمیان فرق ہے۔ رن ٹائم ٹوکنز اپنے عالمی اصولوں کے اوپر اپنے ایکشن رولز رکھتے ہیں، اور ان کی allowedProxies لسٹ خالی شروع ہوتی ہے، لہذا جب تک آپ POST /v1/proxy/:service کو اجازت نہ دیں، اسے مسترد کر دیا جاتا ہے۔ وہ پراکسی اینڈ پوائنٹ آپ کے کریڈینشل کے ساتھ ایک خام درخواست پرووائیڈر کو بھیجتا ہے، لہذا اسے خالی چھوڑ دیں جب تک کہ کسی مخصوص ایجنٹ کو اس کی ضرورت نہ ہو۔

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK بائی ڈیفالٹ false پر ہوتا ہے، جو سیلف ہوسٹڈ پرووائیڈر کنکشن کو کسی نجی پتے کی طرف اشارہ کرنے سے روکتا ہے، جیسے کہ 169.254.169.254 پر کلاؤڈ میٹا ڈیٹا سروس، یا اسی نیٹ ورک پر آپ کا ڈیٹا بیس۔ اسے آف ہی رہنے دیں۔ اسے صرف اس پرووائیڈر کے لیے آن کریں جسے آپ خود ہوسٹ کرتے ہیں۔

ہر ٹوکن رکھنے والے باکس کا بیک اپ لیں

دو چیزیں اہم ہیں، اور ایک دوسرے کے بغیر دونوں بے کار ہیں۔ /app/data/connect.sqlite پر موجود ڈیٹا بیس جو connector-data والیوم کے اندر ہے، سیل شدہ اسناد (credentials) کو محفوظ رکھتا ہے۔ .env میں موجود انکرپشن کی (encryption key) انہیں ان سیل کرتی ہے۔ کی (key) کے بغیر والیوم کا بیک اپ کچھ بحال نہیں کر سکتا، اور والیوم کے بغیر کی (key) کچھ بحال نہیں کر سکتی، لہذا کی (key) کو اپنے پاس ورڈ مینیجر میں رکھیں اور والیوم کو اپنی معمول کی بیک اپ روٹیشن میں شامل کریں۔

SQLite فائل کاپی کرتے وقت کنٹینر کو روک دیں، کیونکہ لکھائی کے دوران لی گئی کاپی ایک کرپٹ ڈیٹا بیس کے طور پر بحال ہو سکتی ہے۔

docker volume ls | grep connector-data
docker compose stop connector
docker run --rm -v open-connector_connector-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/connector-data.tgz -C /data .
docker compose start connector

والیوم کا نام آپ کی پروجیکٹ ڈائریکٹری جمع _connector-data ہے، اسی لیے پہلا کمانڈ وہاں موجود ہے: اصل نام کو تیسرے کمانڈ میں پیسٹ کریں۔ آرکائیو کو VPS سے restic بیک اپ کے ذریعے VPS سے باہر بھیجیں، جو اسے باہر جانے سے پہلے انکرپٹ کر دیتا ہے، کیونکہ وہ آرکائیو اسناد کا ذخیرہ ہے۔

رن ٹائم حالیہ ایکشن رنز کو آڈٹ ریکارڈز کے طور پر محفوظ رکھتا ہے، جو بائی ڈیفالٹ 5,000 ہوتے ہیں، تاکہ کنسول آپ کو بتا سکے کہ کس ایجنٹ نے کیا اور کب چلایا۔ جب کوئی ایجنٹ عجیب رویہ دکھائے تو وہ لاگ سب سے پہلے پڑھنا چاہیے۔ Uptime Kuma اسٹیٹس پیج کو بھی https://connect.example.com/health پر پوائنٹ کریں۔ جب گیٹ وے جواب دینا بند کر دیتا ہے، تو ایجنٹس الجھا دینے والے طریقوں سے فیل ہوتے ہیں، اور یہ جاننا کہ گیٹ وے ڈاؤن ہے، ایجنٹ آؤٹ پٹ پڑھنے کا ایک گھنٹہ بچا سکتا ہے۔

کیا چیز خراب ہوتی ہے، اور آپ کو کیا پیغام نظر آئے گا

redirect_uri_mismatch فراہم کنندہ (provider) پر۔ اصل (origin) اور رجسٹرڈ کال بیک URL آپس میں نہیں ملتے۔ /api/oauth/configs سے حاصل کردہ درست سٹرنگ کا موازنہ فراہم کنندہ کی ایپ سیٹنگز سے کریں، جس میں https کا http کے ساتھ موازنہ اور کسی بھی ٹریلنگ سلیش (trailing slash) کی جانچ شامل ہے۔

ہر /api کال 401 واپس کرتی ہے۔ ایڈمن ٹوکن ہیڈر غائب ہے یا اس کے ہجے غلط ہیں۔ ہیڈر Authorization: Bearer <token> ہے، اور ویب کنسول اسی ٹوکن کا مطالبہ کرتا ہے۔

کنٹینر چلتا ہے، اور اسناد (credentials) سادہ متن (plain text) میں موجود ہیں۔ یہ تب ہوتا ہے جب OOMOL_CONNECT_ENCRYPTION_KEY کنٹینر تک نہیں پہنچ پاتا، کیونکہ رن ٹائم اسناد کے ریکارڈز کو انکرپٹ کیے بغیر اسٹور کر لیتا ہے بجائے اس کے کہ شروع ہونے سے انکار کرے۔ اپنے انسٹال پر اس کی تصدیق کریں: ایک ایسے API کی کے ساتھ فراہم کنندہ کو کنیکٹ کریں جسے آپ پہچان سکیں، پھر ڈیٹا بیس میں اسے تلاش کریں۔

docker compose cp connector:/app/data/connect.sqlite /tmp/connect.sqlite
grep -c 'github_pat_' /tmp/connect.sqlite
shred -u /tmp/connect.sqlite

0 سے زیادہ کی تعداد کا مطلب ہے کہ کی (key) فعال نہیں ہے، لہذا چیک کریں کہ .env اسی ڈائریکٹری میں موجود ہے جہاں compose.yaml ہے اور یہ کہ docker compose config وہ ویلیو دکھا رہا ہے۔ کی سیٹ ہونے کے بعد، وہی تلاش 0 واپس کرے گی، کیونکہ ریکارڈ AES-256-GCM (ایڈوانسڈ انکرپشن اسٹینڈرڈ، 256-bit کی، گالوئس/کاؤنٹر موڈ) کے ساتھ سیل (seal) ہو چکا ہوتا ہے۔

ریسٹور کے بعد کچھ بھی ڈکرپٹ نہیں ہوتا۔ انکرپشن کی تبدیل ہو گئی ہے یا ضائع ہو گئی ہے۔ ڈیزائن کے مطابق، اسے کبھی بھی ڈیٹا کے ساتھ نہیں لکھا جاتا، لہذا اس کا کوئی ریکوری پاتھ نہیں ہے اور کوئی سپورٹ ٹکٹ مدد نہیں کر سکتا۔ ہر فراہم کنندہ کو دوبارہ کنیکٹ کریں۔ روٹیشن (rotation) ایک الگ کی ویری ایبل اور رن ٹائم میں ڈیٹا کمانڈ کے ذریعے سپورٹ کی جاتی ہے، لہذا کچھ بھی روٹیٹ کرنے سے پہلے موجودہ ریلیز نوٹس پڑھ لیں۔

ایجنٹ کو ایک ایسے ایکشن کا نام لینے پر ایرر ملتا ہے جو اسے کیٹلاگ میں نظر آتا ہے۔ ڈسکوری اور ایگزیکیوشن الگ الگ ہیں۔ ایک ایکشن search_actions میں ظاہر ہو سکتا ہے اور پھر بھی OOMOL_CONNECT_ALLOWED_ACTIONS، ڈین لسٹ (denylist)، یا اس رن ٹائم ٹوکن کے اپنے قواعد کی وجہ سے مسترد کیا جا سکتا ہے۔

اپ گریڈز۔ والیوم کا بیک اپ لیں، امیج ٹیگ کو نئی ریلیز میں ایڈٹ کریں، پھر docker compose pull && docker compose up -d کریں۔ مائیگریشن لائن کے لیے docker compose logs -n 50 connector کو مانیٹر کریں، اور دوبارہ بھروسہ کرنے سے پہلے ہیلتھ چیک اور ایک حقیقی ایکشن دوبارہ چلائیں۔ رول بیک (rolling back) کا مطلب ہے پرانا ٹیگ واپس لگانا، جو صرف تب کام کرتا ہے جب آپ نے اسے پن (pin) کیا ہو۔

FAQ

کیا Open Connector کو self-host کرنے کے لیے مجھے public domain کی ضرورت ہے؟

جن providers کے لیے API key درکار ہوتی ہے، ان کے لیے نہیں: 127.0.0.1 پر ایک gateway کافی ہے۔ OAuth کے لیے، عملی طور پر ہاں۔ Provider براؤزر کو آپ کے callback URL پر بھیجتا ہے، لہذا اس URL کا public internet سے resolve ہونا ضروری ہے، اور providers localhost کے علاوہ سادہ http:// کو قبول نہیں کرتے۔ پہلی بار start کرنے سے پہلے OOMOL_CONNECT_ORIGIN کو اپنے https:// hostname پر سیٹ کریں، اور provider کی OAuth app میں <origin>/oauth/callback کو رجسٹر کریں۔

اگر میں Open Connector کی encryption key کھو دوں تو کیا ہوگا؟

محفوظ کردہ credentials کو decrypt نہیں کیا جا سکتا، اور اس کی کوئی recovery نہیں ہے۔ یہ key جان بوجھ کر ڈیٹا کے ساتھ ذخیرہ نہیں کی جاتی، تاکہ ڈیٹا بیس تک رسائی رکھنے والا کوئی بھی شخص اسے پڑھ نہ سکے، بشمول آپ کے۔ آپ کا واحد آپشن یہ ہے کہ نئی key سیٹ کریں اور ہر provider کو دوبارہ connect کریں۔ Key کو password manager میں اور ڈیٹا بیس کو اپنی backup rotation میں رکھیں، کیونکہ restore کے لیے دونوں کی ضرورت ہوتی ہے۔

کیا میرا AI agent provider access token دیکھ سکتا ہے؟

جب یہ gateway کے ذریعے کال کرتا ہے تو نہیں۔ Agent ایک runtime token کے ساتھ authenticate ہوتا ہے جو oct_ سے شروع ہوتا ہے، اور gateway سرور پر outbound request میں provider credential شامل کر دیتا ہے، اور صرف response واپس کرتا ہے۔ دو چیزیں اس خصوصیت کو ختم کرتی ہیں: /v1/proxy/:service endpoint، جو آپ کے credential کے ساتھ raw requests کو آگے بھیجتا ہے اور جس کے grants خالی شروع ہوتے ہیں، اور agent میں خود API key پیسٹ کرنا، جو gateway کو مکمل طور پر نظر انداز کر دیتا ہے۔

کیا gateway تک public internet سے رسائی ہونی چاہیے؟

صرف /oauth/callback تک رسائی ہونی چاہیے۔ Container port کو 127.0.0.1 پر publish کریں تاکہ Docker کے NAT rules اسے آپ کے firewall سے باہر ظاہر نہ کر سکیں، اور اس کے آگے reverse proxy لگا دیں۔ پھر بغیر authorization header کے ایک action call ٹیسٹ کریں۔ اگر یہ کامیاب ہو جائے، تو proxy پر /api، /v1 اور /mcp کو صرف ان addresses تک محدود کریں جو آپ کے agents استعمال کرتے ہیں، یہاں تک کہ صرف authenticated calls ہی کام کریں۔

کیا Open Connector production استعمال کے لیے تیار ہے؟

یہ Apache 2.0 لائسنس یافتہ ہے اور تیزی سے ترقی کر رہا ہے: repository 29 June 2026 کو ظاہر ہوئی اور v1.3.3 کو 30 July 2026 کو release کیا گیا، لہذا اس گائیڈ میں ہر version number کو 1 August 2026 کا snapshot سمجھیں۔ اسے ہمیشہ release tag کے ساتھ چلائیں، کبھی بھی latest یا tip پر نہ چلائیں، ہر upgrade سے پہلے release notes پڑھیں، اور volume کا ایسا backup رکھیں جسے آپ ایک بار restore کر چکے ہوں۔ اس کا ڈیزائن آپ کی اپنی مشین کے لیے درست ہے، اور خطرہ version میں تبدیلی کا ہے، نہ کہ architecture کا۔