Open Connectorను సెల్ఫ్-హోస్ట్ చేయడం ఎలా?

AI ఏజెంట్ కోసం Open Connector ఏమి చేస్తుంది

Open Connectorను సెల్ఫ్-హోస్ట్ చేయడం ద్వారా, మీ AI ఏజెంట్లు మరియు అవి కాల్ చేసే ప్రతి సాఫ్ట్‌వేర్ యాజ్ ఏ సర్వీస్ (SaaS) 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 కోసం ఒక రిఫ్రెష్ టోకెన్ అనేది మీ మెయిల్ మరియు మీ రిపోజిటరీలకు సంబంధించిన దీర్ఘకాలిక కీ, మరియు ఇది సాధారణంగా పాస్‌వర్డ్ మార్పు తర్వాత కూడా పనిచేస్తుంది. వాటికి భద్రతా ఉల్లంఘన జరిగితే, అది మీకు కూడా భద్రతా ఉల్లంఘన అవుతుంది. సెల్ఫ్-హోస్టింగ్ ద్వారా ఆ రికార్డులను మీరు అద్దెకు తీసుకుని, నిర్వహించే మెషీన్‌లోని SQLite లోకి తరలించవచ్చు. ఇవి మీ సర్వర్ నుండి బయటకు వెళ్లని కీతో సురక్షితంగా ఉంటాయి.

మీరు ప్రారంభించే ముందు దీని ఖర్చును ఒకసారి అంచనా వేయండి. ఈ 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 ప్లగిన్
• మీ VPSని సూచించే A రికార్డు కలిగిన హోస్ట్‌నేమ్, ఉదాహరణకు connect.example.com
• ఆ హోస్ట్‌నేమ్ కోసం ఇప్పటికే TLS (ట్రాన్స్‌పోర్ట్ లేయర్ సెక్యూరిటీ)ని ముగించే రివర్స్ ప్రాక్సీ
• కింద రూపొందించిన రెండు రాండమ్ సీక్రెట్స్

అనేక Docker Compose యాప్‌ల కోసం Traefik రివర్స్ ప్రాక్సీ గైడ్ ప్రాక్సీ వైపు ఉన్న అంశాలను వివరిస్తుంది. ఒకే యాప్ కోసం సర్టిఫికేట్ సెటప్ పూర్తి వివరాలు Docker మరియు HTTPSతో VPSలో n8n గైడ్‌లో ఉన్నాయి.

ముందుగా సీక్రెట్స్‌ను రూపొందించండి. ఎన్‌క్రిప్షన్ కీ నిల్వ చేసిన క్రెడెన్షియల్స్‌ను భద్రపరుస్తుంది. అడ్మిన్ టోకెన్ వెబ్ కన్సోల్‌ను మరియు మొత్తం /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ని పబ్లిష్ చేస్తుంది, ఇది హోస్ట్‌లోని ప్రతి ఇంటర్‌ఫేస్‌కు బైండ్ అవుతుంది. ufw ఫిల్టర్ చైన్ ప్యాకెట్‌ను చూడకముందే Docker తన పబ్లిష్ చేసిన పోర్ట్‌లను NAT (నెట్‌వర్క్ అడ్రస్ ట్రాన్స్‌లేషన్) టేబుల్‌లో రాస్తుంది, కాబట్టి 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 ఎందుకు నిజమైన హోస్ట్‌నేమ్ (hostname) ఉండాలని కోరుకుంటుంది

OOMOL_CONNECT_ORIGIN అనేది చాలామంది విస్మరించే సెట్టింగ్. దీనిని విస్మరించడం వల్ల OAuth పని చేయదు, ఇది ఏదో ప్రొవైడర్ బగ్ లాగా కనిపిస్తుంది. రన్‌టైమ్ ఆ ఆరిజిన్ (origin) నుండి తన రీడైరెక్ట్ URIని <origin>/oauth/callback రూపంలో నిర్మిస్తుంది. దీనిని సెట్ చేయకపోతే, ఆరిజిన్ డిఫాల్ట్‌గా http://localhost:3000 అవుతుంది. కాబట్టి, మీ OAuth యాప్‌లో https://connect.example.com/oauth/callback రిజిస్టర్ అయి ఉన్నప్పటికీ, రన్‌టైమ్ ప్రొవైడర్‌కు http://localhost:3000/oauth/callback అనే రీడైరెక్ట్ URIని పంపుతుంది. ఈ రెండు స్ట్రింగ్‌లు వేర్వేరుగా ఉండటం వల్ల, 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కి సెట్ చేయండి. క్లయింట్ ID మరియు క్లయింట్ సీక్రెట్‌ను భద్రపరచుకోండి.

ప్రతి /api కాల్ అడ్మిన్ టోకెన్‌ను కలిగి ఉంటుంది, కాబట్టి షెల్ సెషన్ కోసం దానిని ఒకసారి ఎక్స్‌పోర్ట్ చేయండి.

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

ఆ లిస్టింగ్ ప్రతి ప్రొవైడర్ కోసం రన్‌టైమ్ ఆశిస్తున్న రీడైరెక్ట్ URIని చూపుతుంది. మీ ఆరిజిన్ అమల్లోకి వచ్చిందో లేదో తనిఖీ చేయడానికి ఇది వేగవంతమైన మార్గం. ఒకవేళ అది ఇప్పటికీ 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 కీని ఉపయోగించే ప్రొవైడర్లు వీటన్నింటినీ దాటవేస్తాయి: PUT /api/connections/<service>తో పాటు {"authType":"api_key","values":{"apiKey":"..."}} కీని నేరుగా స్టోర్ చేస్తుంది.

ప్రతి ఏజెంట్‌కు రన్‌టైమ్ టోకెన్‌ను కేటాయించండి, క్రెడెన్షియల్స్‌ను ఎప్పుడూ ఇవ్వకండి

ఏజెంట్ అడ్మిన్ API ద్వారా రూపొందించబడిన రన్‌టైమ్ టోకెన్‌తో గేట్‌వేకి ప్రామాణీకరణ (authenticate) చేసుకుంటుంది.

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 ద్వారా చర్యలను (actions) అమలు చేస్తుంది.

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ని కాల్ చేస్తుంది. కాబట్టి, రన్‌టైమ్ ఆథరైజేషన్ కాన్ఫిగర్ చేయకుండా ఇన్‌స్టాల్ చేస్తే, ఆ పోర్ట్‌ను యాక్సెస్ చేయగల ఎవరైనా చర్యలను అమలు చేయవచ్చు. ఒకవేళ మీ అనామక కాల్ (unauthenticated call) విజయవంతమైతే, మీకు రెండు మార్గాలు ఉన్నాయి: రన్‌టైమ్ టోకెన్‌లను కాన్ఫిగర్ చేసి అనామక కాల్ విఫలమవుతుందని నిర్ధారించుకోండి, లేదా రివర్స్ ప్రాక్సీ వద్ద /api, /v1 మరియు /mcpలను మీ ఏజెంట్లు వచ్చే అడ్రస్‌లకు మాత్రమే పరిమితం చేయండి. కేవలం /oauth/callback మాత్రమే ప్రపంచానికి అందుబాటులో ఉండాలి, ఎందుకంటే ప్రొవైడర్ బ్రౌజర్ రీడైరెక్ట్‌కు ఇది మాత్రమే ఏకైక మార్గం.

ఏజెంట్‌కు అవసరమైన చర్యల జాబితాను తగ్గించడం

వెనుక వేలకొద్దీ ప్రొవైడర్లు ఉన్న గేట్‌వే, లాంగ్వేజ్ మోడల్‌కు విస్తృతమైన యాక్సెస్ ఉపరితలాన్ని అందిస్తుంది. రెండు నియంత్రణలు దీనిని పరిమితం చేస్తాయి.

OOMOL_CONNECT_ALLOWED_ACTIONS అనేది కామాతో వేరు చేయబడిన అనుమతించబడిన జాబితాను (allowlist) తీసుకుంటుంది మరియు service.* అలాగే * లను అర్థం చేసుకుంటుంది. OOMOL_CONNECT_BLOCKED_ACTIONS అనేది నిరోధించబడిన జాబితా (denylist), మరియు నిరోధించబడిన జాబితాకు ప్రాధాన్యత ఉంటుంది. అనుమతించబడిన జాబితాను github.get_current_user,github.list_issues కి సెట్ చేయడం అంటే, ఏజెంట్ దేనిని కోరినప్పటికీ మిగిలిన అన్ని చర్యలు తిరస్కరించబడతాయి; ఇది ఒక పొరపాటుకు మరియు ఒక భద్రతా సంఘటనకు మధ్య ఉన్న వ్యత్యాసం. రన్‌టైమ్ టోకెన్‌లు గ్లోబల్ నియమాలపై అదనంగా తమ సొంత చర్యల నియమాలను కలిగి ఉంటాయి, మరియు వాటి allowedProxies జాబితా ఖాళీగా ప్రారంభమవుతుంది, కాబట్టి మీరు అనుమతించే వరకు POST /v1/proxy/:service తిరస్కరించబడుతుంది. ఆ ప్రాక్సీ ఎండ్‌పాయింట్ మీ క్రెడెన్షియల్‌ను జత చేసి ఒక ముడి అభ్యర్థనను (raw request) ప్రొవైడర్‌కు ఫార్వర్డ్ చేస్తుంది, కాబట్టి ఏదైనా ఒక నిర్దిష్ట ఏజెంట్‌కు అవసరమైతే తప్ప దానిని ఖాళీగా ఉంచండి.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK డిఫాల్ట్‌గా false కి సెట్ చేయబడి ఉంటుంది, ఇది సెల్ఫ్-హోస్టెడ్ ప్రొవైడర్ కనెక్షన్‌ను 169.254.169.254 లోని క్లౌడ్ మెటాడేటా సర్వీస్ వంటి ప్రైవేట్ అడ్రస్‌లకు లేదా అదే నెట్‌వర్క్‌లోని మీ డేటాబేస్‌కు పాయింట్ చేయకుండా నిరోధిస్తుంది. దీనిని ఆఫ్ చేసి ఉంచండి. మీరు స్వయంగా హోస్ట్ చేసే ప్రొవైడర్ కోసం మాత్రమే దీనిని ఆన్ చేయండి.

అన్ని టోకెన్లను కలిగి ఉన్న బాక్స్‌ను బ్యాకప్ చేయండి

రెండు విషయాలు ముఖ్యమైనవి, ఒకదానితో ఒకటి లేకుండా మరొకటి పనికిరాదు. connector-data వాల్యూమ్‌లోని /app/data/connect.sqlite వద్ద ఉన్న డేటాబేస్ సీల్ చేయబడిన క్రెడెన్షియల్స్‌ను కలిగి ఉంటుంది. .env లోని ఎన్‌క్రిప్షన్ కీ వాటిని అన్‌సీల్ చేస్తుంది. కీ లేకుండా వాల్యూమ్ బ్యాకప్ దేనినీ పునరుద్ధరించదు, అలాగే వాల్యూమ్ లేకుండా కీ దేనినీ పునరుద్ధరించదు. కాబట్టి, కీని మీ పాస్‌వర్డ్ మేనేజర్‌లో ఉంచండి మరియు వాల్యూమ్‌ను మీ సాధారణ బ్యాకప్ రొటేషన్‌లో చేర్చండి.

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. ఆరిజిన్ మరియు రిజిస్టర్ చేయబడిన కాల్‌బ్యాక్ URLలు భిన్నంగా ఉన్నాయి. /api/oauth/configs నుండి వచ్చిన ఖచ్చితమైన స్ట్రింగ్‌ను ప్రొవైడర్ యాప్ సెట్టింగ్‌లతో పోల్చండి, ఇందులో https ను http తో మరియు చివరన ఉండే స్లాష్‌తో సహా సరిచూసుకోండి.

ప్రతి /api కాల్ 401ని తిరిగి ఇస్తుంది. అడ్మిన్ టోకెన్ హెడర్ లేదు లేదా తప్పుగా వ్రాయబడింది. హెడర్ Authorization: Bearer <token>, మరియు వెబ్ కన్సోల్ అదే టోకెన్‌ను అడుగుతుంది.

కంటైనర్ రన్ అవుతుంది, మరియు క్రెడెన్షియల్స్ ప్లెయిన్ టెక్స్ట్‌లో ఉంటాయి. రన్‌టైమ్ క్రెడెన్షియల్ రికార్డులను ఎన్‌క్రిప్ట్ చేయకుండా నిల్వ చేసి, స్టార్ట్ అవ్వడానికి నిరాకరించనప్పుడు, 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 కంటే ఎక్కువగా ఉంటే, కీ అమలులో లేదని అర్థం, కాబట్టి .env అనేది compose.yaml ఉన్న అదే డైరెక్టరీలో ఉందని మరియు docker compose config ఆ విలువను చూపుతుందని నిర్ధారించుకోండి. కీ సెట్ చేయబడినప్పుడు, అదే శోధన 0ని తిరిగి ఇస్తుంది, ఎందుకంటే రికార్డు AES-256-GCM (అడ్వాన్స్‌డ్ ఎన్‌క్రిప్షన్ స్టాండర్డ్, 256-బిట్ కీ, గలోయిస్/కౌంటర్ మోడ్)తో సీల్ చేయబడింది.

రీస్టోర్ తర్వాత ఏదీ డిక్రిప్ట్ అవ్వదు. ఎన్‌క్రిప్షన్ కీ మారింది లేదా పోయింది. డిజైన్ ప్రకారం, ఇది డేటా పక్కన ఎప్పుడూ వ్రాయబడదు, కాబట్టి రికవరీ మార్గం లేదు మరియు ఏ సపోర్ట్ టికెట్ సహాయపడదు. ప్రతి ప్రొవైడర్‌ను మళ్లీ కనెక్ట్ చేయండి. రన్‌టైమ్‌లో ప్రత్యేక కీ వేరియబుల్ మరియు డేటా కమాండ్ ద్వారా రొటేషన్ సపోర్ట్ చేయబడుతుంది, కాబట్టి మీరు దేనినైనా రొటేట్ చేసే ముందు ప్రస్తుత రిలీజ్ నోట్స్‌ను చదవండి.

ఏజెంట్ కేటలాగ్‌లో కనిపించే యాక్షన్ పేరుతో ఎర్రర్‌ను పొందుతుంది. డిస్కవరీ మరియు ఎగ్జిక్యూషన్ వేర్వేరు. ఒక యాక్షన్ search_actionsలో కనిపించినప్పటికీ, అది OOMOL_CONNECT_ALLOWED_ACTIONS ద్వారా, డెన్లిస్ట్ ద్వారా లేదా ఆ రన్‌టైమ్ టోకెన్ యొక్క స్వంత నిబంధనల ద్వారా తిరస్కరించబడవచ్చు.

అప్‌గ్రేడ్‌లు. వాల్యూమ్‌ను బ్యాకప్ చేయండి, ఇమేజ్ ట్యాగ్‌ను కొత్త రిలీజ్‌కు ఎడిట్ చేయండి, ఆపై docker compose pull && docker compose up -d చేయండి. మైగ్రేషన్ లైన్ కోసం docker compose logs -n 50 connectorని గమనించండి, మరియు మీరు మళ్లీ నమ్మే ముందు హెల్త్ చెక్ మరియు ఒక నిజమైన యాక్షన్‌ను మళ్లీ రన్ చేయండి. రోలింగ్ బ్యాక్ అంటే పాత ట్యాగ్‌ను తిరిగి ఉంచడం, మీరు దాన్ని పిన్ చేసినందున మాత్రమే ఇది పనిచేస్తుంది.

FAQ

Open Connectorను సెల్ఫ్-హోస్ట్ చేయడానికి నాకు పబ్లిక్ డొమైన్ అవసరమా?

API కీని ఉపయోగించే ప్రొవైడర్ల కోసం, అవసరం లేదు: 127.0.0.1 లోని గేట్‌వే సరిపోతుంది. OAuth కోసం, ఆచరణలో ఇది అవసరం. ప్రొవైడర్ బ్రౌజర్‌ను మీ కాల్‌బ్యాక్ URLకి రీడైరెక్ట్ చేస్తుంది, కాబట్టి ఆ URL పబ్లిక్ ఇంటర్నెట్ నుండి రిజాల్వ్ కావాలి, మరియు ప్రొవైడర్లు localhost వెలుపల సాధారణ http://ని అంగీకరించవు. మొదటిసారి ప్రారంభించే ముందు OOMOL_CONNECT_ORIGINని మీ https:// హోస్ట్‌నేమ్‌కు సెట్ చేయండి మరియు ప్రొవైడర్ యొక్క OAuth యాప్‌లో <origin>/oauth/callbackని రిజిస్టర్ చేయండి.

నేను Open Connector ఎన్‌క్రిప్షన్ కీని కోల్పోతే ఏమవుతుంది?

నిల్వ చేసిన క్రెడెన్షియల్స్‌ను డిక్రిప్ట్ చేయడం సాధ్యం కాదు, మరియు దీనికి రికవరీ లేదు. డేటాతో పాటు కీని ఎప్పటికీ నిల్వ చేయకూడదనే ఉద్దేశంతోనే ఇలా రూపొందించబడింది, తద్వారా డేటాబేస్ ఉన్న ఎవరూ (మీతో సహా) దానిని చదవలేరు. మీకున్న ఏకైక మార్గం కొత్త కీని సెట్ చేసి, ప్రతి ప్రొవైడర్‌ను మళ్లీ కనెక్ట్ చేయడం. కీని పాస్‌వర్డ్ మేనేజర్‌లో మరియు డేటాబేస్‌ను మీ బ్యాకప్ రొటేషన్‌లో ఉంచండి, ఎందుకంటే రీస్టోర్ చేయడానికి రెండూ అవసరం.

నా AI ఏజెంట్ ప్రొవైడర్ యాక్సెస్ టోకెన్‌ను చూడగలదా?

గేట్‌వే ద్వారా కాల్ చేసినప్పుడు చూడలేదు. ఏజెంట్ oct_తో ప్రారంభమయ్యే రన్‌టైమ్ టోకెన్‌తో అథెంటికేట్ అవుతుంది, మరియు గేట్‌వే సర్వర్‌లో అవుట్‌బౌండ్ అభ్యర్థనలోకి ప్రొవైడర్ క్రెడెన్షియల్‌ను ఇంజెక్ట్ చేసి, కేవలం ప్రతిస్పందనను మాత్రమే తిరిగి ఇస్తుంది. ఈ లక్షణాన్ని రెండు విషయాలు దెబ్బతీస్తాయి: /v1/proxy/:service ఎండ్‌పాయింట్, ఇది మీ క్రెడెన్షియల్‌తో కూడిన రా (raw) అభ్యర్థనలను ఫార్వార్డ్ చేస్తుంది మరియు దీని గ్రాంట్లు ఖాళీగా ఉండటానికి ఒక కారణం ఉంది, మరియు API కీని మీరే ఏజెంట్‌లో పేస్ట్ చేయడం, ఇది గేట్‌వేని పూర్తిగా దాటవేస్తుంది.

గేట్‌వే పబ్లిక్ ఇంటర్నెట్ నుండి అందుబాటులో ఉండాలా?

/oauth/callback మాత్రమే అందుబాటులో ఉండాలి. కంటైనర్ పోర్ట్‌ను 127.0.0.1లో పబ్లిష్ చేయండి, తద్వారా Docker యొక్క NAT రూల్స్ దానిని మీ ఫైర్‌వాల్ దాటి ఎక్స్‌పోజ్ చేయలేవు, మరియు రివర్స్ ప్రాక్సీని ముందు ఉంచండి. ఆ తర్వాత authorization హెడర్ లేకుండా ఒక యాక్షన్ కాల్‌ను పరీక్షించండి. అది విజయవంతమైతే, అథెంటికేట్ అయిన కాల్స్ మాత్రమే పనిచేసే వరకు ప్రాక్సీ వద్ద /api, /v1 మరియు /mcpలను మీ ఏజెంట్లు ఉపయోగించే అడ్రస్‌లకు పరిమితం చేయండి.

Open Connector ప్రొడక్షన్ వినియోగానికి సిద్ధంగా ఉందా?

ఇది Apache 2.0 లైసెన్స్‌తో వేగంగా అభివృద్ధి చెందుతోంది: రిపోజిటరీ 29 జూన్ 2026న కనిపించింది మరియు v1.3.3 వెర్షన్ 30 జూలై 2026న విడుదలైంది, కాబట్టి ఈ గైడ్‌లోని ప్రతి వెర్షన్ నంబర్‌ను 1 ఆగస్టు 2026 నాటి స్నాప్‌షాట్‌గా పరిగణించండి. దీనిని ఒక రిలీజ్ ట్యాగ్‌కు పిన్ చేసి రన్ చేయండి, ఎప్పుడూ latest లేదా tipలో రన్ చేయవద్దు, ప్రతి అప్‌గ్రేడ్‌కు ముందు రిలీజ్ నోట్స్ చదవండి, మరియు మీరు ఒకసారి రీస్టోర్ చేసి చూసిన వాల్యూమ్ బ్యాకప్‌ను ఉంచుకోండి. మీరు సొంతంగా కలిగి ఉన్న బాక్స్‌కు ఈ డిజైన్ సరైనది, మరియు ఇక్కడ ఉన్న రిస్క్ ఆర్కిటెక్చర్ వల్ల కాదు, వెర్షన్ మార్పుల వల్ల మాత్రమే.