Call a self-hosted runtime with OpenConnector

Use OpenConnector when your TypeScript code calls an OpenConnector runtime that you operate. Its baseUrl points to your server.

Deploy and protect the server first. The OpenConnector self-hosting guide covers Docker Compose, source, and Cloudflare Workers deployments.

Install the SDK

npm install @oomol-lab/connector

Call a local runtime

A fresh local runtime defaults to http://localhost:3000 and can be called without a runtime token until tokens are configured. Keep this no-token setup on localhost or an otherwise private network:

import { OpenConnector } from "@oomol-lab/connector";

const open = new OpenConnector();

const stories = await open.execute("hackernews.get_top_stories", {});

The namespace form uses the same action registry:

const threads = await open.gmail.search_threads({ query: "is:unread" });

Point the client at your server

Use the server origin as baseUrl. The client adds its own API path. Before making the runtime public, create a runtime token while it is still reachable only from a trusted network, then require that token from every client:

const open = new OpenConnector({
  baseUrl: "https://connect.internal.example.com",
  runtimeToken: process.env.OOMOL_CONNECT_RUNTIME_TOKEN!,
  connectionName: "work",
});

The server requires a valid oct_… token after runtime tokens exist. Keep it in the calling backend or Agent environment according to your deployment policy. Never expose a no-token runtime on a public domain or tunnel.

Inspect the runtime

await open.health();
await open.catalog.services();
await open.catalog.search("send email", { limit: 5 });
await open.apps.listByService("github");
await open.apps.authenticated(["github", "notion"]);

Use connectionName on the client or per call to select a configured account. When neither is present, the runtime uses its default connection.

Keep administration in the web console

The SDK consumes the runtime configuration. Create connections, configure OAuth clients, generate runtime tokens, and manage action policy in the OpenConnector web console.

See the TypeScript SDK reference for precise action types, proxy differences, timeouts, retries, errors, and the complete OpenConnector API.