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`	`OpenGeniAutomationsClient` for inbound event automations
`@opengeni/sdk/organization-integration-policy`	Which integrations an organization allows
`@opengeni/sdk/usage-allowances`	Server helpers for workspace and member usage allowances
`@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" />. Each request calls resolve, runs as the resolved user, and stays in the resolved workspace. Only the routes a conversation needs are exposed; Cancel and workspace Pause are refused.

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, only cross-site (`Sec-Fetch-Site`) mutations are refused
`authorizeSession`	Optional product check that this user may open this session
`createSession`	Allows browser-started sessions. The browser sends only `initialMessage` and `idempotencyKey`; you return the full request
`beforeForwardMessage`	Runs before each forwarded message. Returns `modelContext` and `mcpCredentialUpdates`, or a `Response` to reject
`modelSelection`	`false` removes per-message model choices and hides the model picker
`files`	`false` disables attachment routes
`sandboxFiles`	`true` enables reads inside the session working directory. Off by default
`artifacts`	`true` enables the artifact viewer and Site previews. Off by default
`sessionList`	Chat list for `OpenGeniChat`: `"mine"` (default), `"visible"`, or `false`
`archive`	`false` disables archiving chats
`maxBodyBytes`	Request body limit. 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