oomol-lab/open-connector: a self-hostable auth gateway between agents and 1,000+ SaaS providers

The problem: agents that need user accounts, without holding user secrets

An agent that reads a Gmail thread or writes to a Notion page needs an OAuth token for that user's account. The common shortcut is to paste the token into the agent's context or environment. That puts a long-lived credential inside a process whose prompt, logs and tool calls you do not fully control, and it makes rotation someone's manual job.

OpenConnector moves that boundary. The README describes it as an auth gateway and an alternative to Pipedream and Composio: connect user app accounts once, then expose a shared catalog of 1,000+ providers and 10,000+ prebuilt Actions to agents and applications. The stated goal is that provider secrets stay behind the runtime boundary while agents receive metadata, safe account labels and execution results.

The audience is narrow but real. Agent products that need reusable access across work apps, developer tools, data systems and communication platforms; products adding agent workflows that need stable, inspectable Action contracts; and teams that want hosted auth for speed while keeping a route to a private runtime. If your product never touches a third-party account on a user's behalf, this is infrastructure you do not need.

How the gateway routes a call: catalog, credential boundary, policy, logs

The README's flow diagram is the clearest description of the architecture. An AI agent or app reaches the OpenConnector Gateway through one of four transports: SDK, CLI, MCP or HTTP. The gateway then fans out to five internal concerns: a credential and OAuth boundary, a provider catalog, open-source Action executors, tokens with scopes and allow/block policy, and run logs. The Action executors are what finally talk to the 1,000+ providers.

The sequence the README gives is discovery first. Apps and agents discover Actions, inspect schemas and scopes, select a connection alias, and execute through the gateway. That ordering matters: the agent never needs the credential, only the Action id, the connection alias and the JSON shape. Action contracts are described as inspectable, with request and response schemas, required scopes and lazy-loaded executor source. Lazy loading means the executor code is not shipped with the catalog listing, which keeps discovery cheap.

Runtime controls are listed as connection identity, scopes, runtime tokens, action allow/block policies, temporary file transit and redacted run logs. Those are configuration surfaces, not defaults you get for free. The allow and block lists in particular are the mechanism that stops an agent from calling every Action a provider offers once a connection exists.

Running OpenConnector with Docker and calling an Action over HTTP

The repository ships a docker-compose.yml that runs the prebuilt image from GHCR rather than building from source. The comment at the top of that file notes that building from source is a separate overlay: docker compose -f docker-compose.yml -f docker-compose.build.yml up --build.

The compose file maps port 3000 and mounts a named volume at /app/data, with OOMOL_CONNECT_DATA_DIR set to the same path. Most environment variables in the file are listed with empty values, which means they are declared for you to fill in rather than given defaults. Two of them decide whether the deployment is usable at all: OOMOL_CONNECT_ENCRYPTION_KEY and OOMOL_CONNECT_ADMIN_TOKEN. The file also exposes OOMOL_CONNECT_ALLOWED_ACTIONS and OOMOL_CONNECT_BLOCKED_ACTIONS, plus OOMOL_CONNECT_ALLOWED_PROXIES and OOMOL_CONNECT_BLOCKED_PROXIES.

docker compose up

After the container starts, the gateway listens on port 3000. The README gives the MCP endpoint as http://localhost:3000/mcp, and says HTTP and OpenAPI clients call /v1/actions/* directly or read the generated /openapi.json document. The README also states that endpoint details, response envelopes, auth headers, MCP tools and Action guide examples live in docs/runtime-api.md, so that file is where you go before writing a client.

For a local checkout instead of Docker, package.json defines a start script that runs node scripts/ensure-generated.ts and then node src/server/index.ts. The postinstall hook runs the same ensure-generated script, so a fresh npm install prepares generated artifacts before you start the server.

Hosted, Cloudflare or self-hosted: three deployment paths with different owners

The README lays out three paths and is unusually direct about who carries the operational load. With OOMOL Hosted, the vendor runs managed OAuth and a hosted runtime: no deployment and no OAuth app setup. Deploying to Cloudflare puts the gateway on Workers, D1, R2 and Static Assets inside your own Cloudflare account, and you manage both the deployment and the OAuth apps. Self-hosting runs locally or on your own infrastructure with Docker or Node.js, and you manage storage and OAuth apps.

The self-hosted path supports SQLite or PostgreSQL for state and local or S3-compatible storage for file transit. The Cloudflare path is wired through wrangler.example.jsonc, with dev:cloudflare and deploy:cloudflare scripts that generate the catalog, build the web console, copy catalog assets and then call wrangler. The repository also carries a fly.toml, so Fly.io is a documented target.

The claim worth noting is that the same provider ids, Action ids, schemas and contracts hold across the open-source and commercial SaaS deployments. That is the argument for starting hosted and moving later: your agent code should not need to change when the runtime moves. It is a claim from the README, not something a reader can confirm without running both.

Where OpenConnector is the wrong tool

The self-hosted path asks you to register and maintain OAuth applications with each provider you enable. That is the cost the hosted tier exists to remove, and it does not shrink because the gateway is open source. If you enable a dozen providers, you own a dozen OAuth client registrations, their redirect URIs and their review processes.

Second, the catalog is an asset and a dependency at the same time. The README promises 1,000+ providers and 10,000+ prebuilt Actions, but an Action only helps if it matches the call you need. A provider that is present with three Actions and no coverage of the endpoint you care about leaves you writing an executor against the runtime's contract, which is a different project from installing a gateway.

Third, the README does not document rollback, backup or restore procedures for runtime state. docker-compose.yml mounts a volume at /app/data and package.json exposes runtime:migrate through node scripts/runtime-data.ts migrate, so migrations exist. What happens on a downgrade is not described. If you cannot tolerate that gap, run the hosted runtime instead of owning the database.

Finally, the project does not fit a single-provider integration. If your agent only talks to one API, an OAuth library and a token store in your own service is less machinery than a gateway, a catalog and a policy layer.

How it differs from Pipedream and Composio

The README positions OpenConnector as an alternative to Pipedream and Composio, and the difference it emphasizes is where the runtime lives. Both of those are hosted platforms: you connect accounts and call Actions, and the execution environment is theirs. OpenConnector offers the same shape of product with a self-hosted option that runs on Docker or Node.js with SQLite or PostgreSQL, on Cloudflare Workers with D1 and R2, or on Fly.io.

The second difference is the contract surface. OpenConnector exposes the same catalog through an SDK, a CLI, MCP, raw HTTP under /v1/actions/* and a generated /openapi.json document. That means an MCP-capable agent host, a TypeScript app and a custom HTTP client can all drive the same Actions without a translation layer.

The third difference is inspectability, which is the project's stated selling point: credentials, scopes, schemas, policies and run logs stay inside a runtime you can read. On a hosted competitor you accept their logging and their policy model. Here you configure OOMOL_CONNECT_ALLOWED_ACTIONS and OOMOL_CONNECT_BLOCKED_ACTIONS yourself. The trade is that you also operate the thing.

Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-08-20, the same date as the v1.4.0 release. Before that, v1.3.5 landed on 2026-08-07 and v1.3.4 on 2026-08-03. package.json declares version 1.5.0, which is ahead of the most recent published release in the repository's release list, so the version string in the source tree and the release tag do not line up and you should check which one a given artifact corresponds to.

The upgrade surface is mostly generated code. The typecheck script runs generate:registry before type checking, and the Cloudflare scripts run generate:catalog. Because the provider registry and catalog are generated, pulling a new version can change the catalog contents along with the code, and the runtime:migrate script is there for the data side. There is no documented downgrade path.

The project is licensed Apache-2.0. That permits commercial use and modification, and it includes a patent grant and a NOTICE.md file in the repository. It does not settle questions specific to your situation, such as whether the provider names and trademarks you display require separate agreements; the README states that provider names and trademarks belong to their respective owners and are used only for identification and interoperability. Get your own advice on that point rather than treating the licence as the whole answer.

Editorial conclusion

Adopt OpenConnector if your agents need durable access to the tools users already have and you are not willing to hand provider credentials to the agent process. Skip it if you only need one or two providers, or if you cannot operate the OAuth apps and storage the self-hosted path requires. Before committing, verify your target providers exist in the catalog, decide between the hosted runtime and Docker or Cloudflare, and confirm that OOMOL_CONNECT_ENCRYPTION_KEY and the admin token are set the way your deployment expects.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes