Open Connector ను సొంతంగా హోస్ట్ చేయడం ఎలా?
మీ AI agents కోసం Open Connector ను స్వంత VPS లో సెటప్ చేయండి. SaaS టోకెన్లను సురక్షితంగా ఉంచడానికి TLS, OAuth callbacks, మరియు SQLite బ్యాకప్ పద్ధతులను ఈ గైడ్లో చూడండి.
AI agent కోసం Open Connector చేసే పని
Open Connector ను self-hosting చేస్తే, మీ AI agents మరియు అవి ఉపయోగించే ప్రతి software as a service (SaaS) API మధ్య ఒకే auth gateway ఉంటుంది. అందువల్ల agent వద్ద ఎప్పుడూ provider token ఉండదు. ఇది OOMOL Lab అందించే source-available gateway. ప్రస్తుతం ఇది అదనపు నిబంధనలతో సవరించిన Apache 2.0 license కింద అందుబాటులో ఉంది. v1.9.4 వరకు విడుదలలు Apache 2.0 కిందే ఉన్నాయి; v1.9.5 లో ఈ మార్పు ప్రవేశపెట్టారు. OpenConnector కార్యాచరణే ప్రధాన విలువగా ఉన్న hosted లేదా managed service అందించాలంటే OOMOL నుంచి commercial license తీసుకోవాలి. ఇది ఒకే container గా నడుస్తుంది. తన state ను ఒకే SQLite file లో ఉంచుతుంది. Provider actions ను HTTP ద్వారా, అలాగే MCP (model context protocol) ద్వారా అందిస్తుంది.
రెండవ integration దగ్గర సమస్య మొదలవుతుంది. ప్రతి provider కు తనదైన OAuth (open authorization) flow, refresh token lifetime, scope names ఉంటాయి. ఐదు providers ను agent లో చేతితో అనుసంధానించాలంటే ఐదు redirect handlers, ఐదు credential stores, అలాగే token గడువు ముగియకముందు అమలవాల్సిన ఐదు refresh loops అవసరం. దాదాపు ఎవరూ ఆ code రాయరు. బదులుగా ప్రతి service కోసం ఒకటి చొప్పున దీర్ఘకాలం చెల్లే personal access token తయారు చేసి, దాన్ని agent config, environment file లేదా prompt లోనే ఉంచుతారు. ఆ token ను agent నడిపే ప్రతి tool చదవగలదు. అది transcript లో కూడా చేరుతుంది. AI agents నుంచి secrets ను దూరంగా ఉంచడం వివరించే వైఫల్యం ఇదే.
Auth gateway credential ను రెండు భాగాలుగా విభజిస్తుంది. Gateway provider credential ను భద్రపరుస్తుంది మరియు OAuth flow ను నడుపుతుంది. Agent కు gateway ఎదుట మాత్రమే చెల్లే runtime token లభిస్తుంది. Agent ఒక action ను పిలిచినప్పుడు, gateway stored credential ను లోడ్ చేసి, దాన్ని server side లో outbound request కు జతచేస్తుంది. తరువాత response body ను మాత్రమే తిరిగి ఇస్తుంది. Agent కు provider access token ఎప్పుడూ అందదు. అందువల్ల agent transcript లీక్ అయితే, మీ GitHub account ను ప్రమాదంలో పెట్టే బదులు revoke చేయగల ఒక runtime token మాత్రమే ప్రమాదంలో పడుతుంది.
Catalog లో 1,000 కంటే ఎక్కువ providers మరియు 10,000 prebuilt actions ఉన్నాయని పేర్కొంటుంది. ఇది project స్వయంగా తెలిపిన సంఖ్య మాత్రమే; బయట నుంచి దీన్ని మీరు నిర్ధారించలేరు. మీరు నిర్ధారించగలది దీని నిర్మాణం: ప్రతి action కు ఒక HTTP endpoint, ప్రతి provider కు ఒక stored connection, ప్రతి agent కు ఒక token. Agent వైపు ఉన్న ఈ అంశాలు ఇంకా కొత్తగా ఉంటే, అలాగే tool call లేదా MCP server వంటి పదాల అర్థాలు ఇంకా స్థిరపడకపోతే, AI agents ను మొదటి నుంచి నేర్చుకునే విధానం లోని దశలవారీ మార్గం loop, tools మరియు ఇలాంటి gateway మీకు ముందే తెలుసని భావించే safety అలవాట్లను క్రమంగా నేర్పుతుంది.
Hosted connector service ఉపయోగించకుండా Open Connector ను self-host చేయడానికి కారణం
Hosted connector service ఇదే పనిని చేస్తుంది. మీరు దానికి అనుసంధానించే ప్రతి provider కోసం refresh tokens ను అది నిల్వ చేస్తుంది. Google లేదా GitHub కోసం ఉన్న refresh token మీ mail మరియు repositories కు దీర్ఘకాలిక cryptographic key వంటిది. ఆ సేవ breach అయితే, మీ వ్యవస్థ కూడా breach అయినట్టే. Self-hosting ద్వారా ఆ records మీరు rent చేసి నిర్వహించే machine లోని SQLite కు తరలుతాయి. అవి మీ box ను ఎప్పుడూ విడిచిపెట్టని key తో రక్షించబడతాయి.
ప్రారంభించే ముందు ఖర్చును స్పష్టంగా అంచనా వేయండి. మీరు నడిపే servers లో ఈ VPS అత్యంత విలువైనదిగా మారుతుంది. ఒకే file లో డజను services కు సంబంధించిన పనిచేసే credentials ఉంటాయి. అందువల్ల password manager host కు ఇచ్చే స్థాయి రక్షణ దీనికీ అవసరం: 443 ను మాత్రమే బయటకు expose చేసే firewall, shared logins లేకపోవడం, మీరు కనీసం ఒకసారి restore చేసి నిర్ధారించిన backup, అలాగే ఇది స్పందించడం ఆపినప్పుడు alert. ఈ box పై మీ password vault ను ఉంచరనుకుంటే, connector ను కూడా ఇందులో ఉంచకండి.
ఇన్స్టాల్ చేయడానికి ముందు ఒక version ను pin చేయండి
Open Connector కొత్తది. ఈ guide లో 30 July 2026న విడుదలైన v1.3.3 ను 1 August 2026 నాటి installation snapshot గా pin చేశారు. ఇది ఇక తాజా release కాదు. Registry లో tip tag కూడా ఉంది. ఇది main లోని తాజా commit ఆధారంగా build చేయబడుతుంది.
ఇంత కొత్త project లో moving tags తరచుగా మారుతాయి. రెండు releases ను దాటేలా మారే docker compose pull మీ agent ఆధారపడే endpoint ను మార్చవచ్చు. అప్పుడు మీరు దాన్ని agent సమస్యగా భావించి సాయంత్రం మొత్తం debugging చేయాల్సి రావచ్చు. Image ను release tag కు pin చేయండి. Release notes చదివిన తర్వాత, మీ నిర్ణయం ప్రకారం upgrade చేయండి.
TLSతో మీ స్వంత VPSపై Open Connectorని deploy చేయండి
కంటైనర్ ప్రారంభమయ్యే ముందు మీకు ఇవి అవసరం:
- Compose pluginతో కూడిన Docker Engine 28.0.0 లేదా తదుపరి వెర్షన్, Ubuntu 24.04 లేదా దానికి సమీపమైన సిస్టమ్పై
- ఈ VPSని సూచించే A record కలిగిన hostname, ఉదాహరణకు
connect.example.com - ఆ hostname కోసం ఇప్పటికే TLS (transport layer security) termination చేసే reverse proxy
- దిగువన రూపొందించే రెండు random secrets
అనేక Docker Compose అప్లికేషన్ల కోసం Traefik reverse proxy proxy భాగాన్ని వివరిస్తుంది. ఒకే అప్లికేషన్ కోసం certificate plumbing ను ప్రారంభం నుంచి ముగింపు వరకు వివరించే మార్గదర్శకం Docker మరియు HTTPSతో VPSపై n8n లో ఉంది.
ముందుగా secrets రూపొందించండి. encryption key నిల్వ చేసిన credentials ను రక్షిస్తుంది. 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మొదటి startకు ముందు రెండు విలువలను ఇప్పుడే మీ password managerలో కాపీ చేయండి. encryption keyకి recovery మార్గం లేదు. కారణం దిగువ failure జాబితాలో వివరించబడింది.
ఇప్పుడు compose.yaml. ఇది upstream ఉదాహరణకు రెండు విషయాల్లో భిన్నంగా ఉంటుంది. రెండూ ముఖ్యమైనవే.
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 బదులుగా pinned tagను ఉపయోగించడం. రెండవది port. upstream file 3000:3000ను publish చేస్తుంది. ఇది hostలోని ప్రతి interfaceకు bind అవుతుంది. packetను ufw filter chain చూసేలోపే Docker published portsను NAT (network address translation) tableలో రాస్తుంది. అందువల్ల ufw deny 3000 ఆ portను మూసివేయదు. దీనినే Docker ports ufwను ఎలా bypass చేస్తాయో వివరించే trap అంటారు. 127.0.0.1:3000:3000 రాస్తే port loopback interfaceపై మాత్రమే publish అవుతుంది. మీ reverse proxy అదే host నుంచి connect అవుతుంది. Docker Engine 28.0.0కు ముందు, అదే L2 segmentలోని hosts localhostకు publish చేసిన portsను చేరుకోగలిగేవి. అందుకే ఈ మార్గదర్శకానికి 28.0.0 లేదా తదుపరి వెర్షన్ అవసరం.
:? ప్రతి variableను requiredగా గుర్తిస్తుంది. అందువల్ల .env లేనప్పుడు credentialsను unencryptedగా ఉంచి stack ప్రారంభించదు. విలువలను compose fileలో కాకుండా .envలో ఉంచడం Docker Compose env files మరియు secretsలోని పద్ధతి. దిగువన మొదటి 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 3000runtime ప్రారంభమైన తర్వాత /health, { "ok": true }కు సమాధానం ఇస్తుంది. ss తప్పనిసరిగా 127.0.0.1:3000ను print చేయాలి. 0.0.0.0:3000 అనే line కనిపిస్తే listener ప్రతి IPv4 interfaceకు bind అయిందని అర్థం. అయితే internet reachability నిర్ధారించబడదు. Upstream firewalls లేదా Dockerలోని DOCKER-USER chainలోని rules బాహ్య trafficను ఇంకా block చేయవచ్చు. Health checkలో connection refused కనిపిస్తే container ఇంకా listen చేయడం ప్రారంభించలేదు. కాబట్టి proxyను మార్చే ముందు logs చదవండి.
అదే service కోసం Traefik labels
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"Traefik అదే hostలో Dockerలో నడుస్తున్నప్పుడు, ఈ serviceను Traefik networkకు జత చేసి ports: blockను తొలగించండి. Traefik internal network ద్వారా containerకు చేరుతుంది. అందువల్ల hostకు ఏదీ publish చేయాల్సిన అవసరం ఉండదు. certresolver=le మీ Traefik static configలోని resolver nameతో సరిపోలాలి. లేకపోతే router certificate లేకుండానే ప్రారంభమవుతుంది.
OAuth callbacks కు సరైన origin ఎందుకు అవసరం
OOMOL_CONNECT_ORIGIN అనేది చాలామంది దాటవేసే setting. దాన్ని దాటవేస్తే OAuth లో provider లోపంలా కనిపించే సమస్య ఏర్పడుతుంది. Runtime ఆ origin ఆధారంగా <origin>/oauth/callback రూపంలో redirect URIని నిర్మిస్తుంది. Origin సెట్ చేయకపోతే, దాని default విలువ http://localhost:3000 అవుతుంది. అందువల్ల runtime provider కు http://localhost:3000/oauth/callback అనే redirect URIని పంపుతుంది, అయితే మీ OAuth appలో https://connect.example.com/oauth/callback నమోదు అయి ఉంటుంది. ఈ రెండు strings వేర్వేరుగా ఉండటంతో GitHub ఇలా సమాధానం ఇస్తుంది:
The redirect_uri MUST match the registered callback URL for this application.OAuth provider browserను ఆ URIకి తిరిగి పంపుతుంది. అందువల్ల ఆ URIని browser చేరుకోగలగాలి. OAuth కు ప్రతి సందర్భంలోనూ public hostname అవసరం లేదు: OpenConnector GitHub callbacks కోసం http://localhost:3000/oauth/callback ను document చేస్తుంది. ఈ VPS deploymentలో browser gatewayని దాని HTTPS origin ద్వారా చేరుకోవడానికి 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ని చూపుతుంది, మీ 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":"..."}}ని ఉపయోగించి కీని నేరుగా స్టోర్ చేయవచ్చు.
ప్రతి agent కు runtime token ఇవ్వండి, credential ను ఎప్పుడూ ఇవ్వవద్దు
Admin API జారీ చేసే runtime token తో agent gateway కు authentication చేస్తుంది.
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 మాత్రమే జారీ చేసి, దానికి ఆ agent పేరును పెట్టండి. ఏ token ను గుర్తించలేకపోతే, దాన్ని revoke చేయడం ద్వారా అన్ని token లను revoke చేయాల్సి వస్తుంది. ఆ తర్వాత agent సాధారణ HTTP ద్వారా actions ను 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 లో 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 tools ను అందిస్తుంది. దీనివల్ల agent tool list చిన్నగా ఉంటుంది. VPSపై MCP servers నడపడం ఈ wiring లో client భాగాన్ని వివరిస్తుంది.
దీన్ని పూర్తయిందిగా పరిగణించే ముందు మరోసారి తనిఖీ చేయండి. authorization header ను తొలగించి action call ను మళ్లీ పంపండి. Project యొక్క స్వంత quickstart, bearer లేకుండానే /v1 ను call చేస్తుంది. అందువల్ల runtime authentication configure చేయని installation లో port కు చేరగల ఎవరైనా actions ను execute చేయగలరు. Authentication లేకుండా చేసిన మీ call విజయవంతమైతే, మీకు రెండు మార్గాలు ఉన్నాయి: runtime tokens configure చేసి anonymous call ఇప్పుడు విఫలమవుతోందని నిర్ధారించండి, లేదా reverse proxy వద్ద /api, /v1 మరియు /mcp ను మీ agents వచ్చే addresses కు మాత్రమే పరిమితం చేయండి. Authorization పూర్తి చేసే browser కు /oauth/callback అందుబాటులో ఉండాలి. అయితే అది మొత్తం internet కు open గా ఉండాల్సిన అవసరం లేదు.
ఏజెంట్కు అవసరమైన పనులకు మాత్రమే పరిమితం చేయండి
వెనుక వేలకొద్దీ ప్రొవైడర్లు ఉన్న గేట్వేని లాంగ్వేజ్ మోడల్కు అందించడం అంటే, దాడికి అవకాశం ఉన్న ఉపరితలాన్ని (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 ఉపయోగించే providers కోసం అవసరం లేదు: 127.0.0.1 లో gateway ఉంటే సరిపోతుంది. OAuth కు కూడా ప్రతి సందర్భంలో అది అవసరం లేదు: GitHub యొక్క local callback ను OpenConnector http://localhost:3000/oauth/callback గా document చేస్తుంది. Authorization పూర్తి చేసే browser callback URL ను చేరుకోగలగాలి. ఈ VPS deployment కోసం, మొదటి start కు ముందు OOMOL_CONNECT_ORIGIN ను మీ https:// hostname గా సెట్ చేసి, provider యొక్క OAuth app లో <origin>/oauth/callback ను నమోదు చేయండి.
Open Connector encryption key పోతే ఏమి జరుగుతుంది?
నిల్వ చేసిన credentials ను decrypt చేయలేరు. వాటిని తిరిగి పొందే మార్గం లేదు. Data పక్కనే key ఎప్పుడూ నిల్వ కాకుండా ఉద్దేశపూర్వకంగా రూపొందించారు. అందువల్ల 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, ఇది మీ credential జతచేసిన raw requests ను forward చేస్తుంది; దాని grants ఉద్దేశపూర్వకంగా ఖాళీగా ఉంటాయి. అలాగే API key ను మీరే agent లో paste చేస్తే gateway పూర్తిగా bypass అవుతుంది.
Gateway public internet నుండి చేరుకోగలిగేలా ఉండాలా?
Authorization పూర్తి చేసే browser OAuth callback ను చేరుకోగలగాలి. అయితే మొత్తం internet నుండి access అవసరం లేదు. Docker Engine 28.0.0 లేదా ఆ తరువాతి version మరియు default bridge networking ఉపయోగిస్తే, container port ను 127.0.0.1 పై publish చేయండి. అప్పుడు published port host నుంచే చేరుకోగలిగేలా ఉంటుంది. Reverse proxy ను దాని ముందు ఉంచండి. పాత Docker releases లో అదే L2 segment పై ఉన్న hosts localhost-published ports ను చేరుకోగలిగేవి. తరువాత authorization header లేకుండా ఒక action call ను test చేయండి. అది విజయవంతమైతే, authenticated calls మాత్రమే పనిచేసే వరకు proxy వద్ద /api, /v1 మరియు /mcp ను మీ agents ఉపయోగించే addresses కు మాత్రమే పరిమితం చేయండి.
Open Connector production use కు సిద్ధంగా ఉందా?
ప్రస్తుత releases అదనపు conditions కలిగిన modified Apache 2.0 license ను ఉపయోగిస్తున్నాయి. Pinned v1.3.3 తో సహా v1.9.4 వరకు ఉన్న releases మాత్రం Apache 2.0 కిందే ఉన్నాయి. OpenConnector functionality ప్రధాన విలువగా ఉన్న hosted లేదా managed connector service కు ప్రస్తుత license ప్రకారం OOMOL నుండి commercial license అవసరం. v1.3.3 installation commands 1 August 2026 నాటి snapshot గా ఉన్నాయి. ఆ release 30 July 2026 న ship అయింది. దాన్ని release tag కు pinned గా మాత్రమే run చేయండి. latest లేదా tip పై ఎప్పుడూ run చేయవద్దు. ప్రతి upgrade ముందు release notes చదవండి. మీరు ఒకసారి restore చేసి ధృవీకరించిన volume backup ను ఉంచండి. మీరు స్వంతంగా నిర్వహించే box కు ఈ design సరైనది. Risk architecture లో కాదు; version churn లో ఉంది.