Open Connector ను సొంతంగా హోస్ట్ చేయడం ఎలా?

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

Open Connector ను self-host చేయడం ద్వారా, మీ AI agents మరియు అవి పిలిచే ప్రతి software as a service (SaaS) API మధ్య ఒక auth gateway ఏర్పడుతుంది. దీనివల్ల agent వద్ద ఎప్పుడూ 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 కాలపరిమితి, మరియు సొంత scope పేర్లు ఉంటాయి. ఐదు వేర్వేరు providers ను ఒక agent కి మాన్యువల్‌గా అనుసంధానించడం అంటే ఐదు redirect handlers, ఐదు credential stores, మరియు token గడువు ముగియకముందే రన్ అవ్వాల్సిన ఐదు refresh loops అవసరం. ఇలాంటి కోడ్ ఎవరూ రాయరు. బదులుగా, ప్రతి service కి ఒక long-lived personal access token ను సృష్టించి, దానిని agent config లో, environment file లో, లేదా prompt లోనే పేస్ట్ చేస్తారు. ఆ token ను agent రన్ చేసే ప్రతి tool చదవగలదు, మరియు అది transcript లోకి చేరుతుంది. ఇది AI agents నుండి రహస్యాలను దూరంగా ఉంచడం లో వివరించిన వైఫల్యానికి దారితీస్తుంది.

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

ఈ catalog లో 1,000 కంటే ఎక్కువ providers మరియు 10,000 ముందే సిద్ధం చేసిన actions ఉన్నాయని ప్రకటిస్తారు. ఇది ప్రాజెక్ట్ వారి స్వంత లెక్క, బయటి నుండి దీనిని ధృవీకరించడం సాధ్యం కాదు. మీరు ధృవీకరించగలిగేది దాని నిర్మాణం మాత్రమే: ప్రతి action కు ఒక HTTP endpoint, ప్రతి provider కు ఒక stored connection, మరియు ప్రతి agent కు ఒక token. ఒకవేళ agent వైపు విషయాలు ఇంకా కొత్తగా అనిపించి, tool call లేదా MCP server వంటి పదాలు ఇంకా అలవాటు కాకపోతే, AI agents ను మొదటి నుండి నేర్చుకోవడం ఎలా లోని దశలవారీ మార్గం మీకు అవసరమైన loop, tools, మరియు భద్రతా అలవాట్లను నిర్మించడంలో సహాయపడుతుంది. ఇవే ఈ gateway కి అవసరమైన ప్రాథమికాంశాలు.

Hosted connector service కు బదులుగా Open Connector ను ఎందుకు self-host చేయాలి

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

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

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

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

ఇంత కొత్త ప్రాజెక్ట్‌లో, మారుతున్న ట్యాగ్‌లు తరచుగా మారుతుంటాయి. రెండు రిలీజ్‌ల మధ్య దూసుకెళ్లే 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
• కింద రూపొందించిన రెండు యాదృచ్ఛిక రహస్యాలు (secrets)

అనేక Docker Compose అప్లికేషన్ల కోసం Traefik reverse proxy గైడ్ ప్రాక్సీ వైపు ఉన్న అంశాలను వివరిస్తుంది. ఒకే అప్లికేషన్ కోసం సర్టిఫికేట్ సెటప్ పూర్తి వివరాలు 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

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

ఇప్పుడు 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 ఆ పోర్ట్‌ను మూసివేయదు; ఇది Docker పోర్ట్‌లు ufw ని ఎందుకు దాటవేస్తాయి అనే విభాగంలో వివరించిన ఉచ్చు. 127.0.0.1:3000:3000 అని రాయడం వల్ల కేవలం loopback ఇంటర్‌ఫేస్‌పై మాత్రమే పబ్లిష్ అవుతుంది, మరియు మీ reverse proxy అదే హోస్ట్ నుండి కనెక్ట్ అవుతుంది.

:? ప్రతి వేరియబుల్ అవసరమని సూచిస్తుంది, కాబట్టి .env లేనప్పుడు స్టాక్ ప్రారంభం కాకుండా ఆగిపోతుంది; లేదంటే ఆధారాలు ఎన్‌క్రిప్ట్ చేయబడకుండానే ప్రారంభమయ్యే ప్రమాదం ఉంది. Docker Compose env ఫైళ్లు మరియు రహస్యాలు లో చెప్పినట్లుగా, విలువలను 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 అని వస్తే, కంటైనర్ ఇంకా వినడం లేదని అర్థం, కాబట్టి ప్రాక్సీని తాకే ముందు 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 గా ఉంటుంది. కాబట్టి, మీ OAuth యాప్‌లో https://connect.example.com/oauth/callback రిజిస్టర్ అయి ఉన్నప్పటికీ, రన్‌టైమ్ ప్రొవైడర్‌కు http://localhost:3000/oauth/callback అనే redirect URIని పంపుతుంది. ఈ రెండు స్ట్రింగ్‌లు వేరుగా ఉండటంతో, GitHub ఇలా సమాధానమిస్తుంది:

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

ఒక OAuth ప్రొవైడర్ బ్రౌజర్‌ను తిరిగి ఆ URIకి పంపుతుంది, అంటే అది బయటి ప్రపంచానికి అందుబాటులో ఉండే అడ్రస్ అయి ఉండాలి. localhost మినహా మరే ఇతర దానికి ప్రొవైడర్లు సాధారణ http:// ని అంగీకరించవు. ఈ డిప్లాయ్‌మెంట్‌కు hostname మరియు certificate అవసరమవ్వడానికి ఇదే ప్రధాన కారణం. మొదటిసారి ప్రారంభించే ముందే 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ని చూపుతుంది, మీ origin అమరికలు అమలయ్యాయో లేదో తనిఖీ చేయడానికి ఇది వేగవంతమైన మార్గం. ఒకవేళ అది ఇప్పటికీ 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కి పంపుతుంది, అక్కడ రన్‌టైమ్ కోడ్‌ను మార్పిడి చేసుకుని credentialను స్టోర్ చేస్తుంది. మీ origin వద్ద ఉన్న వెబ్ కన్సోల్ అదే అడ్మిన్ టోకెన్ ఉపయోగించి, ఫారమ్ ద్వారా ఇదే దశలను పూర్తి చేస్తుంది. సాధారణ 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 క్లయింట్ కోసం, దానిని అదే bearer హెడర్‌తో https://connect.example.com/mcp కి పాయింట్ చేయండి. అప్పుడు గేట్‌వే ప్రతి API కి ఒక టూల్ ఇచ్చే బదులు, search_actions మరియు execute_action వంటి డిస్కవరీ టూల్స్‌ను అందిస్తుంది. ఇది ఏజెంట్ యొక్క టూల్ జాబితాను చిన్నదిగా ఉంచుతుంది. VPS పై MCP సర్వర్లను రన్ చేయడం అనే విభాగం ఈ కనెక్షన్‌కు సంబంధించిన క్లయింట్ వైపు వివరాలను వివరిస్తుంది.

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

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

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

OOMOL_CONNECT_ALLOWED_ACTIONS అనేది కామాలతో వేరు చేయబడిన allowlist ను తీసుకుంటుంది మరియు service.* అలాగే * లను అర్థం చేసుకుంటుంది. OOMOL_CONNECT_BLOCKED_ACTIONS అనేది denylist, మరియు denylist కే ప్రాధాన్యత ఉంటుంది. allowlist ను 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 మధ్య తేడాలు మరియు చివరన ఉండే స్లాష్ (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 చేయడానికి నాకు public domain అవసరమా?

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

నేను Open Connector encryption key ని కోల్పోతే ఏమవుతుంది?

నిల్వ చేసిన credentials ను decrypt చేయడం సాధ్యం కాదు, దీనికి recovery మార్గం లేదు. భద్రతా కారణాల దృష్ట్యా ఈ key ని డేటాతో పాటు ఎప్పుడూ నిల్వ చేయరు, కాబట్టి డేటాబేస్ ఎవరి చేతిలో ఉన్నా (మీతో సహా) వారు దాన్ని చదవలేరు. మీకున్న ఏకైక మార్గం కొత్త key ని సెట్ చేసి, ప్రతి ప్రొవైడర్‌ను మళ్ళీ కనెక్ట్ చేయడం. Key ని password manager లో, డేటాబేస్‌ను మీ backup rotation లో భద్రపరచండి, ఎందుకంటే restore చేయడానికి ఈ రెండూ అవసరం.

నా AI agent ప్రొవైడర్ access token ను చూడగలదా?

Gateway ద్వారా కాల్ చేసినప్పుడు చూడలేదు. Agent అనేది oct_ తో మొదలయ్యే runtime token తో authenticate అవుతుంది. Gateway సర్వర్ వద్ద outbound request లోకి ప్రొవైడర్ credential ను పంపి, కేవలం response ను మాత్రమే తిరిగి ఇస్తుంది. ఈ భద్రతను దెబ్బతీసేవి రెండు విషయాలు: ఒకటి /v1/proxy/:service endpoint, ఇది మీ credential తో కూడిన raw requests ను ఫార్వర్డ్ చేస్తుంది (దీని grants ఖాళీగా ఉండటానికి కారణం ఇదే). రెండవది, API key ని నేరుగా agent లో పేస్ట్ చేయడం, ఇది gateway ని పూర్తిగా దాటవేస్తుంది.

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

కేవలం /oauth/callback మాత్రమే అందుబాటులో ఉండాలి. కంటైనర్ పోర్ట్‌ను 127.0.0.1 పై publish చేయండి, తద్వారా Docker యొక్క NAT నియమాలు మీ firewall దాటి దాన్ని బహిర్గతం చేయవు. దీని ముందు reverse proxy ని ఉంచండి. ఆ తర్వాత authorization header లేకుండా ఒక action call ను పరీక్షించండి. అది విజయవంతమైతే, authenticated కాల్స్ మాత్రమే పనిచేసే వరకు proxy వద్ద /api, /v1 మరియు /mcp లను మీ agents ఉపయోగించే చిరునామాలకు పరిమితం చేయండి.

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

ఇది Apache 2.0 లైసెన్స్‌తో వేగంగా అభివృద్ధి చెందుతోంది: ఈ repository 29 June 2026 న విడుదలైంది మరియు v1.3.3 అనేది 30 July 2026 న విడుదలయ్యింది. కాబట్టి ఈ గైడ్‌లోని ప్రతి version నంబర్‌ను 1 August 2026 నాటి snapshot గా పరిగణించండి. దీన్ని ఎల్లప్పుడూ release tag కి పిన్ చేసి రన్ చేయండి, ఎప్పుడూ latest లేదా tip పై రన్ చేయకండి. ప్రతి upgrade కి ముందు release notes చదవండి మరియు కనీసం ఒక్కసారైనా restore చేసి పరీక్షించిన volume backup ను ఉంచుకోండి. మీ సొంత సర్వర్ కోసం దీని డిజైన్ పటిష్టంగా ఉంది, ఇక్కడ ఉన్న రిస్క్ కేవలం version మార్పుల వల్ల వచ్చేదే తప్ప, architecture వల్ల కాదు.