Jihost Open Connector kwa AI agents bila SaaS token

Open Connector hufanya nini kwa AI agent

Kujihost Open Connector huweka auth gateway moja kati ya AI agents zako na kila software as a service (SaaS) API wanayoiita, hivyo agent haihifadhi provider token kamwe. Ni gateway ya open source kutoka OOMOL Lab, yenye leseni ya Apache 2.0. Huendeshwa kama container moja, huhifadhi state yake katika SQLite file moja, na hutoa provider actions kupitia HTTP na MCP (model context protocol).

Tatizo huanza kwenye integration ya pili. Kila provider ina OAuth (open authorization) flow yake, muda wake wa kuishi wa refresh token, na majina yake ya scope. Kuunganisha providers watano kwenye agent kwa mkono kunamaanisha redirect handlers watano, credential stores watano, na refresh loops watano zinazopaswa kuendeshwa kabla token haijaisha muda. Karibu hakuna mtu anayeandika code hiyo. Badala yake, hutengeneza personal access token moja ya muda mrefu kwa kila service na kuiweka kwenye agent config, environment file, au prompt yenyewe. Kisha kila tool inayotekelezwa na agent inaweza kusoma token hiyo, nayo huingia kwenye transcript. Hilo ndilo tatizo linaloelezwa na kuweka secrets nje ya AI agents.

Auth gateway hugawanya credential katika sehemu mbili. Gateway huhifadhi provider credential na huendesha OAuth flow. Agent hupata runtime token ambayo ni halali dhidi ya gateway pekee. Agent inapoiita action, gateway hupakia credential iliyohifadhiwa, huiingiza kwenye outbound request upande wa server, na kurudisha response body pekee. Agent haipokei provider access token kamwe. Kwa hiyo, transcript ya agent ikivuja, gharama yake ni runtime token moja inayoweza kufutwa, badala ya akaunti yako ya GitHub.

Catalog inaonyesha zaidi ya providers 1,000 na actions 10,000 zilizotengenezwa tayari. Hiyo ni takwimu ya mradi wenyewe, na si jambo unaloweza kuthibitisha kutoka nje. Unachoweza kuthibitisha ni muundo wake: HTTP endpoint moja kwa kila action, connection moja iliyohifadhiwa kwa kila provider, na token moja kwa kila agent. Ikiwa upande wa agent bado ni mpya kwako na istilahi kama tool call au MCP server bado hazijawa thabiti, njia ya hatua kwa hatua katika jinsi ya kujifunza AI agents kuanzia mwanzo hujenga loop, tools na mazoea ya usalama ambayo gateway kama hii hudhani tayari unayo.

Kwa nini ujipangie mwenyewe Open Connector badala ya kutumia huduma ya connector inayopangishwa

Huduma ya connector inayopangishwa hufanya kazi hiyo hiyo, na huhifadhi refresh tokens za kila provider unayoiunganisha nayo. Refresh token ya Google au GitHub ni key ya muda mrefu ya kufikia barua pepe na repositories zako, na kwa kawaida hubaki halali hata baada ya kubadilisha password. Ikivunjwa kiusalama, nawe unakuwa umeathirika. Kujipangia mwenyewe huhamisha rekodi hizo kwenye SQLite iliyo kwenye mashine unayoikodisha na kuisimamia, ikiwa imefungwa kwa key ambayo haiondoki kwenye mashine yako.

Taja gharama hiyo waziwazi kabla ya kuanza. VPS hii itakuwa seva yenye thamani kubwa zaidi unayoendesha. Inahifadhi credentials zinazotumika za huduma kadhaa katika faili moja, kwa hiyo inahitaji ulinzi unaoupa host ya password manager: firewall inayofungua 443 pekee, hakuna shared logins, backup ambayo umeiwahi kurejesha kwa mafanikio, na alert inapotosa kujibu. Ikiwa huwezi kuweka password vault yako kwenye mashine hii, usiweke connector humo pia.

Funga toleo mahususi kabla ya kusakinisha chochote

Open Connector ni mpya. Repository ilionekana kwa mara ya kwanza tarehe 29 June 2026, na kufikia 1 August 2026 toleo jipya zaidi lenye tag ni v1.3.3, lililotolewa tarehe 30 July 2026 na pia lenye tag ya latest. Registry pia huchapisha tag ya tip, iliyoundwa kutoka kwenye commit mpya zaidi kwenye main.

Kwenye mradi mpya kiasi hiki, tag zinazobadilika hubadilika mara kwa mara. docker compose pull inayoruka matoleo mawili inaweza kubadilisha endpoint ambayo agent yako inategemea, na utatumia jioni nzima kuichunguza kana kwamba ni tatizo la agent. Funga image kwenye tag ya toleo, kisha uboreshe unapoamua kufanya hivyo baada ya kusoma maelezo ya toleo.

Weka Open Connector nyuma ya TLS kwenye VPS yako

Kabla ya container kuanza, unahitaji:

• Docker yenye Compose plugin, kwenye Ubuntu 24.04 au mfumo unaokaribiana nayo
• hostname ambayo A record yake inaelekeza kwenye VPS hii, kwa mfano connect.example.com
• reverse proxy ambayo tayari inafanya TLS termination (transport layer security) kwa hostname hiyo
• secrets mbili za nasibu, zitakazotengenezwa hapa chini

Mwongozo wa Traefik reverse proxy kwa programu nyingi za Docker Compose unaeleza upande wa proxy. Usanidi huo wa certificate, kuanzia mwanzo hadi mwisho kwa programu moja, unapatikana katika mwongozo wa n8n kwenye VPS yenye Docker na HTTPS.

Tengeneza secrets kwanza. Encryption key hufunga credentials zilizohifadhiwa. Admin token hulinda web console na surface yote ya /api. Hakuna kati yake yenye thamani ya default, na runtime huanza bila matatizo hata ikiwa hazipo.

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

Nakili values zote mbili kwenye password manager yako sasa, kabla ya kuanza kwa mara ya kwanza. Encryption key haina njia ya kurejeshwa, na sababu imeelezwa katika orodha ya failures hapa chini.

Sasa compose.yaml. Inatofautiana na mfano wa upstream katika sehemu mbili, na zote ni muhimu.

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:

Mabadiliko ya kwanza ni tag iliyowekwa bayana badala ya latest. La pili ni port. File ya upstream huchapisha 3000:3000, ambayo hufunga kila interface kwenye host. Docker huandika ports zilizochapishwa kwenye jedwali la NAT (network address translation) kabla packet haijafikia ufw filter chain, kwa hiyo ufw deny 3000 haifungi port hiyo. Hii ndiyo trap iliyoelezwa katika kwa nini Docker ports hupita ufw. Kuandika 127.0.0.1:3000:3000 huchapisha kwenye loopback interface pekee, na reverse proxy yako huunganisha kutoka kwenye host hiyo hiyo.

:? huweka kila variable kuwa ya lazima, kwa hiyo stack hukataa kuanza wakati .env haipo badala ya kuanza ikiwa credentials hazijasimbwa kwa encryption. Kuhifadhi values katika .env badala ya compose file ndiyo pattern iliyo katika Docker Compose env files na 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 hujibu { "ok": true } mara runtime inapoanza. ss lazima ichapishe 127.0.0.1:3000. Mstari unaosomeka 0.0.0.0:3000 unamaanisha port mapping bado ni ile ya upstream, na gateway inajibu Internet nzima moja kwa moja. Ikiwa health check inarudisha connection refused, container bado haisikilizi. Kwa hiyo soma logs kabla ya kugusa proxy.

    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"

Kwa nini OAuth inakulazimisha uwe na hostname halisi

OOMOL_CONNECT_ORIGIN ni setting ambayo watu wengi huruka, na kuiacha husababisha OAuth ishindwe kwa njia inayoonekana kama bug ya provider. Runtime huunda redirect URI kutoka kwenye origin hiyo, kwa muundo wa <origin>/oauth/callback. Ikiwa haijawekwa, origin huwa http://localhost:3000 kwa chaguo-msingi, hivyo runtime humtumia provider redirect URI ya http://localhost:3000/oauth/callback, ilhali OAuth app yako imesajili https://connect.example.com/oauth/callback. Strings hizo mbili zinatofautiana, kwa hiyo GitHub hujibu:

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

OAuth provider humrejesha browser kwenye URI hiyo. Hiyo inamaanisha lazima iwe anwani inayoweza kufikiwa na ulimwengu wa nje, na providers hukataa http:// isiyo na encryption kwa kila kitu isipokuwa localhost. Hiyo ndiyo sababu kamili deployment hii inahitaji hostname na certificate. Weka origin kabla ya kuwasha kwa mara ya kwanza, kwa sababu value husomwa wakati wa startup: baada ya kuhariri .env au compose.yaml, endesha docker compose up -d tena ili kuitumia.

Unganisha provider wako wa kwanza kupitia OAuth

Kwanza, unda OAuth app kwenye provider. Kwenye GitHub, fuata Settings, kisha Developer settings, kisha OAuth Apps, halafu New OAuth App. Weka authorization callback URL iwe https://connect.example.com/oauth/callback. Hifadhi client ID na client secret.

Kila ombi la /api hubeba admin token, kwa hiyo i-export mara moja kwa session ya shell.

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

Orodha hiyo inaonyesha redirect URI ambayo runtime inatarajia kwa kila provider. Hii ndiyo njia ya haraka zaidi ya kuthibitisha kuwa origin yako imetumika. Ikiwa bado inaonyesha localhost, container inaendesha kwa value ya zamani na OAuth flow itashindwa kwenye hatua ya mwisho.

Hifadhi client credentials, kisha uanzishe 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"}'

Ombi la pili linarudisha authorizationUrl. Ifungue kwenye browser, kubali scopes, na provider itairudisha browser kwenye /oauth/callback, ambako runtime hubadilisha code na kuhifadhi credential. Web console kwenye origin yako hupitia hatua hizo hizo kwa kutumia form, chini ya admin token hiyo hiyo. Providers wanaotumia API key ya kawaida huruka hatua hizi zote: PUT /api/connections/<service> kwa {"authType":"api_key","values":{"apiKey":"..."}} huhifadhi key moja kwa moja.

Mpe kila agent tokeni ya wakati wa kuendesha, kamwe si credential

Agent hujithibitisha kwa gateway kwa kutumia tokeni ya wakati wa kuendesha, ambayo admin API huitengeneza.

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"}'

Jibu hubeba tokeni inayoanza na oct_. Toa tokeni moja kwa kila agent na ipe jina la agent hiyo, kwa sababu kubatilisha tokeni usiyoweza kuitambua kunamaanisha kubatilisha zote. Kisha agent huita actions kupitia HTTP ya kawaida.

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":{}}'

Jibu lenye afya ni envelope ambayo field yake ya success ni true, huku payload ya provider ikiwa chini ya data. Tokeni ya GitHub haipo popote katika jibu hilo. Kwa MCP client, iielekeze kwenye https://connect.example.com/mcp ukiwa na bearer header hiyo hiyo, na gateway itoe zana za discovery kama search_actions na execute_action badala ya zana moja kwa kila API. Hii huweka orodha ya zana za agent ikiwa ndogo. Kuendesha MCP servers kwenye VPS inaeleza upande wa client wa usanidi huo.

Fanya ukaguzi mmoja zaidi kabla ya kuita kazi hii imekamilika. Rudia action call baada ya kufuta header ya authorization. Quickstart ya mradi wenyewe huita /v1 bila bearer yoyote, kwa hiyo installation ambayo haijasanidiwa runtime auth itatekeleza actions kwa mtu yeyote anayeweza kufikia port hiyo. Ikiwa call yako bila authentication itafaulu, una njia mbili za kurekebisha hali hii: sanidi runtime tokens na uthibitishe kwamba call isiyo na authentication sasa inakataliwa, au zuia /api, /v1 na /mcp kwenye reverse proxy ili zikubali tu addresses ambazo agents wako hutoka. Ni /oauth/callback pekee inayopaswa kubaki wazi kwa umma, kwa sababu hiyo ndiyo njia pekee inayohitajiwa na browser redirect ya provider.

Punguza orodha ya vitendo hadi vile wakala anavyohitaji

Gateway yenye providers elfu moja nyuma yake ina sehemu kubwa ya mashambulizi unapoiunganisha na language model. Sehemu hiyo huwa kubwa zaidi model inapoanza kusoma maandishi ambayo haikuandika, kwa sababu ukurasa unaorejeshwa na SearXNG instance yako yenyewe inayojibu utafutaji wa wavuti wa wakala unaweza kuwa na maagizo yanayolenga vitendo vyovyote ambavyo wakala inaruhusiwa kufanya. Udhibiti huohuo unaomfanya coding agent afanye mabadiliko madogo zaidi yanayotosha unapaswa kutumika kwenye permissions zake: ruhusu vitendo vichache ambavyo kazi inahitaji, na usiruhusu vingine. Controls mbili hupunguza wigo huo.

OOMOL_CONNECT_ALLOWED_ACTIONS hupokea allowlist iliyotenganishwa kwa koma na inaelewa service.* na *. OOMOL_CONNECT_BLOCKED_ACTIONS ni denylist, na denylist huwa na kipaumbele. Kuweka allowlist kuwa github.get_current_user,github.list_issues kunamaanisha kila action nyingine inakataliwa bila kujali wakala anaomba nini. Hii ndiyo tofauti kati ya kosa na tukio la usalama. Runtime tokens huwa na action rules zao juu ya rules za jumla, na orodha yao ya allowedProxies huanza ikiwa tupu. Kwa hiyo, POST /v1/proxy/:service inakataliwa hadi uiruhusu. Proxy endpoint hiyo hupeleka raw request kwa provider ikiwa na credential yako. Iache ikiwa tupu isipokuwa agent mmoja mahususi anaihitaji.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK huwa false kwa chaguo-msingi. Hii huzuia muunganisho wa self-hosted provider kuelekezwa kwenye anwani ya faragha kama cloud metadata service iliyo kwenye 169.254.169.254, au database yako iliyo kwenye network hiyo hiyo. Iache ikiwa imezimwa. Iwashe tu kwa provider unayohost mwenyewe.

Hifadhi nakala ya seva inayohifadhi tokeni zote

Mambo mawili ni muhimu, na kila moja haliwezi kutumika bila jingine. Database iliyo kwenye /app/data/connect.sqlite ndani ya volume ya connector-data huhifadhi credentials zilizofungwa kwa usimbaji. Key ya usimbaji iliyo kwenye .env huzifungua. Backup ya volume bila key haiwezi kurejesha chochote, na key bila volume haiwezi kurejesha chochote. Kwa hiyo, weka key kwenye password manager yako, na ujumuishe volume katika mzunguko wako wa kawaida wa backup.

Simamisha container unapokopi faili ya SQLite, kwa sababu nakala inayochukuliwa wakati wa uandishi inaweza kurejeshwa ikiwa database imeharibika.

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

Jina la volume ni directory ya project yako pamoja na _connector-data. Ndiyo sababu command ya kwanza ipo hapo: bandika jina halisi kwenye command ya tatu. Tuma archive nje ya VPS kwa kutumia backups za restic kutoka VPS, ambayo huisimba kabla haijaondoka, kwa sababu archive hiyo ndiyo credential store.

Runtime huhifadhi recent action runs kama audit records, 5,000 kwa chaguo-msingi. Hivyo, console inaweza kukuonyesha agent gani iliendesha kitendo gani na wakati gani. Log hiyo ndiyo kitu cha kwanza kusoma agent inapofanya kazi kwa njia isiyo ya kawaida. Elekeza status page ya Uptime Kuma kwenye https://connect.example.com/health pia. Gateway inapoacha kujibu, agents hushindwa kwa njia zinazochanganya. Kujua kwamba gateway iko chini kunaweza kuokoa saa moja ya kusoma agent output.

Kinachoharibika, na ujumbe utakaoona

redirect_uri_mismatch kwa mtoa huduma. Origin na URL ya callback iliyosajiliwa hazilingani. Linganisha mfuatano kamili kutoka /api/oauth/configs na mipangilio ya programu kwa mtoa huduma, ukijumuisha https dhidi ya http pamoja na slash yoyote ya mwisho.

Kila mwito wa /api unarudisha 401. Kichwa cha tokeni ya msimamizi hakipo au kimeandikwa vibaya. Kichwa hicho ni Authorization: Bearer <token>, na web console inaomba tokeni hiyo hiyo.

Container inaendelea, na credentials ziko kwenye plain text. Hili hutokea wakati OOMOL_CONNECT_ENCRYPTION_KEY haifiki kwenye container, kwa sababu runtime huhifadhi rekodi za credentials bila encryption badala ya kukataa kuanza. Thibitisha hili kwenye installation yako mwenyewe: unganisha provider kwa kutumia API key unayoweza kuitambua, kisha itafute kwenye database.

docker compose cp connector:/app/data/connect.sqlite /tmp/connect.sqlite
grep -c 'github_pat_' /tmp/connect.sqlite
shred -u /tmp/connect.sqlite

Hesabu iliyo juu ya 0 inamaanisha key haitumiki, kwa hiyo hakikisha .env iko kwenye directory moja na compose.yaml na kwamba docker compose config inaonyesha value hiyo. Key ikiwekwa, utafutaji huohuo hurudisha 0, kwa sababu rekodi imefungwa kwa AES-256-GCM (advanced encryption standard, key ya bits 256, Galois/counter mode).

Hakuna kinachoweza kufanya decryption baada ya restore. Encryption key imebadilika au imepotea. Haiandikwi kamwe karibu na data, kwa muundo wa mfumo, kwa hiyo hakuna njia ya recovery wala support ticket inayoweza kusaidia. Unganisha tena kila provider. Rotation inatumia variable tofauti ya key na data command ndani ya runtime, kwa hiyo soma release notes za release ya sasa kabla ya kufanya rotation yoyote.

Agent inapata error inayotaja action ambayo inaweza kuona kwenye catalog. Discovery na execution ni hatua tofauti. Action inaweza kuonekana kwenye search_actions na bado ikakataliwa na OOMOL_CONNECT_ALLOWED_ACTIONS, na denylist, au na rules za tokeni hiyo ya runtime.

Upgrades. Fanya backup ya volume, badilisha image tag iwe release mpya, kisha docker compose pull && docker compose up -d. Monitor docker compose logs -n 50 connector uone mstari wa migration, halafu endesha tena health check na action moja halisi kabla ya kuanza kuiamini tena. Kurudisha toleo la zamani kunamaanisha kuweka tena tag ya zamani, jambo linalowezekana kwa sababu uliipin.

FAQ

Je, ninahitaji domain ya umma ili kujiendeshea Open Connector?

Kwa watoa huduma wanaotumia API key, hapana: gateway kwenye 127.0.0.1 inatosha. Kwa OAuth, kwa vitendo ndiyo. Mtoa huduma humwelekeza browser kwenye callback URL yako, kwa hiyo URL hiyo lazima ipatikane kutoka public internet, na watoa huduma hukataa http:// ya kawaida nje ya localhost. Weka OOMOL_CONNECT_ORIGIN iwe hostname yako ya https:// kabla ya kuanzisha kwa mara ya kwanza, kisha usajili <origin>/oauth/callback kwenye OAuth app ya mtoa huduma.

Nini hutokea nik ipoteza encryption key ya Open Connector?

Credentials zilizohifadhiwa haziwezi kufasiriwa, na hakuna njia ya kuzirejesha. Key hiyo haihifadhiwi kamwe pamoja na data kimakusudi, kwa hiyo hakuna mtu mwenye database anayeweza kuisoma, hata wewe. Chaguo lako pekee ni kuweka key mpya na kuunganisha tena kila mtoa huduma. Hifadhi key kwenye password manager na database kwenye utaratibu wako wa backup, kwa sababu restore inahitaji vyote viwili.

Je, AI agent yangu inaweza kuona access token ya mtoa huduma?

Hapana inapopiga simu kupitia gateway. Agent hujithibitisha kwa runtime token inayoanza na oct_, na gateway huingiza credential ya mtoa huduma kwenye request inayotoka kwenye server, kisha hurudisha response pekee. Vitu viwili huvunja sifa hiyo: endpoint ya /v1/proxy/:service, ambayo hupeleka raw requests ikiwa credential yako imeambatishwa na ambayo grants zake huanza zikiwa tupu kwa sababu maalumu, na kuweka API key kwenye agent mwenyewe, jambo linaloruka gateway kabisa.

Je, gateway inapaswa kufikiwa kutoka public internet?

Ni /oauth/callback pekee inapaswa kufikiwa. Publish container port kwenye 127.0.0.1 ili sheria za Docker za NAT zisiweze kuifikisha nje ya firewall yako, kisha weka reverse proxy mbele yake. Halafu jaribu action call moja bila authorization header. Ikifaulu, zuia /api, /v1 na /mcp kwenye proxy kwa anwani zinazotumiwa na agents zako hadi calls zenye authentication ziwe ndizo pekee zinazofanya kazi.

Je, Open Connector iko tayari kutumika production?

Ina leseni ya Apache 2.0 na inaendelea kubadilika haraka: repository ilionekana tarehe 29 June 2026 na v1.3.3 ilitolewa tarehe 30 July 2026, kwa hiyo chukulia kila nambari ya version kwenye mwongozo huu kuwa snapshot ya 1 August 2026. Iendeshe ikiwa imefungwa kwenye release tag, kamwe isiwe kwenye latest au tip, soma release notes kabla ya kila upgrade, na uhifadhi volume backup ambayo umefanya restore angalau mara moja. Muundo wake unafaa kwa server unayomiliki; hatari iko kwenye mabadiliko ya version, si kwenye architecture.