Open Connector সেলফ-হোস্ট করার নিয়ম

AI এজেন্টের জন্য Open Connector যা করে

Open Connector সেলফ-হোস্ট করলে এটি আপনার AI এজেন্ট এবং তাদের কল করা প্রতিটি SaaS (Software as a Service) API-এর মধ্যে একটি অথ গেটওয়ে হিসেবে কাজ করে, ফলে এজেন্টের কাছে কখনোই কোনো প্রোভাইডার টোকেন থাকে না। এটি OOMOL Lab-এর একটি ওপেন সোর্স গেটওয়ে, যা Apache 2.0 লাইসেন্সের অধীনে প্রকাশিত। এটি একটি কন্টেইনার হিসেবে চলে, একটি SQLite ফাইলে এর স্টেট সংরক্ষণ করে এবং HTTP ও MCP (Model Context Protocol)-এর মাধ্যমে প্রোভাইডার অ্যাকশনগুলো এক্সপোজ করে।

দ্বিতীয় ইন্টিগ্রেশন থেকেই সমস্যার শুরু হয়। প্রতিটি প্রোভাইডারের নিজস্ব OAuth (Open Authorization) ফ্লো, নিজস্ব রিফ্রেশ টোকেন লাইফটাইম এবং নিজস্ব স্কোপ নেম থাকে। হাতে কলমে পাঁচটি প্রোভাইডারকে একটি এজেন্টের সাথে যুক্ত করার অর্থ হলো পাঁচটি রিডাইরেক্ট হ্যান্ডলার, পাঁচটি ক্রেডেনশিয়াল স্টোর এবং পাঁচটি রিফ্রেশ লুপ তৈরি করা, যা টোকেন এক্সপায়ার হওয়ার আগেই চলতে হবে। প্রায় কেউই এই কোড লেখে না। তারা প্রতিটি সার্ভিসের জন্য একটি দীর্ঘমেয়াদী পার্সোনাল অ্যাক্সেস টোকেন তৈরি করে এবং সেটি এজেন্টের কনফিগারেশন, এনভায়রনমেন্ট ফাইল বা সরাসরি প্রম্পটে পেস্ট করে দেয়। এরপর এজেন্ট যে টুলই রান করুক না কেন, সেই টোকেনটি তার কাছে দৃশ্যমান থাকে এবং এটি ট্রান্সক্রিপ্টে চলে আসে, যা AI এজেন্ট থেকে গোপন তথ্য দূরে রাখা নিবন্ধে বর্ণিত ব্যর্থতার কারণ।

একটি অথ গেটওয়ে ক্রেডেনশিয়ালকে দুই ভাগে বিভক্ত করে। গেটওয়েটি প্রোভাইডারের ক্রেডেনশিয়াল সংরক্ষণ করে এবং OAuth ফ্লো পরিচালনা করে। এজেন্ট একটি রানটাইম টোকেন পায় যা শুধুমাত্র গেটওয়ের ক্ষেত্রেই বৈধ। যখন এজেন্ট কোনো অ্যাকশন কল করে, গেটওয়ে তখন সংরক্ষিত ক্রেডেনশিয়াল লোড করে, সেটিকে সার্ভার সাইড থেকে আউটবাউন্ড রিকোয়েস্টে ইনজেক্ট করে এবং শুধুমাত্র রেসপন্স বডিটি ফেরত পাঠায়। এজেন্ট কখনোই প্রোভাইডারের অ্যাক্সেস টোকেন পায় না, তাই এজেন্টের ট্রান্সক্রিপ্ট ফাঁস হলেও আপনার GitHub অ্যাকাউন্টের পরিবর্তে শুধুমাত্র একটি রিভোকেবল রানটাইম টোকেন খোয়া যায়।

ক্যাটালগে 1,000-এর বেশি প্রোভাইডার এবং 10,000-এর বেশি প্রি-বিল্ট অ্যাকশনের বিজ্ঞাপন দেওয়া হয়েছে, যা প্রজেক্টটির নিজস্ব পরিসংখ্যান এবং বাইরে থেকে যাচাইযোগ্য নয়। আপনি যা যাচাই করতে পারেন তা হলো এর গঠন: প্রতিটি অ্যাকশনের জন্য একটি HTTP এন্ডপয়েন্ট, প্রতিটি প্রোভাইডারের জন্য একটি সংরক্ষিত কানেকশন এবং প্রতিটি এজেন্টের জন্য একটি টোকেন।

কেন একটি হোস্ট করা কানেক্টর পরিষেবা ব্যবহারের পরিবর্তে Open Connector সেলফ-হোস্ট করবেন

একটি হোস্ট করা কানেক্টর পরিষেবা একই কাজ করে এবং এটি আপনার সংযুক্ত প্রতিটি প্রোভাইডারের রিফ্রেশ টোকেনগুলো সংরক্ষণ করে। Google বা GitHub-এর একটি রিফ্রেশ টোকেন হলো আপনার মেইল এবং রিপোজিটরির জন্য একটি দীর্ঘস্থায়ী কি (key), যা সাধারণত পাসওয়ার্ড পরিবর্তনের পরেও কার্যকর থাকে। তাদের সার্ভার হ্যাক হওয়া মানেই আপনার তথ্য বেহাত হওয়া। সেলফ-হোস্টিংয়ের মাধ্যমে আপনি এই রেকর্ডগুলোকে আপনার ভাড়া করা এবং নিয়ন্ত্রিত মেশিনের SQLite ডেটাবেসে সরিয়ে নিতে পারেন, যা এমন একটি কি (key) দিয়ে সুরক্ষিত থাকে যা কখনোই আপনার সার্ভারের বাইরে যায় না।

কাজ শুরু করার আগে এর খরচের বিষয়টি বিবেচনা করুন। এই VPS-টি আপনার চালানো সবচেয়ে গুরুত্বপূর্ণ সার্ভারে পরিণত হবে। এটি একটি ফাইলে ডজনখানেক পরিষেবার কার্যকর ক্রেডেনশিয়াল সংরক্ষণ করে, তাই এটি একটি পাসওয়ার্ড ম্যানেজার হোস্টের মতো গুরুত্ব পাওয়ার যোগ্য: এমন একটি ফায়ারওয়াল যা শুধুমাত্র 443 পোর্ট খোলা রাখে, কোনো শেয়ারড লগইন থাকবে না, এমন একটি ব্যাকআপ যা আপনি অন্তত একবার পুনরুদ্ধার করে দেখেছেন এবং সার্ভার সাড়া দেওয়া বন্ধ করলে সতর্কবার্তা পাওয়ার ব্যবস্থা। আপনি যদি আপনার পাসওয়ার্ড ভল্ট এই বক্সে না রাখেন, তবে কানেক্টরটিও এখানে রাখবেন না।

কোনো কিছু ইনস্টল করার আগে একটি ভার্সন পিন করুন

Open Connector একটি নতুন সফটওয়্যার। এর রিপোজিটরি প্রথম প্রকাশিত হয় 29 June 2026 তারিখে এবং 1 August 2026 পর্যন্ত সর্বশেষ ট্যাগ করা রিলিজ হলো v1.3.3, যা 30 July 2026 তারিখে প্রকাশিত হয়েছে এবং এতে latest ট্যাগটিও রয়েছে। রেজিস্ট্রি একটি tip ট্যাগও প্রকাশ করে, যা main-এর সর্বশেষ কমিট থেকে তৈরি।

এত নতুন একটি প্রজেক্টে পরিবর্তনশীল ট্যাগগুলো ঘন ঘন পরিবর্তিত হয়। একটি docker compose pull যা দুটি রিলিজ অতিক্রম করে, তা আপনার এজেন্টের ওপর নির্ভরশীল কোনো এন্ডপয়েন্ট পরিবর্তন করে দিতে পারে এবং তখন আপনাকে পুরো সন্ধ্যা ব্যয় করতে হবে এটিকে এজেন্টের সমস্যা হিসেবে ডিবাগ করার জন্য। ইমেজটিকে একটি রিলিজ ট্যাগের সাথে পিন করুন এবং রিলিজ নোট পড়ার পর আপনার সুবিধামতো সময়ে আপগ্রেড করুন।

আপনার নিজস্ব VPS-এ TLS-এর পেছনে Open Connector স্থাপন করুন

কন্টেইনারটি শুরু করার আগে আপনার যা প্রয়োজন:

• Ubuntu 24.04 বা সমমানের সিস্টেমে Docker এবং Compose প্লাগইন
• একটি হোস্টনাম যার A রেকর্ড এই VPS-কে নির্দেশ করে, উদাহরণস্বরূপ connect.example.com
• একটি রিভার্স প্রক্সি যা ইতিমধ্যে সেই হোস্টনামের জন্য TLS (transport layer security) টার্মিনেট করে
• নিচে তৈরি করা দুটি র‍্যান্ডম সিক্রেট

একাধিক Docker Compose অ্যাপের জন্য Traefik রিভার্স প্রক্সি নিবন্ধে প্রক্সি সংক্রান্ত বিষয়গুলো আলোচনা করা হয়েছে। একটি একক অ্যাপের জন্য শুরু থেকে শেষ পর্যন্ত একই সার্টিফিকেট কনফিগারেশনের বিস্তারিত Docker এবং HTTPS সহ VPS-এ n8n গাইডে রয়েছে।

প্রথমে সিক্রেটগুলো তৈরি করুন। এনক্রিপশন কি (encryption key) সংরক্ষিত ক্রেডেনশিয়ালগুলোকে সুরক্ষিত রাখে। অ্যাডমিন টোকেন (admin token) ওয়েব কনসোল এবং পুরো /api ইন্টারফেসকে সুরক্ষিত রাখে। এগুলোর কোনো ডিফল্ট মান নেই এবং এগুলো ছাড়া রানটাইম শুরু হয়ে যায়, যা অনিরাপদ।

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

প্রথমবার শুরু করার আগেই উভয় মান আপনার পাসওয়ার্ড ম্যানেজারে কপি করে রাখুন। এনক্রিপশন কি-এর কোনো রিকভারি পাথ নেই, এবং এর কারণ নিচে ব্যর্থতার তালিকায় দেওয়া হয়েছে।

এখন compose.yaml তৈরি করুন। এটি আপস্ট্রিম উদাহরণের চেয়ে দুটি জায়গায় আলাদা, এবং উভয়ই গুরুত্বপূর্ণ।

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-এর পরিবর্তে একটি নির্দিষ্ট ট্যাগ ব্যবহার করা। দ্বিতীয়টি হলো পোর্ট। আপস্ট্রিম ফাইলটি 3000:3000 পাবলিশ করে, যা হোস্টের প্রতিটি ইন্টারফেসে বাইন্ড হয়। Docker তার পাবলিশ করা পোর্টগুলোকে NAT (network address translation) টেবিলে লিখে রাখে, যা ufw ফিল্টার চেইন দেখার আগেই কার্যকর হয়। তাই ufw deny 3000 সেই পোর্টটি বন্ধ করতে পারে না, যা কেন Docker পোর্টগুলো ufw বাইপাস করে নিবন্ধে বর্ণিত একটি ফাঁদ। 127.0.0.1:3000:3000 লিখলে তা শুধুমাত্র লুপব্যাক ইন্টারফেসে পাবলিশ হয় এবং আপনার রিভার্স প্রক্সি একই হোস্ট থেকে সংযোগ স্থাপন করে।

:? প্রতিটি ভেরিয়েবলকে প্রয়োজনীয় হিসেবে চিহ্নিত করে, তাই .env অনুপস্থিত থাকলে স্ট্যাকটি শুরু হতে অস্বীকার করে, যা ক্রেডেনশিয়াল এনক্রিপ্ট না করে শুরু হওয়া থেকে বিরত রাখে। কম্পোজ ফাইলে মানগুলো না রেখে .env-এ রাখা হলো Docker Compose env ফাইল এবং সিক্রেট নিবন্ধের আদর্শ পদ্ধতি।

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

রানটাইম চালু হলে /health, { "ok": true }-এর উত্তর দেয়। ss অবশ্যই 127.0.0.1:3000 প্রিন্ট করবে। যদি কোনো লাইনে 0.0.0.0:3000 লেখা থাকে, তার মানে পোর্ট ম্যাপিং এখনো আপস্ট্রিম মডেলে আছে এবং গেটওয়ে সরাসরি পুরো ইন্টারনেটকে উত্তর দিচ্ছে। হেলথ চেক-এ 'Connection refused' আসার অর্থ হলো কন্টেইনারটি এখনো লিসেন করছে না, তাই প্রক্সিতে হাত দেওয়ার আগে লগগুলো পড়ুন।

    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-এর জন্য একটি প্রকৃত হোস্টনাম প্রয়োজন

OOMOL_CONNECT_ORIGIN হলো সেই সেটিং যা ব্যবহারকারীরা এড়িয়ে যান, এবং এটি এড়িয়ে যাওয়ার ফলে OAuth এমনভাবে কাজ করা বন্ধ করে দেয় যা দেখে মনে হয় এটি প্রোভাইডারের কোনো ত্রুটি। রানটাইম সেই অরিজিন থেকে তার রিডাইরেক্ট URI তৈরি করে, যা <origin>/oauth/callback আকারে থাকে। এটি সেট না করা থাকলে, অরিজিন ডিফল্ট হিসেবে http://localhost:3000 গ্রহণ করে, ফলে রানটাইম প্রোভাইডারের কাছে http://localhost:3000/oauth/callback রিডাইরেক্ট 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:// প্রত্যাখ্যান করে। এই কারণেই এই ডিপ্লয়মেন্টের জন্য একটি হোস্টনাম এবং একটি সার্টিফিকেটের প্রয়োজন। প্রথমবার স্টার্ট করার আগেই অরিজিন সেট করুন, কারণ এই মানটি স্টার্টআপের সময় পড়া হয়: .env অথবা compose.yaml এডিট করার পর, এটি কার্যকর করতে পুনরায় docker compose up -d চালান।

আপনার প্রথম প্রোভাইডারকে OAuth-এর মাধ্যমে সংযুক্ত করুন

প্রথমে প্রোভাইডারের সাইটে OAuth অ্যাপ তৈরি করুন। GitHub-এ এর পাথ হলো Settings, তারপর Developer settings, তারপর OAuth Apps, এবং সবশেষে New OAuth App। অথরাইজেশন কলব্যাক URL হিসেবে https://connect.example.com/oauth/callback সেট করুন। ক্লায়েন্ট আইডি (client ID) এবং ক্লায়েন্ট সিক্রেট (client secret) সংরক্ষণ করে রাখুন।

প্রতিটি /api কলে অ্যাডমিন টোকেন থাকে, তাই শেল সেশনের জন্য এটি একবার এক্সপোর্ট করে নিন।

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

এই তালিকাটি প্রতিটি প্রোভাইডারের জন্য রানটাইম যে রিডাইরেক্ট URI আশা করে তা প্রদর্শন করে। আপনার অরিজিন (origin) কার্যকর হয়েছে কি না তা যাচাই করার এটিই দ্রুততম উপায়। যদি এটি এখনও localhost দেখায়, তবে কন্টেইনারটি পুরনো ভ্যালু নিয়ে চলছে এবং OAuth ফ্লো শেষ ধাপে গিয়ে ব্যর্থ হবে।

ক্লায়েন্ট ক্রেডেনশিয়ালগুলো সংরক্ষণ করুন, তারপর একটি অথরাইজেশন শুরু করুন।

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 প্রদান করে। এটি ব্রাউজারে খুলুন, স্কোপগুলো অনুমোদন করুন। এরপর প্রোভাইডার ব্রাউজারটিকে /oauth/callback-এ ফেরত পাঠাবে, যেখানে রানটাইম কোডটি বিনিময় করে ক্রেডেনশিয়াল সংরক্ষণ করবে। আপনার অরিজিনের ওয়েব কনসোল একই অ্যাডমিন টোকেনের অধীনে একটি ফর্মের মাধ্যমে এই ধাপগুলো সম্পন্ন করে। যে প্রোভাইডারগুলো সাধারণ API কি (API key) ব্যবহার করে, তাদের ক্ষেত্রে এই প্রক্রিয়ার প্রয়োজন নেই: PUT /api/connections/<service>-এর সাথে {"authType":"api_key","values":{"apiKey":"..."}} ব্যবহার করে সরাসরি কি (key) সংরক্ষণ করা যায়।

প্রতিটি এজেন্টকে একটি রানটাইম টোকেন দিন, কখনোই ক্রেডেনশিয়াল নয়

এজেন্ট একটি রানটাইম টোকেনের মাধ্যমে গেটওয়েতে অথেন্টিকেট করে, যা অ্যাডমিন 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":{}}'

একটি সঠিক উত্তরের এনভেলপের success ফিল্ডটি হয় true, যেখানে প্রোভাইডার পেলোডটি data-এর অধীনে থাকে। GitHub টোকেনটি সেই রেসপন্সের কোথাও থাকে না। একটি MCP ক্লায়েন্টের জন্য, সেটিকে https://connect.example.com/mcp-এর দিকে নির্দেশ করুন এবং একই বিয়ারার হেডার ব্যবহার করুন। গেটওয়ে তখন প্রতিটি API-এর জন্য একটি টুলের পরিবর্তে search_actions এবং execute_action-এর মতো ডিসকভারি টুল অফার করে, যা এজেন্টের টুলের তালিকা ছোট রাখে। VPS-এ MCP সার্ভার চালানো অংশে এই সংযোগের ক্লায়েন্ট দিকের বিষয়টি আলোচনা করা হয়েছে।

এটি শেষ করার আগে আরও একটি চেক করুন। authorization হেডারটি মুছে ফেলে অ্যাকশন কলটি পুনরায় করুন। প্রজেক্টের নিজস্ব কুইকস্টার্টে কোনো বিয়ারার ছাড়াই /v1 কল করা হয়, তাই রানটাইম অথ কনফিগার করা না থাকলে যে কেউ পোর্টটিতে অ্যাক্সেস করতে পারলে অ্যাকশনগুলো এক্সিকিউট করতে পারবে। যদি আপনার আনঅথেন্টিকেটেড কলটি সফল হয়, তবে আপনার কাছে দুটি উপায় আছে: রানটাইম টোকেন কনফিগার করুন এবং নিশ্চিত করুন যে অ্যানোনিমাস কলটি এখন ব্যর্থ হচ্ছে, অথবা রিভার্স প্রক্সিতে /api, /v1 এবং /mcp-কে শুধুমাত্র আপনার এজেন্টের অ্যাড্রেসগুলোর জন্য সীমাবদ্ধ করুন। শুধুমাত্র /oauth/callback-কে সবার জন্য উন্মুক্ত রাখতে হবে, কারণ প্রোভাইডারের ব্রাউজার রিডাইরেক্টের জন্য এটিই একমাত্র পথ।

এজেন্ট যা প্রয়োজন কেবল সেই অ্যাকশন লিস্টে সীমাবদ্ধ করুন

একটি গেটওয়ের পেছনে হাজারো প্রোভাইডার থাকা মানে ল্যাঙ্গুয়েজ মডেলের জন্য একটি বিশাল সারফেস উন্মুক্ত রাখা। দুটি কন্ট্রোল একে সংকুচিত করে।

OOMOL_CONNECT_ALLOWED_ACTIONS একটি কমা-সেপারেটেড অ্যালাউ-লিস্ট গ্রহণ করে এবং service.* ও * বুঝতে পারে। OOMOL_CONNECT_BLOCKED_ACTIONS হলো ডিনাই-লিস্ট, এবং ডিনাই-লিস্টের অগ্রাধিকার বেশি। অ্যালাউ-লিস্টকে github.get_current_user,github.list_issues-এ সেট করার অর্থ হলো, এজেন্ট যা-ই অনুরোধ করুক না কেন, অন্য সব অ্যাকশন প্রত্যাখ্যান করা হবে; এটিই একটি ভুল এবং একটি ইনসিডেন্টের মধ্যে পার্থক্য। রানটাইম টোকেনগুলো গ্লোবাল রুলসের ওপর ভিত্তি করে নিজস্ব অ্যাকশন রুল বহন করে এবং তাদের allowedProxies লিস্ট খালি থাকে, তাই আপনি অনুমতি না দেওয়া পর্যন্ত POST /v1/proxy/:service প্রত্যাখ্যান করা হয়। সেই প্রক্সি এন্ডপয়েন্ট আপনার ক্রেডেনশিয়াল সংযুক্ত করে একটি প্রোভাইডারের কাছে র-রিকোয়েস্ট ফরোয়ার্ড করে, তাই কোনো নির্দিষ্ট এজেন্টের প্রয়োজন না হলে এটি খালি রাখুন।

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK ডিফল্টভাবে false থাকে, যা একটি সেলফ-হোস্টেড প্রোভাইডার কানেকশনকে কোনো প্রাইভেট অ্যাড্রেসের দিকে নির্দেশ করা থেকে বিরত রাখে, যেমন 169.254.169.254-এ থাকা ক্লাউড মেটাডেটা সার্ভিস বা একই নেটওয়ার্কে থাকা আপনার ডাটাবেস। এটি বন্ধ রাখুন। শুধুমাত্র আপনার নিজের হোস্ট করা প্রোভাইডারের জন্য এটি চালু করুন।

প্রতিটি টোকেন ধারণকারী বক্সের ব্যাকআপ নিন

দুটি বিষয় গুরুত্বপূর্ণ এবং একটি ছাড়া অন্যটি অকেজো। connector-data ভলিউমের ভেতরে /app/data/connect.sqlite অবস্থানে থাকা ডেটাবেসটি সিল করা ক্রেডেনশিয়ালগুলো ধারণ করে। .env অবস্থানে থাকা এনক্রিপশন কি (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 থেকে সরিয়ে নিন, যা এটি পাঠানোর আগেই এনক্রিপ্ট করে ফেলে, কারণ ওই আর্কাইভটিই হলো ক্রেডেনশিয়াল স্টোর।

রানটাইম অডিট রেকর্ড হিসেবে সাম্প্রতিক অ্যাকশন রানগুলো সংরক্ষণ করে, ডিফল্টভাবে যার সংখ্যা 5000। তাই কনসোল আপনাকে জানাতে পারে কোন এজেন্ট কখন কী রান করেছে। কোনো এজেন্ট অস্বাভাবিক আচরণ করলে সবার আগে সেই লগটি পড়ুন। একটি Uptime Kuma স্ট্যাটাস পেজ-কে https://connect.example.com/health-এর দিকে নির্দেশ করুন। গেটওয়ে সাড়া দেওয়া বন্ধ করলে এজেন্টগুলো বিভ্রান্তিকর উপায়ে ফেইল করে, আর গেটওয়ে ডাউন আছে তা জানা থাকলে এজেন্টের আউটপুট পড়ার এক ঘণ্টা সময় বেঁচে যায়।

কী কী অকার্যকর হয় এবং আপনি যে বার্তাটি দেখবেন

প্রোভাইডারের কাছে redirect_uri_mismatch। অরিজিন এবং রেজিস্টার করা কলব্যাক URL ভিন্ন। /api/oauth/configs থেকে প্রাপ্ত সঠিক স্ট্রিংটি প্রোভাইডারের অ্যাপ সেটিংসের সাথে তুলনা করুন, যার মধ্যে https এবং http এর মধ্যকার পার্থক্য এবং কোনো ট্রেইলিং স্ল্যাশ অন্তর্ভুক্ত রয়েছে।

প্রতিটি /api কল 401 রিটার্ন করে। অ্যাডমিন টোকেন হেডারটি অনুপস্থিত অথবা ভুল বানান লেখা হয়েছে। হেডারটি হলো Authorization: Bearer <token>, এবং ওয়েব কনসোল একই টোকেন দাবি করে।

কন্টেইনারটি চলে, এবং ক্রেডেনশিয়ালগুলো প্লেইন টেক্সটে থাকে। এটি তখন ঘটে যখন OOMOL_CONNECT_ENCRYPTION_KEY কন্টেইনারে পৌঁছায় না, কারণ রানটাইম ক্রেডেনশিয়াল রেকর্ডগুলোকে এনক্রিপ্ট না করেই সংরক্ষণ করে, অথচ সেগুলোর কাজ শুরু করতে অস্বীকার করা উচিত ছিল। আপনার নিজের ইনস্টলে এটি যাচাই করুন: একটি পরিচিত API কি (key) দিয়ে একটি প্রোভাইডার কানেক্ট করুন, তারপর ডাটাবেসে সেটি অনুসন্ধান করুন।

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 মানটি প্রদর্শন করছে। কি (key) সেট করা থাকলে, একই অনুসন্ধানে 0 আসবে, কারণ রেকর্ডটি AES-256-GCM (অ্যাডভান্সড এনক্রিপশন স্ট্যান্ডার্ড, 256-বিট কি, গালোইস/কাউন্টার মোড) দিয়ে সিল করা থাকে।

রিস্টোরের পর কিছুই ডিক্রিপ্ট হয় না। এনক্রিপশন কি (key) পরিবর্তিত হয়েছে অথবা হারিয়ে গেছে। ডিজাইনের কারণে এটি কখনোই ডেটার পাশে লেখা থাকে না, তাই কোনো রিকভারি পাথ নেই এবং কোনো সাপোর্ট টিকিট এখানে সাহায্য করতে পারে না। প্রতিটি প্রোভাইডার পুনরায় কানেক্ট করুন। একটি আলাদা কি (key) ভেরিয়েবল এবং রানটাইমে একটি ডাটা কমান্ডের মাধ্যমে রোটেশন সমর্থিত হয়, তাই কোনো কিছু রোটেট করার আগে বর্তমান রিলিজ নোটগুলো পড়ে নিন।

এজেন্ট এমন একটি অ্যাকশনের নাম উল্লেখ করে এরর পায় যা সে ক্যাটালগে দেখতে পায়। ডিসকভারি এবং এক্সিকিউশন আলাদা বিষয়। একটি অ্যাকশন search_actions-এ দেখা যেতে পারে, কিন্তু তবুও সেটি OOMOL_CONNECT_ALLOWED_ACTIONS দ্বারা, ডেনলিস্ট দ্বারা, অথবা সেই রানটাইম টোকেনের নিজস্ব নিয়ম দ্বারা প্রত্যাখ্যাত হতে পারে।

আপগ্রেড। ভলিউমটি ব্যাকআপ নিন, নতুন রিলিজের জন্য ইমেজ ট্যাগটি এডিট করুন, তারপর docker compose pull && docker compose up -d করুন। মাইগ্রেশন লাইনের জন্য docker compose logs -n 50 connector পর্যবেক্ষণ করুন, এবং পুনরায় বিশ্বাস করার আগে হেলথ চেক ও একটি প্রকৃত অ্যাকশন চালিয়ে দেখুন। রোলব্যাক করার অর্থ হলো পুরনো ট্যাগটি পুনরায় বসানো, যা কেবল তখনই কাজ করে যদি আপনি সেটি পিন করে রাখেন।

FAQ

Open Connector সেলফ-হোস্ট করার জন্য কি আমার একটি পাবলিক ডোমেইন প্রয়োজন?

যেসব প্রোভাইডার API key ব্যবহার করে, তাদের জন্য প্রয়োজন নেই: 127.0.0.1-এ একটি গেটওয়েই যথেষ্ট। OAuth-এর ক্ষেত্রে, বাস্তবে এটি প্রয়োজন। প্রোভাইডার আপনার ব্রাউজারকে আপনার callback URL-এ রিডাইরেক্ট করে, তাই সেই URL-টিকে পাবলিক ইন্টারনেট থেকে রিজলভ হতে হয় এবং প্রোভাইডাররা localhost ছাড়া সাধারণ http:// গ্রহণ করে না। প্রথমবার চালু করার আগে OOMOL_CONNECT_ORIGIN-কে আপনার https:// হোস্টনামে সেট করুন এবং প্রোভাইডারের OAuth অ্যাপে <origin>/oauth/callback রেজিস্টার করুন।

আমি যদি Open Connector এনক্রিপশন কি (key) হারিয়ে ফেলি তবে কী হবে?

সংরক্ষিত ক্রেডেনশিয়ালগুলো আর ডিক্রিপ্ট করা যাবে না এবং এটি পুনরুদ্ধারের কোনো উপায় নেই। কি (key)-টি ইচ্ছাকৃতভাবে ডেটার সাথে রাখা হয় না, যাতে ডেটাবেস যার কাছেই থাকুক না কেন, কেউ তা পড়তে না পারে, আপনি নিজেও না। আপনার একমাত্র উপায় হলো একটি নতুন কি (key) সেট করা এবং প্রতিটি প্রোভাইডারকে পুনরায় কানেক্ট করা। কি (key)-টি একটি পাসওয়ার্ড ম্যানেজারে রাখুন এবং ডেটাবেসটিকে আপনার ব্যাকআপ রোটেশনে রাখুন, কারণ রিস্টোর করার জন্য উভয়ই প্রয়োজন।

আমার AI এজেন্ট কি প্রোভাইডার অ্যাক্সেস টোকেন দেখতে পায়?

গেটওয়ের মাধ্যমে কল করার সময় পায় না। এজেন্ট oct_ দিয়ে শুরু হওয়া একটি রানটাইম টোকেন দিয়ে অথেন্টিকেট করে এবং গেটওয়ে সার্ভারে আউটবাউন্ড রিকোয়েস্টে প্রোভাইডার ক্রেডেনশিয়াল ইনজেক্ট করে, শুধুমাত্র রেসপন্সটি ফেরত দেয়। দুটি কারণে এই বৈশিষ্ট্যটি কাজ করে না: /v1/proxy/:service এন্ডপয়েন্ট, যা আপনার ক্রেডেনশিয়াল সংযুক্ত করে সরাসরি রিকোয়েস্ট ফরওয়ার্ড করে এবং যার গ্র্যান্টগুলো খালি থাকে, এবং নিজে থেকে এজেন্টে API key পেস্ট করা, যা গেটওয়েকে পুরোপুরি এড়িয়ে যায়।

গেটওয়ে কি পাবলিক ইন্টারনেট থেকে অ্যাক্সেসযোগ্য হওয়া উচিত?

শুধুমাত্র /oauth/callback অ্যাক্সেসযোগ্য হওয়া প্রয়োজন। কন্টেইনার পোর্টটিকে 127.0.0.1-এ পাবলিশ করুন যাতে Docker-এর NAT রুলগুলো আপনার ফায়ারওয়ালের বাইরে এটিকে এক্সপোজ করতে না পারে এবং সামনে একটি রিভার্স প্রক্সি বসান। এরপর কোনো authorization হেডার ছাড়া একটি অ্যাকশন কল টেস্ট করুন। যদি এটি সফল হয়, তবে অথেন্টিকেটেড কল ছাড়া অন্য কিছু কাজ না করা পর্যন্ত প্রক্সিতে /api, /v1 এবং /mcp-কে আপনার এজেন্টের ব্যবহৃত অ্যাড্রেসগুলোতে সীমাবদ্ধ করুন।

Open Connector কি প্রোডাকশন ব্যবহারের জন্য প্রস্তুত?

এটি Apache 2.0 লাইসেন্সপ্রাপ্ত এবং দ্রুত পরিবর্তিত হচ্ছে: রিপোজিটরিটি 29 জুন 2026-এ প্রকাশিত হয় এবং 30 জুলাই 2026-এ v1.3.3 রিলিজ হয়, তাই এই গাইডের প্রতিটি ভার্সন নম্বরকে 1 আগস্ট 2026-এর একটি স্ন্যাপশট হিসেবে গণ্য করুন। এটিকে সবসময় একটি রিলিজ ট্যাগের সাথে পিন করে চালান, কখনোই latest বা tip-এ চালাবেন না, প্রতিটি আপগ্রেডের আগে রিলিজ নোটগুলো পড়ুন এবং এমন একটি ভলিউম ব্যাকআপ রাখুন যা আপনি অন্তত একবার রিস্টোর করে দেখেছেন। আপনার নিজস্ব সার্ভারের জন্য এর ডিজাইনটি সঠিক, এবং ঝুঁকিটি আর্কিটেকচারে নয়, বরং ভার্সন পরিবর্তনের দ্রুততায়।