Open Connector ను self-host చేయడం ఎలా?

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

Open Connector ను self-host చేయడం ద్వారా మీ AI ఏజెంట్లకు మరియు అవి కాల్ చేసే ప్రతి software as a service (SaaS) API కి మధ్య ఒక auth gateway ఏర్పడుతుంది. దీనివల్ల ఏజెంట్ వద్ద ఎప్పుడూ provider token ఉండదు. ఇది OOMOL Lab వారి open source gateway, దీనికి Apache 2.0 లైసెన్స్ ఉంది. ఇది ఒకే container గా రన్ అవుతుంది, తన state ను ఒకే SQLite ఫైల్‌లో ఉంచుకుంటుంది, మరియు provider actions ను HTTP మరియు MCP (model context protocol) ద్వారా అందిస్తుంది.

రెండవ integration తోనే సమస్యలు మొదలవుతాయి. ప్రతి provider కి సొంత OAuth (open authorization) flow, refresh token lifetime, మరియు scope పేర్లు ఉంటాయి. ఐదు వేర్వేరు providers ను మాన్యువల్‌గా ఏజెంట్‌కు అనుసంధానించాలంటే, ఐదు redirect handlers, ఐదు credential stores, మరియు token గడువు ముగియకముందే రన్ అవ్వాల్సిన ఐదు refresh loops అవసరమవుతాయి. ఇలాంటి కోడ్ ఎవరూ రాయరు. బదులుగా, ప్రతి service కి ఒక long-lived personal access token సృష్టించి, దానిని ఏజెంట్ config లో, environment file లో లేదా prompt లోనే పేస్ట్ చేస్తారు. ఆ token ను ఏజెంట్ రన్ చేసే ప్రతి tool చదవగలదు, అది transcript లో కూడా కనిపిస్తుంది. దీనివల్ల కలిగే నష్టాల గురించి AI ఏజెంట్లలో రహస్యాలను భద్రపరచడం లో వివరించబడింది.

ఒక auth gateway ఈ credential ను రెండుగా విభజిస్తుంది. Gateway లో provider credential నిల్వ చేయబడుతుంది మరియు OAuth flow రన్ అవుతుంది. ఏజెంట్‌కు కేవలం gateway వద్ద మాత్రమే చెల్లుబాటు అయ్యే runtime token లభిస్తుంది. ఏజెంట్ ఒక action ని కాల్ చేసినప్పుడు, gateway నిల్వ చేసిన credential ని లోడ్ చేసి, outbound request లో server side ద్వారా ఇంజెక్ట్ చేస్తుంది, మరియు కేవలం response body ని మాత్రమే తిరిగి పంపుతుంది. ఏజెంట్‌కు provider access token ఎప్పటికీ అందదు, కాబట్టి ఒకవేళ ఏజెంట్ transcript లీక్ అయినా, మీ GitHub ఖాతాకు ప్రమాదం ఉండదు; కేవలం ఒక revocable runtime token మాత్రమే కోల్పోతారు.

ఈ ప్రాజెక్ట్ యొక్క catalog లో 1,000 కి పైగా providers మరియు 10,000 కి పైగా prebuilt actions ఉన్నాయని పేర్కొన్నారు; ఇది ప్రాజెక్ట్ వారి స్వంత గణాంకం, దీనిని బయటి నుండి ధృవీకరించడం సాధ్యం కాదు. అయితే, మీరు ధృవీకరించగలిగేది దాని నిర్మాణం: ప్రతి action కి ఒక HTTP endpoint, ప్రతి provider కి ఒక stored connection, మరియు ప్రతి ఏజెంట్‌కు ఒక token.

హోస్ట్ చేసిన కనెక్టర్ సర్వీస్‌కు బదులుగా Open Connector ను ఎందుకు self-host చేయాలి

హోస్ట్ చేసిన కనెక్టర్ సర్వీస్ కూడా ఇదే పనిని చేస్తుంది, కానీ అది మీరు కనెక్ట్ చేసే ప్రతి ప్రొవైడర్ యొక్క refresh tokens ను తన వద్దే ఉంచుకుంటుంది. Google లేదా GitHub కోసం ఉండే refresh token అనేది మీ మెయిల్ మరియు రిపోజిటరీలకు సంబంధించిన దీర్ఘకాలిక కీ (long-lived key), ఇది సాధారణంగా పాస్‌వర్డ్ మార్చిన తర్వాత కూడా పనిచేస్తుంది. వారి సర్వర్లు breached అయితే, అది మీ ఖాతా breached అయినట్లే. Self-hosting ద్వారా ఈ రికార్డులను మీరు అద్దెకు తీసుకుని, నిర్వహించే మెషీన్‌లోని SQLite ఫైల్‌లోకి తరలించవచ్చు. ఇవి మీ సర్వర్ దాటి బయటకు వెళ్లని కీతో సురక్షితంగా ఉంటాయి.

ప్రారంభించే ముందు దీనివల్ల అయ్యే ఖర్చును ఒకసారి అంచనా వేయండి. ఈ VPS మీరు నిర్వహించే సర్వర్లలో అత్యంత విలువైనదిగా మారుతుంది. ఇది ఒకే ఫైల్‌లో పన్నెండు సర్వీసులకు సంబంధించిన working credentials ను కలిగి ఉంటుంది, కాబట్టి దీనిని మీరు పాస్‌వర్డ్ మేనేజర్ హోస్ట్‌కు ఇచ్చే ప్రాధాన్యతతోనే చూడాలి: కేవలం 443 పోర్ట్‌ను మాత్రమే అనుమతించే ఫైర్‌వాల్, ఎవరితోనూ పంచుకోని లాగిన్‌లు, మీరు ఇప్పటికే ఒకసారి రీస్టోర్ చేసి పరీక్షించిన బ్యాకప్, మరియు సర్వర్ స్పందించనప్పుడు వచ్చే అలర్ట్ వంటివి తప్పనిసరి. మీ పాస్‌వర్డ్ వాల్ట్‌ను ఈ బాక్స్‌లో ఉంచడానికి మీరు ఇష్టపడకపోతే, కనెక్టర్‌ను కూడా దీనిపై ఉంచవద్దు.

ఏదైనా ఇన్‌స్టాల్ చేసే ముందు వెర్షన్‌ను పిన్ చేయండి

Open Connector కొత్త ప్రాజెక్ట్. ఈ రిపోజిటరీ 29 June 2026న ప్రారంభమైంది. 1 August 2026 నాటికి, అందుబాటులో ఉన్న సరికొత్త tagged release v1.3.3, ఇది 30 July 2026న విడుదల చేయబడింది మరియు ఇది latest ట్యాగ్‌ను కలిగి ఉంది. రిజిస్ట్రీ main లోని సరికొత్త కమిట్ నుండి రూపొందించబడిన tip ట్యాగ్‌ను కూడా ప్రచురిస్తుంది.

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

మీ స్వంత VPSలో TLS వెనుక Open Connector ను డిప్లాయ్ చేయడం

కంటైనర్ ప్రారంభం కావడానికి ముందు మీకు ఇవి అవసరం:

• Ubuntu 24.04 లేదా దానికి సమానమైన OSపై Docker మరియు Compose ప్లగిన్
• ఈ VPSకి పాయింట్ చేసే A record కలిగిన ఒక hostname, ఉదాహరణకు connect.example.com
• ఆ hostname కోసం ఇప్పటికే TLS (transport layer security) ను terminate చేస్తున్న ఒక reverse proxy
• కింద రూపొందించిన రెండు రాండమ్ సీక్రెట్స్

Traefik reverse proxy for multiple Docker Compose apps గైడ్ ప్రాక్సీ వైపు ఉన్న అంశాలను వివరిస్తుంది. ఒకే అప్లికేషన్ కోసం సర్టిఫికేట్ సెటప్ పూర్తి వివరాలు n8n on a VPS with Docker and HTTPS గైడ్‌లో ఉన్నాయి.

ముందుగా సీక్రెట్స్‌ను రూపొందించండి. ఎన్‌క్రిప్షన్ కీ నిల్వ చేయబడిన క్రెడెన్షియల్స్‌ను భద్రపరుస్తుంది. అడ్మిన్ టోకెన్ వెబ్ కన్సోల్‌ను మరియు మొత్తం /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 (network address translation) టేబుల్‌లో రాస్తుంది, కాబట్టి ufw deny 3000 ఆ పోర్ట్‌ను క్లోజ్ చేయదు. దీని గురించి why Docker ports bypass ufw లో వివరించబడింది. 127.0.0.1:3000:3000 అని రాయడం వల్ల కేవలం loopback ఇంటర్‌ఫేస్‌పై మాత్రమే పబ్లిష్ అవుతుంది, మరియు మీ రివర్స్ ప్రాక్సీ అదే హోస్ట్ నుండి కనెక్ట్ అవుతుంది.

:? ప్రతి వేరియబుల్ అవసరమని సూచిస్తుంది, కాబట్టి .env లేనప్పుడు క్రెడెన్షియల్స్ ఎన్‌క్రిప్ట్ చేయకుండా ప్రారంభం కాకుండా, స్టాక్ ప్రారంభం కావడాన్ని నిరాకరిస్తుంది. కంపోజ్ ఫైల్‌లో కాకుండా .env లో విలువలను ఉంచడం అనేది Docker Compose env files and 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

రన్‌టైమ్ సిద్ధమైన తర్వాత /health, { "ok": true } కి సమాధానం ఇస్తుంది. ss ఖచ్చితంగా 127.0.0.1:3000 అని ప్రింట్ చేయాలి. 0.0.0.0:3000 అని కనిపిస్తే, పోర్ట్ మ్యాపింగ్ ఇంకా అప్‌స్ట్రీమ్ పద్ధతిలోనే ఉందని మరియు గేట్‌వే నేరుగా ఇంటర్నెట్ మొత్తానికి సమాధానం ఇస్తోందని అర్థం. హెల్త్ చెక్ వద్ద Connection refused అని వస్తే కంటైనర్ ఇంకా వినడం లేదని అర్థం, కాబట్టి ప్రాక్సీని తాకే ముందు 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 విఫలమవుతుంది, ఇది చూడటానికి provider లో ఉన్న లోపంలా అనిపిస్తుంది. runtime ఆ origin నుండి తన redirect URI ని <origin>/oauth/callback రూపంలో నిర్మిస్తుంది. దీనిని సెట్ చేయకపోతే, origin డిఫాల్ట్‌గా http://localhost:3000 గా ఉంటుంది. కాబట్టి, మీ OAuth యాప్‌లో https://connect.example.com/oauth/callback రిజిస్టర్ అయి ఉన్నప్పటికీ, runtime ఆ provider కి http://localhost:3000/oauth/callback అనే redirect URI ని పంపుతుంది. ఈ రెండు strings వేరుగా ఉండటం వల్ల, GitHub ఇలా సమాధానమిస్తుంది:

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

OAuth provider బ్రౌజర్‌ను తిరిగి ఆ URI కి మళ్ళిస్తుంది (redirect చేస్తుంది). అంటే, అది బయటి ప్రపంచం చేరుకోగలిగే చిరునామా అయి ఉండాలి. localhost తప్ప మరేదైనా దానికి plain http:// ని provider లు తిరస్కరిస్తాయి. ఈ deployment కి hostname మరియు certificate అవసరమవ్వడానికి ఇదే ప్రధాన కారణం. మొదటిసారి start చేయడానికి ముందే origin ని సెట్ చేయండి, ఎందుకంటే ఈ విలువ startup సమయంలోనే చదవబడుతుంది: .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 కాల్ అడ్మిన్ టోకెన్‌ను కలిగి ఉంటుంది, కాబట్టి షెల్ సెషన్ కోసం దానిని ఒకసారి 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ను స్టోర్ చేసి, ఆపై ఆథరైజేషన్‌ను ప్రారంభించండి.

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 కీని ఉపయోగించే ప్రొవైడర్లు ఈ ప్రక్రియ మొత్తాన్ని దాటవేస్తాయి: {"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 ద్వారా చర్యలను (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 క్లయింట్ కోసం, దానిని అదే bearer హెడర్‌తో https://connect.example.com/mcp కి పాయింట్ చేయండి. అప్పుడు గేట్‌వే ప్రతి APIకి ఒక టూల్ కాకుండా, search_actions మరియు execute_action వంటి డిస్కవరీ టూల్స్‌ను అందిస్తుంది, ఇది ఏజెంట్ యొక్క టూల్ జాబితాను చిన్నదిగా ఉంచుతుంది. VPS పై MCP సర్వర్లను రన్ చేయడం ఈ వైరింగ్‌కు సంబంధించిన క్లయింట్ వైపు అంశాలను వివరిస్తుంది.

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

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

వెనుక వేలకొద్దీ ప్రొవైడర్లు ఉన్న గేట్‌వే, లాంగ్వేజ్ మోడల్‌కు చాలా పెద్ద ఉపరితలాన్ని అందిస్తుంది. ఆ మోడల్ తాను రాయనటువంటి టెక్స్ట్‌ను చదవడం మొదలుపెట్టినప్పుడు, ఈ ప్రమాదం మరింత పెరుగుతుంది. ఎందుకంటే ఏజెంట్ వెబ్ సెర్చ్‌లకు సమాధానమిచ్చే మీ స్వంత SearXNG instance తిరిగి ఇచ్చే పేజీలో, ఏజెంట్ కలిగి ఉన్న ఏ చర్యకైనా ఉద్దేశించిన సూచనలు ఉండవచ్చు. కోడింగ్ ఏజెంట్ పని చేసే అతి చిన్న మార్పును మాత్రమే తీసుకునేలా చేసే నియంత్రణే దాని అనుమతులకు కూడా వర్తిస్తుంది: ఆ పనికి నిజంగా అవసరమైన కొన్ని చర్యలను మాత్రమే మంజూరు చేయండి, అంతకు మించి ఏమీ వద్దు. రెండు నియంత్రణలు దీనిని పరిమితం చేస్తాయి.

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

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK డిఫాల్ట్‌గా false గా ఉంటుంది. ఇది self-hosted ప్రొవైడర్ కనెక్షన్‌ను 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 ప్రొవైడర్ వద్ద. ఆరిజిన్ మరియు రిజిస్టర్ చేయబడిన callback URL వేర్వేరుగా ఉన్నాయి. /api/oauth/configs నుండి వచ్చిన ఖచ్చితమైన స్ట్రింగ్‌ను ప్రొవైడర్ యొక్క యాప్ సెట్టింగ్‌లతో పోల్చి చూడండి, ఇందులో https మరియు http మధ్య ఉన్న తేడాలను, అలాగే చివరన ఉండే స్లాష్ (trailing slash) ను కూడా గమనించండి.

ప్రతి /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 ను గమనించండి, ఆపై హెల్త్ చెక్ మరియు ఒక నిజమైన యాక్షన్‌ను రన్ చేసి, అది నమ్మదగినదని నిర్ధారించుకోండి. రోల్ బ్యాక్ చేయడం అంటే పాత ట్యాగ్‌ను తిరిగి ఉంచడం, మీరు దాన్ని పిన్ (pin) చేసి ఉంటేనే ఇది పనిచేస్తుంది.

FAQ

Open Connector ను self-host చేయడానికి నాకు పబ్లిక్ డొమైన్ అవసరమా?

API key ఉపయోగించే ప్రొవైడర్ల కోసం, అవసరం లేదు: 127.0.0.1 పై ఉన్న గేట్‌వే సరిపోతుంది. OAuth కోసం, ఆచరణలో ఇది అవసరం. ప్రొవైడర్ బ్రౌజర్‌ను మీ callback 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 June 2026న కనిపించింది మరియు v1.3.3 వెర్షన్ 30 July 2026న విడుదలైంది, కాబట్టి ఈ గైడ్‌లోని ప్రతి వెర్షన్ నంబర్‌ను 1 August 2026 నాటి స్నాప్‌షాట్‌గా పరిగణించండి. దీనిని ఎల్లప్పుడూ ఒక రిలీజ్ ట్యాగ్‌కు పిన్ చేసి రన్ చేయండి, ఎప్పుడూ latest లేదా tip పై రన్ చేయవద్దు, ప్రతి అప్‌గ్రేడ్‌కు ముందు రిలీజ్ నోట్స్ చదవండి, మరియు మీరు ఒకసారి రీస్టోర్ చేసి పరీక్షించిన వాల్యూమ్ బ్యాకప్‌ను ఉంచుకోండి. మీ స్వంత సర్వర్ కోసం దీని డిజైన్ పటిష్టంగా ఉంది, ఇక్కడ ఉన్న రిస్క్ ఆర్కిటెక్చర్‌కు సంబంధించింది కాదు, కేవలం వెర్షన్ల మార్పులకు సంబంధించింది.