Self-host OpenConnector with Docker

Start the runtime

You need Git and Docker with Docker Compose. Start with a no-auth Action before configuring an app account. Clone the repository and start its published image. Keep this local trial on your own machine.

git clone https://github.com/oomol-lab/open-connector.git
cd open-connector
docker compose up

Run your first Action

In another terminal, fetch the top Hacker News stories. This read-only Action does not require a provider account.

curl -s -X POST \
  http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

Run this read-only, no-auth Action against a local runtime. Add your runtime bearer token if authentication is enabled.

Connect an account

Open the local console, select a provider, and configure its credentials. OAuth providers require an OAuth app you register with that service.

Persist and protect credentials

The Docker image uses /app/data for local runtime data. Keep it on a persistent volume. Configure OOMOL_CONNECT_ENCRYPTION_KEY for stored credentials and keep the key available for recovery; consult the deployment guide before exposing the runtime.

Before exposing a runtime publicly, configure admin authentication, runtime tokens, credential encryption, and the public OAuth origin. Follow the deployment guide for production settings.

Before exposing a deployment

The project’s Compose file mounts connector-data at /app/data. Configure separate OOMOL_CONNECT_ADMIN_TOKEN and OOMOL_CONNECT_RUNTIME_TOKEN values, plus OOMOL_CONNECT_ENCRYPTION_KEY, before allowing remote access. Set the public origin and terminate HTTPS at your deployment boundary. Keep secrets out of version control.

Plan upgrades and recovery

Record the image version you deploy and back up the runtime database together with a securely stored copy of its encryption key. Test restoration in an isolated environment before upgrading. Losing the key makes encrypted records unrecoverable; removing the data volume removes the local database.

Read the result

HTTP runtime responses use success, message, data and meta. Inspect success and the Action’s output schema, not just the HTTP status. When execution metadata includes executionId, use it to find the corresponding redacted run log. The example below illustrates the envelope; it is not a live API result.

{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

If the call fails

• For an authentication failure, check the endpoint and credential type: admin access protects /api; a runtime bearer token authorizes /v1 and /mcp. A provider API key is not a runtime token.
• For a permission denial, check the Action’s required scopes, runtime Action rules and connection grants. A valid token may still be forbidden from using the selected account.
• For empty or missing results, confirm the connected account and its access to the requested resource. Successful authorization does not grant access to every workspace, channel or document.
• Inspect the error and run log before retrying. If an Action changes provider data, check whether it already completed; do not blindly repeat the request.