SDK

bun add @opengeni/sdk

@opengeni/sdk is an ESM-only TypeScript client. It uses standard fetch and streams, so it runs in Node 18+, Bun, Deno, browsers, and edge runtimes.

CommonJS hosts

Load the SDK with dynamic import() inside an async function:

// opengeni.cjs
async function createOpenGeniClient() {
  const { OpenGeniClient } = await import("@opengeni/sdk");
  return new OpenGeniClient({
    baseUrl: process.env.OPENGENI_API_BASE_URL,
    apiKey: process.env.OPENGENI_API_KEY,
  });
}

module.exports = { createOpenGeniClient };

Entry points

Import	Use it for
`@opengeni/sdk`	`OpenGeniClient`: sessions, workspaces, files, tools, events, and `createSessionProxyHandler`
`@opengeni/sdk/next`	`createSessionProxyRoute` and `toNextRouteHandlers` for the App Router
`@opengeni/sdk/express`	`toNodeMiddleware` for Express, Connect, and `node:http`
`@opengeni/sdk/hono`	`toHonoHandler` for Hono
`@opengeni/sdk/session-proxy`	Server-only proxy read helpers for artifact and Site delivery
`@opengeni/sdk/chat`	The chat facade for an existing chat UI or server-side bots
`@opengeni/sdk/automations`	Deprecated. Use event sources and scheduled-task `events` on `OpenGeniClient` (background agents)
`@opengeni/sdk/organization-integration-policy`	Which integrations an organization allows
`@opengeni/sdk/usage-allowances`	Server helpers for workspace and member usage allowances
`@opengeni/sdk/session-usage-limits`	Task usage limit reads, writes and the refusal parser
`@opengeni/sdk/workspace-integrations`	Organization webhooks and credential provider; `verifyWebhookEvent` and `verifyCredentialProviderRequest` are also on the root

For the default embed, see Embed manually.

OpenGeniClient

import { OpenGeniClient } from "@opengeni/sdk";

const og = new OpenGeniClient({
  baseUrl: process.env.OPENGENI_API_BASE_URL!,
  apiKey: process.env.OPENGENI_API_KEY!,
});

const session = await og.createSession(workspaceId, {
  initialMessage: "Investigate the failing deploy on staging",
  resources: [{ kind: "repository", uri: "https://github.com/acme/app.git", ref: "main" }],
});

for await (const event of og.streamEvents(workspaceId, session.id)) {
  if (event.type === "agent.message.delta") {
    process.stdout.write((event.payload as { text: string }).text);
  }
}

og.asUser(externalUserId, { source }) returns a client that acts as one of your users. A user with no membership in the workspace is added on their first request with conversation permissions (the key needs members:manage).

Area	Highlights
Organizations and workspaces	Organization API-key create/list/get/update/delete and explicit access policies, idempotent `ensureWorkspace`, external members, workspace settings, `deleteWorkspace`
Organization sessions	`listOrganizationSessions` and `iterateOrganizationSessions` across shared workspaces
Sessions	Create with an `agent`, resources, files, Skills, tools, MCP servers, a goal, and a compute target; list, get, archive, delete
Agent settings	`updateSessionAgent` for a running session; `sessionAgentDefaults` in `updateWorkspaceSettings`; `session.agent` and `session.effectiveTools`
Input and control	`sendMessage`, `steerMessage`, queue management, `pauseSession`, `resumeSession`, `cancelSession`
Decisions	`sendApprovalDecision`, `listHumanInputRequests`, `submitHumanInputResponse`
Events	Replay by sequence, and `streamEvents` with reconnect, resume, gap backfill, and duplicate suppression
Files	Upload, attach, and download workspace files
Goals	Read, update, pause, resume, and clear a session goal
Scheduled tasks	Create, update, pause, resume, trigger, and delete schedules; list runs
Integrations	Preview and install OpenAPI and GraphQL Integrations
Connected Machines	Enrollment tokens, device-flow approval, machine discovery and metrics, active-target swap

In a chat UI, wire Stop to pauseSession. Messages sent while paused queue until resumeSession. cancelSession permanently stops the session and its children. The complete method list is in packages/sdk/README.md.

Workspace member inventory

const members = await og.listWorkspaceMembers(workspaceId);
console.log(members.length); // WorkspaceMember[]

listWorkspaceMembers() returns an array and requires workspace:read. The raw HTTP route returns { members }.

createSessionProxyHandler

createSessionProxyHandler(client, options) returns a web-standard (request: Request) => Promise<Response>. Mount it at a catch-all route such as /api/opengeni/* and render <OpenGeniChat baseUrl="/api/opengeni" /> or SessionApp. Each request calls resolve, runs as the resolved user, and stays in the resolved workspace: every Opengeni route in that workspace is forwarded, and Opengeni’s permissions decide what it may do. Outside the workspace only the bootstrap reads (workspaces, access/me, config/client) and the user’s own inbox (inbox and inbox/items/{id} limited to the workspace, inbox/settings) answer.

Option	Purpose
`resolve`	Required. Returns `{ user, tenant }`, `{ user }`, or `{ user, workspaceId }`, or a `Response` to reject
`chats`	`"private"` (default) or `"shared"`: who sees and shares chats
`authorizeMutation`	Your CSRF check for non-GET requests. Without it, cross-site (`Sec-Fetch-Site`) and form-encoded mutations are refused
`authorizeSession`	Optional product check that this user may open this session, run for its routes and for requests naming it in `x-opengeni-session-id`
`refuse`	Optional. Keeps routes closed that Opengeni would allow: return `true` for a 404 or a `Response`
`createSession`	Server-owned chat setup. The browser sends only the first message and permitted choices; you return the full request, and setup routes close
`beforeForwardMessage`	Runs before each action that starts model work, with its `delivery`, `clientEventId` and the browser’s `browserContext`. Returns `modelContext`, `browserContext` (a replacement, or `null`), `mcpCredentialUpdates`, or a `Response`
`afterForward`	Sees Opengeni’s answer to every forwarded request first, to record what your product keeps beside it; return a `Response` to answer instead
`toolServer`	Attaches your MCP endpoint to each chat with a short-lived per-user token
`modelSelection`	`false` removes per-message model choices; `true` offers end users the model picker
`visitorUploads`	`true` lets anonymous visitors (`visitor: true` from `resolve`) upload files
`editableLiveUrl`	Overrides the editor’s live socket URL the client config reports
`maxBodyBytes`	Limit for request bodies the proxy reads. Defaults to 1 MiB
`basePath`	Mount prefix. Defaults to everything before the first `/v1/`

Framework adapters

The adapters wrap any web-standard handler, including createChatHandler:

// Next.js App Router: app/api/opengeni/[...path]/route.ts
import { createSessionProxyRoute } from "@opengeni/sdk/next";
export const dynamic = "force-dynamic";
export const { GET, POST, PUT, PATCH, DELETE } = createSessionProxyRoute(og, options);

// Express / Connect / node:http
import { toNodeMiddleware } from "@opengeni/sdk/express";
app.use("/api/opengeni", toNodeMiddleware(createSessionProxyHandler(og, options)));

// Hono
import { toHonoHandler } from "@opengeni/sdk/hono";
app.all("/api/opengeni/*", toHonoHandler(createSessionProxyHandler(og, options)));

The Node middleware streams bodies and SSE, works after a body parser, and aborts when the client disconnects. Pass the Opengeni facade from @opengeni/sdk/chat so resolve can return your own ids; with a plain OpenGeniClient, resolve must return { user, workspaceId }. Don’t replace the proxy with a passthrough that forwards any path under the organization key.

Chat facade

import { Opengeni } from "@opengeni/sdk/chat";

const og = new Opengeni({ apiKey: process.env.OPENGENI_API_KEY! }); // add baseUrl when self-hosting

const chat = await og.chat({ tenant: "acme", user: "u_42", conversation: "c_9" });
const reply = await chat.send("What did we decide last time?");

API	Purpose
`chat.send(message)`	Aggregate a reply with `text`, `status`, and any pending decision
`chat.stream(message)`	Iterate text, tool activity, pending decisions, and the final reply
`chat.snapshot()`	Restore messages, unresolved decisions, and session status
`chat.respond(input)`	Continue after an approval or an answered question
`createChatHandler(og, { resolve, format })`	Serve your authenticated chat, history, and decision routes
`uiMessageStreamParts(chunks, options)`	Write a reply into your own AI SDK UI message stream
`og.client`	The full `OpenGeniClient` for the same sessions

The facade is text-only. See Keep your existing chat UI.

Compatibility

Clients and servers are compatible within the same major version. See Going to production.

Get started

Build

Concepts

Guides

Reference

Examples

Further reading

CommonJS hosts

Entry points

OpenGeniClient

Workspace member inventory

createSessionProxyHandler

Framework adapters

Chat facade

Compatibility

​CommonJS hosts

​Entry points

​OpenGeniClient

​Workspace member inventory

​createSessionProxyHandler

​Framework adapters

​Chat facade

​Compatibility

CommonJS hosts

Entry points

OpenGeniClient

Workspace member inventory

createSessionProxyHandler

Framework adapters

Chat facade

Compatibility