Open Connector কীভাবে নিজের সার্ভারে সেটআপ করবেন

একটি AI agent-এর জন্য Open Connector কী করে

Open Connector self-host করে আপনার AI agent এবং তাদের ব্যবহৃত প্রতিটি software as a service (SaaS) API-এর মধ্যে একটি auth gateway বসানো যায়। ফলে agent-এর কাছে কোনো provider token থাকে না। এটি OOMOL Lab-এর source-available gateway। বর্তমানে এটি অতিরিক্ত শর্তসহ পরিবর্তিত Apache 2.0 license-এর অধীনে licensed। v1.9.4 পর্যন্ত release-গুলো Apache 2.0-এর অধীনে রয়েছে; v1.9.5 থেকে পরিবর্তনটি চালু হয়েছে। OpenConnector-এর functionality-কে প্রধান মূল্য হিসেবে ব্যবহার করে hosted বা managed service দিতে হলে OOMOL-এর কাছ থেকে commercial license নিতে হবে। এটি একটি container হিসেবে চলে, একটি SQLite file-এ নিজের state সংরক্ষণ করে এবং HTTP ও MCP (model context protocol)—উভয়ের মাধ্যমে provider action প্রকাশ করে।

দ্বিতীয় integration থেকেই মূল সমস্যা শুরু হয়। প্রতিটি provider-এর নিজস্ব OAuth (open authorization) flow, নিজস্ব refresh token lifetime এবং নিজস্ব scope name থাকে। একটি agent-এ হাতে করে পাঁচটি provider যুক্ত করতে হলে পাঁচটি redirect handler, পাঁচটি credential store এবং token expire হওয়ার আগে চালানোর জন্য পাঁচটি refresh loop লিখতে হয়। প্রায় কেউই এই code লেখে না। তারা প্রতিটি service-এর জন্য একটি করে দীর্ঘমেয়াদি personal access token তৈরি করে সেটি agent config, environment file বা সরাসরি prompt-এ বসিয়ে দেয়। এরপর agent যে প্রতিটি tool চালায়, সেগুলো token-টি পড়তে পারে। token-টি transcript-এও চলে আসে। AI agent থেকে secret দূরে রাখা এই ব্যর্থতার কথাই ব্যাখ্যা করে।

একটি auth gateway credential-কে দুই ভাগে আলাদা করে। Gateway provider credential সংরক্ষণ করে এবং OAuth flow চালায়। Agent এমন একটি runtime token পায়, যা শুধু gateway-এর বিরুদ্ধে কার্যকর। Agent কোনো action call করলে gateway সংরক্ষিত credential লোড করে, server side-এ সেটি outbound request-এ যুক্ত করে এবং কেবল response body ফেরত দেয়। Agent কখনো provider access token পায় না। তাই agent transcript ফাঁস হলেও আপনার GitHub account-এর বদলে একটি revocable runtime token-ই ঝুঁকিতে পড়ে।

Catalog-এ 1,000-এর বেশি provider এবং 10,000টি prebuilt action-এর কথা বলা হয়েছে। এটি প্রকল্পটির নিজস্ব পরিসংখ্যান; বাইরে থেকে এটি যাচাই করা যায় না। তবে যে কাঠামো যাচাই করা যায় তা হলো: প্রতিটি action-এর জন্য একটি HTTP endpoint, প্রতিটি provider-এর জন্য একটি stored connection এবং প্রতিটি agent-এর জন্য একটি token। Agent-এর দিকটি যদি এখনও নতুন হয় এবং tool call বা MCP server-এর মতো term-এর ব্যবহার এখনও স্থির না হয়ে থাকে, তাহলে শূন্য থেকে AI agent শেখার পদ্ধতি-তে দেওয়া ধাপে ধাপে পথটি loop, tool এবং safety habit সম্পর্কে ভিত্তি তৈরি করবে। এই gateway-ও ধরে নেয় যে এগুলো আপনার আগে থেকেই জানা আছে।

Hosted connector service ব্যবহার না করে কেন self-host Open Connector করবেন

একটি hosted connector service একই কাজ করে। এটি আপনার সঙ্গে সংযুক্ত প্রতিটি provider-এর refresh token সংরক্ষণ করে। Google বা GitHub-এর refresh token হলো আপনার mail ও repository-তে দীর্ঘমেয়াদি প্রবেশাধিকার দেওয়া cryptographic credential। তাদের server breached হলে আপনার credential-ও ঝুঁকিতে পড়বে। Self-hosting করলে এই record-গুলো আপনার ভাড়া নেওয়া এবং পরিচালিত একটি machine-এর SQLite-এ থাকে। এগুলো এমন একটি key দিয়ে সুরক্ষিত থাকে, যা কখনও আপনার box ছেড়ে যায় না।

শুরু করার আগে খরচটি স্পষ্টভাবে হিসাব করুন। এই VPS আপনার পরিচালিত সবচেয়ে গুরুত্বপূর্ণ server হয়ে উঠবে। একটি file-এ এক ডজন service-এর কার্যকর credential থাকে। তাই এটিকে password manager host-এর মতো সুরক্ষা দিতে হবে: firewall-এ শুধু 443 expose থাকবে, shared login থাকবে না, এমন backup থাকবে যা আপনি অন্তত একবার restore করে পরীক্ষা করেছেন, এবং server উত্তর দেওয়া বন্ধ করলে alert আসবে। আপনি যদি এই box-এ আপনার password vault রাখতে না চান, তাহলে connector-ও এখানে রাখবেন না।

ইনস্টল করার আগে একটি version নির্দিষ্ট করুন

Open Connector এখনও নতুন। এই guide-এ 30 July 2026-এ প্রকাশিত v1.3.3-কে 1 August 2026-এর installation snapshot হিসেবে নির্দিষ্ট করা হয়েছে। এটি আর সর্বশেষ release নয়। registry-তে একটি tip tag-ও প্রকাশিত হয়, যা main-এর সর্বশেষ commit থেকে তৈরি।

এত নতুন কোনো project-এ পরিবর্তনশীল tag প্রায়ই পরিবর্তিত হয়। দুটি release এগিয়ে যাওয়া একটি docker compose pull আপনার agent যে endpoint-এর ওপর নির্ভর করে সেটি পরিবর্তন করতে পারে। তখন আপনি সেটিকে agent-এর সমস্যা ভেবে সন্ধ্যা পর্যন্ত debugging করতে পারেন। image-কে একটি release tag-এ নির্দিষ্ট করুন। এরপর release notes পড়ে, আপনার সিদ্ধান্ত অনুযায়ী upgrade করুন।

নিজের VPS-এ TLS-এর পেছনে Open Connector deploy করুন

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

• Compose plugin-সহ Docker Engine 28.0.0 বা পরবর্তী সংস্করণ, Ubuntu 24.04 বা কাছাকাছি কোনো সিস্টেমে
• এমন একটি hostname, যার A record এই VPS-এর দিকে নির্দেশ করে; উদাহরণস্বরূপ connect.example.com
• এমন একটি reverse proxy, যা ইতিমধ্যে ওই hostname-এর জন্য TLS (transport layer security) termination করে
• নিচে তৈরি করা দুটি random secret

একাধিক Docker Compose অ্যাপের জন্য Traefik reverse proxy-এ proxy অংশটি দেখানো হয়েছে। একটি অ্যাপের জন্য শুরু থেকে শেষ পর্যন্ত একই certificate plumbing-এর নির্দেশনা Docker ও HTTPS-সহ VPS-এ n8n গাইডে আছে।

প্রথমে secret তৈরি করুন। Encryption key সংরক্ষিত credential সুরক্ষিত করে। Admin token web console এবং সম্পূর্ণ /api surface সুরক্ষিত করে। কোনোটিরই default নেই, এবং এগুলো ছাড়াই 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

প্রথমবার চালু করার আগে এখনই দুটি value আপনার password manager-এ কপি করুন। Encryption key পুনরুদ্ধারের কোনো পথ নেই। এর কারণ নিচের failure list-এ ব্যাখ্যা করা হয়েছে।

এখন compose.yaml। এটি upstream example থেকে দুটি জায়গায় আলাদা, এবং দুটিই গুরুত্বপূর্ণ।

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-এর পরিবর্তে নির্দিষ্ট tag ব্যবহার করা। দ্বিতীয়টি হলো port। Upstream file 3000:3000 publish করে, যা host-এর প্রতিটি interface-এ bind হয়। Docker ufw filter chain packet দেখার আগেই published port-গুলো NAT (network address translation) table-এ লিখে দেয়। তাই ufw deny 3000 ওই port বন্ধ করে না। Docker port কেন ufw bypass করে-এ এই ফাঁদটি ব্যাখ্যা করা হয়েছে। 127.0.0.1:3000:3000 লিখলে শুধু loopback interface-এ publish হয়, এবং আপনার reverse proxy একই host থেকে সংযোগ করে। Docker Engine 28.0.0-এর আগে একই L2 segment-এর host-গুলো localhost-এ publish করা port-এ পৌঁছাতে পারত। তাই এই গাইডে 28.0.0 বা পরবর্তী সংস্করণ প্রয়োজন।

:? প্রতিটি variable-কে required হিসেবে চিহ্নিত করে। ফলে .env অনুপস্থিত থাকলে stack চালু হতে অস্বীকার করে, credential encryption ছাড়া চালু হয় না। Compose file-এ value না রেখে .env-এ রাখার পদ্ধতিটি Docker Compose env file ও secret-এ দেখানো pattern অনুসরণ করে। নিচের প্রথম runtime token তৈরি না করা পর্যন্ত /v1 এবং /mcp reverse proxy-তে private রাখুন।

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 print করতে হবে। 0.0.0.0:3000 লেখা একটি line-এর অর্থ হলো listener প্রতিটি IPv4 interface-এ bind করা আছে। তবে এতে Internet থেকে পৌঁছানো যায়, এমন প্রমাণ হয় না। Upstream firewall বা Docker-এর DOCKER-USER chain-এর rule এখনও external traffic block করতে পারে। Health check-এ connection refused দেখালে container এখনও listen করছে না। তাই proxy পরিবর্তন করার আগে log পড়ুন।

    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 callback-এর জন্য সঠিক origin কেন প্রয়োজন

OOMOL_CONNECT_ORIGIN হলো সেই setting, যা অনেকে বাদ দেন। এটি বাদ দিলে OAuth এমনভাবে ব্যর্থ হয় যে provider-এর bug মনে হয়। Runtime এই origin থেকে redirect URI তৈরি করে, যার রূপ <origin>/oauth/callback। Origin সেট না করা থাকলে এটি http://localhost:3000-এ default হয়। ফলে runtime provider-কে http://localhost:3000/oauth/callback redirect URI পাঠায়, অথচ আপনার OAuth app-এ https://connect.example.com/oauth/callback registered আছে। দুটি string আলাদা হওয়ায় GitHub উত্তর দেয়:

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

OAuth provider browser-কে ওই URI-তে redirect করে। তাই URI-টি browser থেকে reachable হতে হবে। OAuth-এর জন্য সব ক্ষেত্রে public hostname প্রয়োজন হয় না। OpenConnector http://localhost:3000/oauth/callback-এ GitHub callback নথিভুক্ত করেছে। এই VPS deployment-এ hostname এবং certificate ব্যবহার করা হয়েছে, যাতে browser তার HTTPS origin দিয়ে gateway-এ পৌঁছাতে পারে। প্রথমবার start করার আগেই origin সেট করুন, কারণ value-টি startup-এর সময় পড়া হয়। .env বা compose.yaml edit করার পরে এটি প্রয়োগ করতে আবার 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 থাকে, তাই শেল সেশনের জন্য এটি একবার 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 প্রদান করে। এটি ব্রাউজারে ওপেন করুন, স্কোপগুলো অনুমোদন করুন, এবং প্রোভাইডার ব্রাউজারটিকে /oauth/callback-এ ফেরত পাঠাবে, যেখানে রানটাইম কোডটি বিনিময় করে ক্রেডেনশিয়াল সংরক্ষণ করবে। আপনার অরিজিনে থাকা ওয়েব কনসোলটি একই admin token ব্যবহার করে একটি ফর্মের মাধ্যমে এই ধাপগুলো সম্পন্ন করে। যেসব প্রোভাইডার সাধারণ API key ব্যবহার করে তারা এই ধাপগুলো এড়িয়ে যায়: PUT /api/connections/<service>-এর সাথে {"authType":"api_key","values":{"apiKey":"..."}} ব্যবহার করে সরাসরি কি (key) সংরক্ষণ করা যায়।

প্রতিটি agent-কে runtime token দিন, credential কখনো নয়

Agent gateway-এর সঙ্গে runtime token ব্যবহার করে authentication করে। Admin API এই token তৈরি করে।

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"}'

Response-এ oct_ দিয়ে শুরু হওয়া একটি token থাকে। প্রতিটি agent-এর জন্য একটি করে token issue করুন এবং সেটির নাম ওই agent-এর নামে রাখুন। কারণ কোন token কোন agent-এর তা শনাক্ত করতে না পারলে একটি token revoke করতে গিয়ে সব token revoke করতে হতে পারে। এরপর agent সাধারণ HTTP ব্যবহার করে action call করে।

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":{}}'

সফল response হলো এমন একটি envelope, যার success field-এর মান true এবং provider payload data-এর অধীনে থাকে। ওই response-এর কোথাও GitHub token থাকে না। MCP client-এর ক্ষেত্রে একই bearer header ব্যবহার করে সেটিকে https://connect.example.com/mcp-এ point করুন। Gateway তখন প্রতিটি API-এর জন্য আলাদা tool না দিয়ে search_actions ও execute_action-এর মতো discovery tool প্রদান করে। এতে agent-এর tool list ছোট থাকে। VPS-এ MCP server চালানো-এ এই wiring-এর client অংশটি ব্যাখ্যা করা হয়েছে।

এটিকে সম্পূর্ণ মনে করার আগে আরও একটি পরীক্ষা চালান। authorization header মুছে action call-টি আবার করুন। প্রকল্পটির নিজস্ব quickstart-এ কোনো bearer ছাড়াই /v1 call করা হয়েছে। তাই runtime authentication configure না করা installation-এ port-এ পৌঁছাতে পারে এমন যে কেউ action চালাতে পারবে। Unauthenticated call সফল হলে দুটি ব্যবস্থা নিতে পারেন: runtime token configure করে নিশ্চিত করুন যে anonymous call এখন ব্যর্থ হচ্ছে, অথবা reverse proxy-তে /api, /v1 এবং /mcp কেবল আপনার agent-গুলো যে address থেকে আসে সেগুলোতে সীমাবদ্ধ করুন। Authorization সম্পন্ন করা browser-এর কাছে /oauth/callback reachable থাকতে হবে; এটি পুরো internet-এর জন্য open থাকার প্রয়োজন নেই।

এজেন্টের প্রয়োজনীয় কাজের তালিকা সীমিত করুন

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

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-এ থাকা ক্লাউড মেটাডেটা সার্ভিস বা একই নেটওয়ার্কে থাকা আপনার ডাটাবেস। এটি বন্ধ রাখুন। শুধুমাত্র আপনার নিজের হোস্ট করা কোনো প্রোভাইডারের ক্ষেত্রে এটি চালু করুন।

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

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

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

কী কী সমস্যা হতে পারে এবং আপনি যে বার্তাগুলো দেখবেন

redirect_uri_mismatch প্রোভাইডারের ক্ষেত্রে। অরিজিন এবং রেজিস্টার করা কলব্যাক URL ভিন্ন। /api/oauth/configs থেকে পাওয়া সঠিক স্ট্রিংটির সাথে প্রোভাইডারের অ্যাপ সেটিংস মিলিয়ে দেখুন, যার মধ্যে https এবং http-এর পার্থক্য এবং কোনো ট্রেইলিং স্ল্যাশ (trailing slash) আছে কি না তা যাচাই করুন।

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

কন্টেইনার চলছে, কিন্তু ক্রেডেনশিয়ালগুলো প্লেইন টেক্সটে আছে। এটি তখন ঘটে যখন OOMOL_CONNECT_ENCRYPTION_KEY কন্টেইনারে পৌঁছায় না, কারণ রানটাইম ক্রেডেনশিয়াল রেকর্ডগুলো এনক্রিপ্ট না করেই সংরক্ষণ করে, অথচ তার উচিত ছিল শুরু হতে অস্বীকার করা। আপনার নিজের ইন্সটলেশন পরীক্ষা করুন: একটি পরিচিত API কি (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-বিট কি, গালোইস/কাউন্টার মোড) দিয়ে সিল করা থাকে।

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

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

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

FAQ

Open Connector self-host করার জন্য কি public domain প্রয়োজন?

API key ব্যবহারকারী provider-এর ক্ষেত্রে নয়: 127.0.0.1-এ একটি gateway যথেষ্ট। OAuth-এর ক্ষেত্রেও সব সময় public domain প্রয়োজন হয় না: OpenConnector GitHub-এর local callback হিসেবে http://localhost:3000/oauth/callback নথিভুক্ত করেছে। Authorization সম্পন্ন করা browser-কে callback URL-এ পৌঁছাতে হবে। এই VPS deployment-এর জন্য প্রথমবার start করার আগে OOMOL_CONNECT_ORIGIN-এ আপনার https:// hostname সেট করুন এবং provider-এর OAuth app-এ <origin>/oauth/callback নিবন্ধন করুন।

Open Connector-এর encryption key হারালে কী হয়?

সংরক্ষিত credential decrypt করা যাবে না এবং কোনো recovery ব্যবস্থা নেই। নিরাপত্তার কারণে key-টি কখনো data-এর সঙ্গে রাখা হয় না। তাই database যার কাছেই থাকুক, এমনকি আপনার কাছেও, সে এটি পড়তে পারবে না। একমাত্র উপায় হলো নতুন key সেট করা এবং প্রতিটি provider আবার connect করা। Key-টি password manager-এ রাখুন এবং database-কে আপনার backup rotation-এর অন্তর্ভুক্ত রাখুন, কারণ restore করতে দুটিই প্রয়োজন।

আমার AI agent কি provider access token দেখতে পারে?

Gateway-এর মাধ্যমে call করলে পারে না। Agent oct_ দিয়ে শুরু হওয়া একটি runtime token ব্যবহার করে authenticate করে। Gateway server-এ outbound request-এর মধ্যে provider credential যুক্ত করে এবং শুধু response ফেরত দেয়। দুটি ক্ষেত্রে এই সুরক্ষা নষ্ট হয়: /v1/proxy/:service endpoint raw request-এ আপনার credential যুক্ত করে forward করে, এবং এর grant শুরুতে empty রাখার কারণ আছে; আর আপনি নিজে agent-এ API key paste করলে gateway সম্পূর্ণ এড়িয়ে যাওয়া হয়।

Gateway কি public Internet থেকে reachable রাখা উচিত?

Authorization সম্পন্ন করা browser-কে OAuth callback-এ পৌঁছাতে হবে। এর জন্য পুরো Internet থেকে access দেওয়া প্রয়োজন নেই। Docker Engine 28.0.0 বা পরবর্তী সংস্করণ এবং default bridge networking ব্যবহার করলে container port-টি 127.0.0.1-এ publish করুন। এতে published port শুধু host থেকেই accessible থাকবে। এরপর reverse proxy সামনে রাখুন। পুরোনো Docker release-গুলোতে একই L2 segment-এর host-গুলো localhost-published port-এ পৌঁছাতে পারত। তারপর কোনো authorization header ছাড়া একটি action call পরীক্ষা করুন। এটি সফল হলে proxy-তে /api, /v1 এবং /mcp শুধু আপনার agent-গুলো যে address ব্যবহার করে সেগুলোতে সীমাবদ্ধ করুন, যতক্ষণ না authenticated call ছাড়া অন্য সব call ব্যর্থ হয়।

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

বর্তমান release-গুলো অতিরিক্ত শর্তসহ পরিবর্তিত Apache 2.0 license ব্যবহার করে। v1.9.4 পর্যন্ত release-গুলো, যার মধ্যে pinned v1.3.3-ও রয়েছে, Apache 2.0 license-এর অধীনেই থাকে। বর্তমান license অনুযায়ী, যার মূল মূল্য OpenConnector-এর functionality, এমন hosted বা managed connector service-এর জন্য OOMOL-এর কাছ থেকে commercial license প্রয়োজন। v1.3.3 installation command-গুলো 1 August 2026-এর একটি snapshot। এই release 30 July 2026-এ প্রকাশিত হয়েছিল। এটিকে release tag-এ pin করে চালান। কখনো latest বা tip-এ চালাবেন না। প্রতিটি upgrade-এর আগে release note পড়ুন এবং এমন একটি volume backup রাখুন যেটি অন্তত একবার restore করে পরীক্ষা করেছেন। আপনার মালিকানাধীন একটি server-এর জন্য design-টি নির্ভরযোগ্য। ঝুঁকি architecture-এ নয়, version পরিবর্তনের ধারাবাহিকতায়।