Open Connector-ஐ சொந்தமாக VPS-ல் நிறுவுவது எப்படி?

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 உரிமத்தின் கீழ் உள்ளது. v1.9.4 வரையிலான releases Apache 2.0 உரிமத்திலேயே உள்ளன; v1.9.5-ல் இந்த மாற்றம் அறிமுகப்படுத்தப்பட்டது. OpenConnector-ன் செயல்பாட்டை முதன்மை மதிப்பாகக் கொண்ட ஒரு hosted அல்லது managed service-ஐ வழங்குவதற்கு OOMOL-இடமிருந்து வணிக உரிமம் (commercial license) பெற வேண்டும். இது ஒரு container-ஆக இயங்குகிறது, அதன் நிலையை ஒரே ஒரு SQLite file-ல் சேமிக்கிறது, மேலும் provider actions-ஐ HTTP மற்றும் MCP (model context protocol) வழியாக வழங்குகிறது.

இரண்டாவது integration-லேயே சிக்கல்கள் தொடங்குகின்றன. ஒவ்வொரு provider-க்கும் தனித்தனி OAuth (open authorization) flow, refresh token ஆயுட்காலம் மற்றும் scope பெயர்கள் உள்ளன. ஐந்து provider-களை ஒரு agent-ல் கைமுறையாக இணைப்பது என்பது ஐந்து redirect handlers, ஐந்து credential stores மற்றும் token காலாவதியாகும் முன் இயங்க வேண்டிய ஐந்து refresh loops-ஐ உருவாக்குவதாகும். இந்த code-ஐ கிட்டத்தட்ட யாரும் எழுதுவதில்லை. அதற்குப் பதிலாக, ஒவ்வொரு service-க்கும் ஒரு நீண்ட காலம் செல்லுபடியாகும் personal access token-ஐ உருவாக்கி, அதை agent config, environment file அல்லது prompt-லேயே பதிவிடுகிறார்கள். அந்த token-ஐ agent இயக்கும் ஒவ்வொரு tool-ஆலும் படிக்க முடியும், மேலும் அது transcript-ல் பதிவாகிறது; இதுவே AI agent-களிடமிருந்து ரகசியங்களை எவ்வாறு பாதுகாப்பது என்ற பகுதியில் விவரிக்கப்பட்டுள்ள தோல்விக்குக் காரணமாகிறது.

ஒரு 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 account-க்கு பதிலாக, நீங்கள் எளிதாக ரத்து செய்யக்கூடிய ஒரு runtime token-ஐ மட்டுமே இழப்பீர்கள்.

இதன் catalog 1,000-க்கும் மேற்பட்ட provider-களையும் 10,000-க்கும் மேற்பட்ட prebuilt actions-களையும் கொண்டிருப்பதாக விளம்பரப்படுத்துகிறது; இது அந்தத் திட்டத்தின் சொந்த புள்ளிவிவரம், இதை வெளியிலிருந்து உங்களால் சரிபார்க்க முடியாது. ஆனால், அதன் கட்டமைப்பை உங்களால் சரிபார்க்க முடியும்: ஒரு action-க்கு ஒரு HTTP endpoint, ஒரு provider-க்கு ஒரு சேமிக்கப்பட்ட இணைப்பு, ஒரு agent-க்கு ஒரு token. agent சார்ந்த இந்தத் தொழில்நுட்பம் இன்னும் புதியதாக இருப்பதாலும், tool call அல்லது MCP server போன்ற சொற்கள் இன்னும் முழுமையாக நிலைபெறாததாலும், AI agent-களை அடிப்படையிலிருந்து கற்றுக்கொள்வது எப்படி என்ற பகுதியில் உள்ள படிப்படியான வழிமுறைகள், இதுபோன்ற gateway எதிர்பார்க்கும் loop, tools மற்றும் பாதுகாப்புப் பழக்கங்களை உருவாக்க உதவும்.

ஏன் ஒரு hosted connector service-க்கு பதிலாக Open Connector-ஐ நீங்களே self-host செய்ய வேண்டும்

ஒரு hosted connector service அதே வேலையைச் செய்கிறது, மேலும் நீங்கள் இணைக்கும் ஒவ்வொரு provider-ன் refresh tokens-ஐயும் அதுவே வைத்திருக்கிறது. Google அல்லது GitHub-க்கான ஒரு refresh token என்பது உங்கள் மின்னஞ்சல் மற்றும் repositories-க்கான நீண்ட கால அணுகல் திறவுகோலாகும் (long-lived key). அவை breached செய்யப்பட்டால், அது உங்கள் கணக்கு breached செய்யப்பட்டதற்குச் சமம். Self-hosting முறையில், அந்தத் தரவுகள் அனைத்தும் நீங்கள் வாடகைக்கு எடுத்து நிர்வகிக்கும் machine-ல் உள்ள SQLite கோப்பில் சேமிக்கப்படும்; உங்கள் machine-ஐ விட்டு வெளியேறாத ஒரு key மூலம் அவை பாதுகாக்கப்படும்.

நீங்கள் தொடங்குவதற்கு முன் அதன் செலவை வெளிப்படையாகக் கணக்கிடுங்கள். இந்த VPS நீங்கள் இயக்கும் மிக முக்கியமான server-ஆக மாறும். இது ஒரு டஜன் சேவைகளுக்கான credentials-ஐ ஒரே கோப்பில் வைத்திருப்பதால், ஒரு password manager host-க்கு நீங்கள் அளிக்கும் அதே பாதுகாப்பை இதற்கும் அளிக்க வேண்டும்: 443 port-ஐ மட்டும் அனுமதிக்கும் firewall, பகிரப்பட்ட logins இல்லாமை, நீங்கள் ஏற்கனவே ஒருமுறை restore செய்து சரிபார்த்த backup, மற்றும் அது பதிலளிக்காதபோது எச்சரிக்கை செய்யும் வசதி. உங்கள் password vault-ஐ இந்த machine-ல் வைக்க நீங்கள் தயங்குவீர்கள் என்றால், connector-ஐயும் இதில் வைக்காதீர்கள்.

எந்தவொரு மென்பொருளையும் நிறுவும் முன் அதன் பதிப்பை (version) உறுதிப்படுத்தவும்

Open Connector ஒரு புதிய மென்பொருள். இந்த வழிகாட்டி, 30 July 2026 அன்று வெளியிடப்பட்ட v1.3.3 பதிப்பை, 1 August 2026-ன் நிறுவல் snapshot-ஆகப் பயன்படுத்துகிறது. இது தற்போதைய புதிய release அல்ல. Registry-யில் tip tag ஒன்றும் உள்ளது, இது main-ல் உள்ள புதிய commit-லிருந்து உருவாக்கப்பட்டது.

இது போன்ற புதிய திட்டங்களில், நகரும் tags அடிக்கடி மாறக்கூடும். இரண்டு release-களைத் தாண்டிச் செல்லும் ஒரு docker compose pull, உங்கள் agent சார்ந்திருக்கும் endpoint-ஐ மாற்றக்கூடும். அப்போது, அது ஒரு agent பிரச்சினை என்று கருதி நீங்கள் இரவு முழுவதும் பிழைதிருத்தம் (debugging) செய்ய வேண்டியிருக்கும். எனவே, image-ஐ ஒரு குறிப்பிட்ட release tag-உடன் இணைக்கவும் (pin). Release notes-ஐப் படித்த பிறகு, உங்கள் விருப்பப்படி பதிப்பை மேம்படுத்தவும் (upgrade).

உங்கள் சொந்த VPS-ல் TLS-க்கு பின்னால் Open Connector-ஐ நிறுவுதல்

Container தொடங்குவதற்கு முன் உங்களுக்குத் தேவையானவை:

• Docker Engine 28.0.0 அல்லது அதற்குப் பிந்தைய பதிப்பு, Compose plugin-உடன், Ubuntu 24.04 அல்லது அது போன்ற இயங்குதளத்தில்.
• இந்த VPS-ஐச் சுட்டிக்காட்டும் A record கொண்ட ஒரு hostname, உதாரணமாக connect.example.com.
• அந்த hostname-க்கான TLS (transport layer security) termination-ஐ ஏற்கனவே கையாளும் ஒரு reverse proxy.
• கீழே உருவாக்கப்படும் இரண்டு சீரற்ற ரகசியங்கள் (secrets).

பல Docker Compose செயலிகளுக்கான Traefik reverse proxy வழிகாட்டி proxy அமைப்பைப் பற்றி விளக்குகிறது. ஒரு செயலிக்கான முழுமையான certificate அமைப்பைப் பற்றி Docker மற்றும் HTTPS மூலம் VPS-ல் n8n நிறுவுதல் வழிகாட்டியில் காணலாம்.

முதலில் ரகசியங்களை உருவாக்கவும். Encryption key சேமிக்கப்பட்ட நற்சான்றிதழ்களைப் (credentials) பாதுகாக்கிறது. Admin token, web console மற்றும் முழு /api தளத்தையும் பாதுகாக்கிறது. இவற்றுக்கு 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

முதல்முறை தொடங்குவதற்கு முன்பே, இரண்டு மதிப்புகளையும் உங்கள் password manager-ல் நகலெடுத்துக் கொள்ளுங்கள். Encryption key-ஐ மீட்டெடுக்க வழி இல்லை, இதற்கான காரணம் கீழே உள்ள தோல்விப் பட்டியலில் கொடுக்கப்பட்டுள்ளது.

இப்போது 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 கோப்பு 3000:3000-ஐ வெளியிடுகிறது, இது host-ல் உள்ள அனைத்து interface-களையும் இணைக்கிறது. Docker அதன் published ports-ஐ NAT (network address translation) அட்டவணையில் எழுதும், இது ufw filter chain-க்கு முன்பே நடக்கும். எனவே ufw deny 3000 அந்த port-ஐ மூடாது, இது Docker ports ஏன் ufw-ஐத் தவிர்க்கின்றன என்பதில் விவரிக்கப்பட்டுள்ள சிக்கலாகும். 127.0.0.1:3000:3000 என்று குறிப்பிடுவது loopback interface-ல் மட்டுமே வெளியிடும், உங்கள் reverse proxy அதே host-லிருந்து இணைக்கப்படும். Docker Engine 28.0.0-க்கு முன், ஒரே L2 segment-ல் உள்ள host-கள் localhost-ல் வெளியிடப்பட்ட port-களை அணுக முடியும், அதனால்தான் இந்த வழிகாட்டிக்கு 28.0.0 அல்லது அதற்குப் பிந்தைய பதிப்பு தேவைப்படுகிறது.

:? ஒவ்வொரு variable-ம் அவசியம் என்பதைக் குறிக்கிறது, எனவே .env விடுபட்டிருந்தால், நற்சான்றிதழ்கள் குறியாக்கப்படாமல் (unencrypted) தொடங்குவதற்குப் பதிலாக, stack தொடங்குவதை மறுத்துவிடும். .env-ல் மதிப்புகளை வைத்திருப்பது, Docker Compose env கோப்புகள் மற்றும் ரகசியங்கள் வழிகாட்டியில் உள்ள முறையைப் பின்பற்றுவதாகும். கீழே முதல் runtime token-ஐ உருவாக்கும் வரை /v1 மற்றும் /mcp-ஐ reverse proxy-ல் தனிப்பட்டதாக வைத்திருங்கள்.

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-ஐ அச்சிட வேண்டும். 0.0.0.0:3000 என்று ஒரு வரி இருந்தால், listener அனைத்து IPv4 interface-களிலும் இணைக்கப்பட்டுள்ளது என்று அர்த்தம், ஆனால் இது இணைய அணுகலை உறுதிப்படுத்தாது: upstream firewalls அல்லது Docker-ன் DOCKER-USER chain-ல் உள்ள விதிகள் வெளிப்புற traffic-ஐத் தடுக்கலாம். Health check-ல் connection refused என்று வந்தால், container இன்னும் listen செய்யவில்லை என்று அர்த்தம், எனவே proxy-ஐத் தொடுவதற்கு முன் 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 callbacks-க்கு ஏன் சரியான origin தேவைப்படுகிறது

OOMOL_CONNECT_ORIGIN என்பது பயனர்கள் பெரும்பாலும் தவிர்க்கும் அமைப்பாகும். இதைத் தவிர்க்கும்போது, OAuth செயல்பாட்டில் பிழை ஏற்படுகிறது; இது பார்ப்பதற்கு provider-ன் மென்பொருள் பிழை போலத் தோன்றும். Runtime சூழல், அந்த origin-ஐக் கொண்டு <origin>/oauth/callback என்ற வடிவத்தில் redirect URI-ஐ உருவாக்குகிறது. இதை அமைக்கவில்லை என்றால், origin இயல்பாக http://localhost:3000 என எடுத்துக்கொள்ளப்படும். இதனால், உங்கள் OAuth app-ல் https://connect.example.com/oauth/callback என்று பதிவு செய்திருந்தாலும், runtime சூழல் http://localhost:3000/oauth/callback என்ற redirect URI-ஐ provider-க்கு அனுப்பும். இந்த இரண்டு சரங்களும் (strings) வெவ்வேறாக இருப்பதால், GitHub பின்வரும் பிழையை அளிக்கும்:

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

OAuth provider ஒரு browser-ஐ அந்த URI-க்குத் திருப்பிவிடும் (redirect), எனவே அந்த முகவரி browser-க்கு அணுகக்கூடியதாக இருக்க வேண்டும். OAuth-க்கு பொதுவான hostname கட்டாயம் தேவை என்று எந்த விதியும் இல்லை: OpenConnector, GitHub callbacks-ஐ http://localhost:3000/oauth/callback-ல் ஆவணப்படுத்துகிறது. இந்த VPS deployment ஒரு hostname மற்றும் certificate-ஐப் பயன்படுத்துவதால், browser அந்த gateway-ஐ அதன் HTTPS origin மூலம் சென்றடைகிறது. முதல்முறை தொடங்குவதற்கு முன்பே origin-ஐ அமைக்கவும், ஏனெனில் இந்த மதிப்பு தொடக்கத்தின்போதே (startup) படிக்கப்படுகிறது: .env அல்லது compose.yaml கோப்புகளைத் திருத்திய பிறகு, மாற்றங்களைச் செயல்படுத்த docker compose up -d கட்டளையை மீண்டும் இயக்கவும்.

OAuth மூலம் உங்கள் முதல் provider-ஐ இணைத்தல்

முதலில் provider தளத்தில் OAuth app-ஐ உருவாக்கவும். 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-ஐக் கொண்டிருக்கும், எனவே shell session-க்காக அதை ஒருமுறை export செய்யவும்.

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

இந்த பட்டியல் ஒவ்வொரு provider-க்கும் runtime எதிர்பார்க்கும் redirect URI-ஐக் காட்டுகிறது. உங்கள் origin மாற்றங்கள் அமலுக்கு வந்துவிட்டதா என்பதைச் சரிபார்க்க இதுவே விரைவான வழியாகும். ஒருவேளை அது இன்னும் localhost என்று காட்டினால், container பழைய மதிப்பிலேயே இயங்குகிறது என்று அர்த்தம்; இதனால் OAuth flow இறுதி கட்டத்தில் தோல்வியடையும்.

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-ஐத் திருப்பித் தரும். அதை browser-ல் திறந்து, scopes-க்கு ஒப்புதல் அளிக்கவும். பின் provider உங்களை /oauth/callback-க்கு திருப்பி அனுப்பும்; அங்கு runtime அந்த code-ஐப் பெற்று, credential-ஐச் சேமிக்கும். உங்கள் origin-ல் உள்ள web console, அதே admin token-ஐப் பயன்படுத்தி ஒரு form மூலம் இதே படிகளைச் செய்கிறது. Plain API key-ஐப் பயன்படுத்தும் providers-க்கு இவை எதுவும் தேவையில்லை: PUT /api/connections/<service> உடன் {"authType":"api_key","values":{"apiKey":"..."}}-ஐப் பயன்படுத்தி key-ஐ நேரடியாகச் சேமிக்கலாம்.

ஒவ்வொரு agent-க்கும் ஒரு runtime token வழங்குங்கள், credential-ஐ ஒருபோதும் வழங்காதீர்கள்

Agent, admin API மூலம் உருவாக்கப்பட்ட runtime token-ஐப் பயன்படுத்தி gateway-ல் அங்கீகாரம் (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"}'

இந்த response oct_-ல் தொடங்கும் ஒரு token-ஐக் கொண்டிருக்கும். ஒவ்வொரு agent-க்கும் தனித்தனியாக ஒரு token-ஐ வழங்கி, அதற்கு அந்த agent-ன் பெயரைச் சூட்டுங்கள். ஏனெனில், எந்த token என்று அடையாளம் காண முடியாத பட்சத்தில், அனைத்தையும் ரத்து செய்ய வேண்டிய சூழல் ஏற்படும். அதன் பிறகு, agent சாதாரண 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":{}}'

சரியான பதில் என்பது ஒரு envelope ஆகும்; இதில் success புலம் true என்று இருக்க வேண்டும், மேலும் provider payload data-ன் கீழ் இருக்க வேண்டும். அந்த response-ல் GitHub token எங்கும் இருக்காது. ஒரு MCP client-க்கு, அதை https://connect.example.com/mcp-ஐ நோக்கிச் சுட்டிக்காட்டுங்கள்; அதே bearer header-ஐப் பயன்படுத்துங்கள். ஒவ்வொரு API-க்கும் ஒரு tool-க்கு பதிலாக, gateway search_actions மற்றும் execute_action போன்ற discovery கருவிகளை வழங்குகிறது. இது agent-ன் tool பட்டியலைச் சிறியதாக வைத்திருக்கும். VPS-ல் MCP servers-ஐ இயக்குதல் என்ற பகுதி, அந்த இணைப்பின் client பாதியை விளக்குகிறது.

இதை முடிப்பதற்கு முன் மேலும் ஒரு சோதனையைச் செய்யுங்கள். authorization header-ஐ நீக்கிவிட்டு, அந்த action அழைப்பை மீண்டும் செய்யவும். இந்தத் திட்டத்தின் quickstart, bearer இல்லாமலேயே /v1-ஐ அழைக்கிறது. எனவே, runtime auth அமைக்கப்படாத ஒரு நிறுவல், அந்த port-ஐ அணுகக்கூடிய எவருக்கும் செயல்பாடுகளைச் செய்ய அனுமதிக்கும். உங்கள் unauthenticated அழைப்பு வெற்றி பெற்றால், இரண்டு வழிகள் உள்ளன: runtime tokens-ஐ உள்ளமைத்து, anonymous அழைப்பு இப்போது தோல்வியடைகிறது என்பதை உறுதிப்படுத்துங்கள்; அல்லது reverse proxy-ல் /api, /v1 மற்றும் /mcp ஆகியவற்றை உங்கள் agent-கள் வரும் முகவரிகளுக்கு மட்டும் கட்டுப்படுத்துங்கள். /oauth/callback என்பது அங்கீகாரத்தை (authorization) முடிக்கும் browser-ஆல் அணுகக்கூடியதாக இருக்க வேண்டும்; அது முழு இணையத்திற்கும் திறந்திருக்க வேண்டிய அவசியமில்லை.

ஏஜெண்டிற்குத் தேவையான செயல்களை மட்டும் கட்டுப்படுத்துங்கள்

ஆயிரக்கணக்கான providers-ஐக் கொண்ட ஒரு gateway-ஐ ஒரு language model-இடம் ஒப்படைப்பது, தாக்குதலுக்கு உள்ளாகக்கூடிய பரப்பை அதிகரிக்கிறது. அந்த model தான் எழுதாத உரையை வாசிக்கும்போது இந்த ஆபத்து இன்னும் கூடுகிறது. ஏனெனில், ஏஜெண்டின் இணையத் தேடல்களுக்குப் பதிலளிக்கும் உங்கள் சொந்த SearXNG instance வழங்கும் ஒரு பக்கம், ஏஜெண்டிற்கு வழங்கப்பட்டுள்ள எந்தவொரு செயலுக்கும் எதிரான கட்டளைகளைக் கொண்டிருக்கலாம். ஒரு coding agent மிகச்சிறிய மாற்றத்தை மட்டும் செய்யும் அதே கட்டுப்பாடு அதன் அனுமதிகளுக்கும் பொருந்தும்: அந்தப் பணிக்குத் தேவையான சில செயல்களை மட்டும் அனுமதியுங்கள், அதற்கு மேல் எதையும் வழங்காதீர்கள். இரண்டு கட்டுப்பாடுகள் இதைச் சுருக்குகின்றன.

OOMOL_CONNECT_ALLOWED_ACTIONS ஒரு comma-separated 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 உங்கள் credential-உடன் ஒரு raw request-ஐ provider-க்கு அனுப்புகிறது, எனவே ஒரு குறிப்பிட்ட ஏஜெண்டிற்கு அது தேவைப்பட்டால் ஒழிய அதை காலியாக விடவும்.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK இயல்பாகவே false என இருக்கும். இது, self-hosted provider இணைப்பை 169.254.169.254-ல் உள்ள cloud metadata service அல்லது அதே network-ல் உள்ள உங்கள் database போன்ற private முகவரிகளைச் சுட்டிக்காட்டுவதைத் தடுக்கிறது. இதை off நிலையிலேயே விடவும். நீங்கள் சொந்தமாக host செய்யும் provider-க்கு மட்டும் இதை on செய்யவும்.

ஒவ்வொரு டோக்கனையும் கொண்ட பெட்டியை காப்புப்பிரதி எடுத்தல்

இரண்டு விஷயங்கள் முக்கியமானவை, ஒன்று மற்றொன்று இல்லாமல் பயனற்றது. connector-data வால்யூமில் உள்ள /app/data/connect.sqlite-ல் இருக்கும் தரவுத்தளம் (database) முத்திரையிடப்பட்ட நற்சான்றிதழ்களைக் (credentials) கொண்டுள்ளது. .env-ல் உள்ள குறியாக்க விசை (encryption key) அவற்றை விடுவிக்கிறது. விசை இல்லாமல் வால்யூமை மட்டும் காப்புப்பிரதி எடுத்தால் எதையும் மீட்டெடுக்க முடியாது, அதேபோல் வால்யூம் இல்லாமல் விசையை மட்டும் வைத்திருந்தாலும் பயனில்லை. எனவே, விசையை உங்கள் கடவுச்சொல் மேலாளரிலும் (password manager), வால்யூமை உங்கள் வழக்கமான காப்புப்பிரதி சுழற்சியிலும் (backup rotation) வைத்திருக்க வேண்டும்.

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 சேர்ந்ததாகும், அதனால்தான் முதல் கட்டளை அங்கு உள்ளது: உண்மையான பெயரை மூன்றாவது கட்டளையில் உள்ளிடவும். அந்த ஆவணக் காப்பகத்தை (archive) VPS-லிருந்து restic காப்புப்பிரதிகள் மூலம் VPS-லிருந்து வெளியே அனுப்பவும். இது வெளியேறும் முன்பே குறியாக்கம் செய்யப்படுவதால் பாதுகாப்பானது, ஏனெனில் அந்த ஆவணக் காப்பகம் தான் நற்சான்றிதழ் சேமிப்பகம்.

இயக்கநேரம் (runtime) சமீபத்திய செயல்பாடுகளை தணிக்கை பதிவுகளாக (audit records) வைத்திருக்கும், இயல்பாக 5,000 பதிவுகள் வரை இருக்கும். எனவே, எந்த ஏஜென்ட் எப்போது எதை இயக்கியது என்பதை கன்சோல் மூலம் தெரிந்துகொள்ளலாம். ஒரு ஏஜென்ட் வழக்கத்திற்கு மாறாகச் செயல்படும்போது, முதலில் இந்தப் பதிவைத்தான் படிக்க வேண்டும். https://connect.example.com/health-ஐ Uptime Kuma நிலை பக்கத்துடன் இணைக்கவும். கேட்வே (gateway) பதிலளிக்காதபோது, ஏஜென்ட்கள் குழப்பமான முறையில் தோல்வியடையும். கேட்வே செயலிழந்துள்ளதை முன்கூட்டியே அறிந்துகொள்வது, ஏஜென்ட் வெளியீடுகளைப் படித்து நேரத்தை வீணாக்குவதைத் தவிர்க்க உதவும்.

எவை செயலிழக்கும் மற்றும் நீங்கள் காணும் செய்தி

redirect_uri_mismatch வழங்குநரிடம் (provider). மூலமும் (origin) பதிவுசெய்யப்பட்ட callback URL-ம் வெவ்வேறாக உள்ளன. /api/oauth/configs-ல் உள்ள துல்லியமான சரத்தை (string), வழங்குநரின் app settings-ல் உள்ளவற்றுடன் ஒப்பிடவும். இதில் https மற்றும் http ஆகியவற்றுக்கு இடையிலான வேறுபாடுகள் மற்றும் இறுதியில் உள்ள slash குறியீடு ஆகியவற்றைச் சரிபார்க்கவும்.

ஒவ்வொரு /api அழைப்பும் 401 பிழையைத் தருகிறது. admin token header விடுபட்டுள்ளது அல்லது எழுத்துப் பிழையுடன் உள்ளது. அந்த header Authorization: Bearer <token> ஆகும்; web console-ம் அதே token-ஐக் கேட்கிறது.

Container இயங்குகிறது, ஆனால் நற்சான்றுகள் (credentials) plain text-ஆக உள்ளன. OOMOL_CONNECT_ENCRYPTION_KEY container-ஐ அடையாதபோது இது நிகழ்கிறது. Runtime, நற்சான்றுகளைத் தொடங்க மறுப்பதற்குப் பதிலாக, அவற்றை encrypt செய்யாமல் சேமித்து வைக்கிறது. உங்கள் சொந்த நிறுவலிலேயே இதை உறுதிப்படுத்தலாம்: உங்களுக்குத் தெரிந்த ஒரு API key-ஐக் கொண்டு ஒரு வழங்குநரை இணைக்கவும், பின்னர் database-ல் அதைத் தேடவும்.

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 இருக்கும் அதே directory-ல் உள்ளதா என்பதையும், docker compose config அந்த மதிப்பைக் காட்டுகிறதா என்பதையும் சரிபார்க்கவும். key சரியாக அமைக்கப்பட்டிருந்தால், அதே தேடல் 0 என்ற முடிவைத் தரும். ஏனெனில், அந்தப் பதிவு AES-256-GCM (advanced encryption standard, 256-bit key, Galois/counter mode) மூலம் பாதுகாக்கப்பட்டுள்ளது.

மீட்டெடுப்புக்குப் (restore) பிறகு எதுவும் decrypt ஆகவில்லை. encryption key மாற்றப்பட்டிருக்கலாம் அல்லது தொலைந்திருக்கலாம். வடிவமைப்பின்படி, இது தரவுகளுடன் சேர்த்து எழுதப்படுவதில்லை. எனவே, இதை மீட்டெடுக்க வழியில்லை, எந்த support ticket-உம் உதவாது. ஒவ்வொரு வழங்குநரையும் மீண்டும் இணைக்கவும். ஒரு தனி key variable மற்றும் runtime-ல் உள்ள data command மூலம் rotation ஆதரிக்கப்படுகிறது. எனவே, எதையும் rotate செய்வதற்கு முன் தற்போதைய release notes-ஐப் படிக்கவும்.

Catalog-ல் உள்ள ஒரு செயலை (action) agent குறிப்பிடும்போது பிழை ஏற்படுகிறது. கண்டறிதலும் (discovery) செயல்படுத்துதலும் (execution) வெவ்வேறானவை. ஒரு செயல் search_actions-ல் தோன்றினாலும், OOMOL_CONNECT_ALLOWED_ACTIONS, denylist அல்லது அந்த runtime token-ன் சொந்த விதிகளின்படி அது நிராகரிக்கப்படலாம்.

மேம்படுத்தல்கள் (upgrades). volume-ஐ backup எடுக்கவும், image tag-ஐ புதிய release-க்கு மாற்றவும், பின்னர் docker compose pull && docker compose up -d-ஐ இயக்கவும். migration வரி உள்ளதா என docker compose logs -n 50 connector-ஐக் கவனிக்கவும். மீண்டும் நம்பகமானதாக மாற்றுவதற்கு முன், health check-ஐயும் ஒரு உண்மையான செயலையும் மீண்டும் இயக்கவும். பழைய நிலைக்குத் திரும்புவது (rolling back) என்பது பழைய tag-ஐ மீண்டும் பயன்படுத்துவதாகும்; நீங்கள் அதைத் துல்லியமாகக் குறிப்பிட்டிருந்தால் (pinned) மட்டுமே இது வேலை செய்யும்.

FAQ

Open Connector-ஐ self-host செய்ய பொதுவான domain பெயர் தேவையா?

API key பயன்படுத்தும் providers-க்கு இது தேவையில்லை: 127.0.0.1-ல் உள்ள gateway போதுமானது. OAuth-க்கும் இது கட்டாயமில்லை: GitHub-ன் local callback-ஐ http://localhost:3000/oauth/callback என OpenConnector குறிப்பிடுகிறது. அங்கீகாரத்தை (authorization) முடிக்கும் browser, அந்த callback URL-ஐ அணுகக்கூடியதாக இருக்க வேண்டும். இந்த VPS deployment-க்கு, முதல்முறை தொடங்குவதற்கு முன்பே OOMOL_CONNECT_ORIGIN-ஐ உங்கள் https:// hostname-க்கு அமைத்து, provider-ன் OAuth app-ல் <origin>/oauth/callback-ஐ பதிவு செய்யவும்.

Open Connector encryption key தொலைந்துவிட்டால் என்னவாகும்?

சேமிக்கப்பட்ட நற்சான்றிதழ்களை (credentials) decrypt செய்ய முடியாது, இதை மீட்டெடுக்கவும் வழியில்லை. தரவுகளுடன் சேர்த்து key சேமிக்கப்படுவதில்லை என்பதால், database-ஐ வைத்திருப்பவர் யாராலும் (நீங்களும் உட்பட) அதை வாசிக்க முடியாது. புதிய key-ஐ அமைத்து, ஒவ்வொரு provider-உடனும் மீண்டும் இணைப்பதே ஒரே வழி. Key-ஐ ஒரு password manager-லும், database-ஐ உங்கள் backup சுழற்சியிலும் வைத்திருக்கவும், ஏனெனில் மீட்டெடுப்பிற்கு (restore) இவை இரண்டும் தேவை.

எனது AI agent-ஆல் provider access token-ஐ பார்க்க முடியுமா?

Gateway வழியாக அழைக்கும்போது முடியாது. Agent, oct_ எனத் தொடங்கும் runtime token மூலம் அங்கீகரிக்கப்படுகிறது. Gateway, server-ல் உள்ள outbound request-ல் provider credential-ஐ இணைத்து, பதிலை (response) மட்டும் திருப்பி அனுப்பும். இரண்டு சூழல்களில் இது மாறும்: /v1/proxy/:service endpoint, இது உங்கள் credential-உடன் raw request-களை அனுப்பும் (இதன் grants காலியாக இருப்பதற்கு ஒரு காரணம் உண்டு), மற்றும் API key-ஐ நீங்களே agent-ல் பதிவிடுவது, இது gateway-ஐ முழுமையாகத் தவிர்க்கும்.

Gateway பொது இணையத்திலிருந்து அணுகக்கூடியதாக இருக்க வேண்டுமா?

அங்கீகாரத்தை முடிக்கும் browser-ஆல் OAuth callback-ஐ அணுக முடிய வேண்டும், இதற்கு முழு இணைய அணுகல் தேவையில்லை. Docker Engine 28.0.0 அல்லது அதற்குப் பிந்தைய பதிப்புகளில், default bridge networking-ஐப் பயன்படுத்தி, container port-ஐ 127.0.0.1-ல் publish செய்யவும். இது அந்த port-ஐ host-லிருந்து மட்டும் அணுகக்கூடியதாக வைத்திருக்கும், மேலும் reverse proxy-ஐ முன்னால் வைக்கவும். பழைய Docker பதிப்புகளில், ஒரே L2 segment-ல் உள்ள hosts, localhost-ல் publish செய்யப்பட்ட port-களை அணுக அனுமதித்தன. பிறகு authorization header இல்லாமல் ஒரு action call-ஐச் சோதிக்கவும். அது வெற்றி பெற்றால், அங்கீகரிக்கப்பட்ட அழைப்புகள் மட்டுமே செயல்படும் வரை, proxy-ல் /api, /v1 மற்றும் /mcp ஆகியவற்றை உங்கள் agent-கள் பயன்படுத்தும் முகவரிகளுக்கு மட்டும் கட்டுப்படுத்தவும்.

Open Connector production பயன்பாட்டிற்குத் தயாரா?

தற்போதைய releases கூடுதல் நிபந்தனைகளுடன் கூடிய மாற்றியமைக்கப்பட்ட Apache 2.0 உரிமத்தைப் பயன்படுத்துகின்றன; v1.9.4 வரையிலான releases (v1.3.3 உட்பட) Apache 2.0-விலேயே உள்ளன. OpenConnector-ன் செயல்பாட்டை முதன்மை மதிப்பாகக் கொண்ட ஒரு hosted அல்லது managed connector சேவைக்கு, தற்போதைய உரிமத்தின் கீழ் OOMOL-இடமிருந்து வணிக உரிமம் தேவை. v1.3.3 installation கட்டளைகள் 1 August 2026-ன் snapshot-ஆகவே இருக்கும், அந்த release 30 July 2026 அன்று வெளியானது. இதை எப்போதும் ஒரு release tag-உடன் இணைத்து இயக்கவும், ஒருபோதும் latest அல்லது tip-ல் இயக்க வேண்டாம். ஒவ்வொரு upgrade-க்கு முன்பும் release notes-ஐ வாசிக்கவும், ஒருமுறை restore செய்து பார்த்த volume backup-ஐ எப்போதும் வைத்திருக்கவும். உங்கள் சொந்த server-க்கு இந்த வடிவமைப்பு சரியானது, இதில் உள்ள ஆபத்து architecture-ல் இல்லை, பதிப்புகளின் மாற்றத்தில்தான் (version churn) உள்ளது.