@kortix/sdk

The single, opinionated data layer for the Kortix agent platform. One typed client wraps both the Kortix REST API and the agent runtime so a host app — web, mobile, reference — imports only @kortix/sdk and never @opencode-ai/sdk directly. (The no-raw-backendApi/authenticatedFetch rule below is the target state, not yet fully true of apps/web — see Rules of the road.)

Philosophy: one Kortix token, one client, every action a method. Keys never leave the server; mutations own their side-effects there; the host states intent.

📖 Full documentation: kortix.com/docs/sdk — getting started, the full client, sessions, React hooks, and the subpath modules. The REST API has an auto-generated reference at api.kortix.com/v1/docs.

Install

npm install @kortix/sdk

import { createKortix } from "@kortix/sdk";

const kortix = createKortix({
  backendUrl: "https://api.kortix.com/v1",
  getToken,
});
await kortix.projects.list();

Call external systems through Connectors

Use one six-method data plane for every Connector provider. A user token binds the project explicitly. An agent-minted session token already carries its project scope, so it can use the top-level fallback.

const connectors = projectId
  ? kortix.project(projectId).connectors
  : kortix.connectors;

await connectors.catalog();
await connectors.tools();
await connectors.search('send email');
await connectors.describe('gmail.send_email');
await connectors.call('gmail.send_email', { to, subject, body });
await connectors.uploadAttachment(bytes, {
  filename: 'invoice.pdf',
  contentType: 'application/pdf',
});

A Connector defines callable tools. A Connection stores one authorization for that Connector. Credentials remain server-side and never enter the sandbox.

No bundler, no framework

The published package ships a browser IIFE bundle alongside its ESM dist/ — no build step required:

<script src="https://unpkg.com/@kortix/sdk"></script>
<script>
  const kortix = Kortix.createKortix({ backendUrl, getToken });
</script>

CORS: a <script> page calls the API from its own origin, so that origin must be in the API's CORS allowlist. Kortix's own domains and localhost:3000/3010 are allowed out of the box; any third-party origin (or a local page on another port) needs adding via the API's CORS_ALLOWED_ORIGINS — otherwise the browser blocks the request before it leaves the page.

Entry points

@kortix/sdk is the canonical entry — everything framework-free lives there. Three others exist, each for a reason that fits in one sentence:

| Entry | Why it can't live at root | | ------------------------ | --------------------------- | | @kortix/sdk/react | React is a peer dependency | | @kortix/sdk/server | imports node:async_hooks | | @kortix/sdk/internal/* | unsupported, outside semver |

Older subpaths (@kortix/sdk/projects-client, /turns, …) still work and are @deprecated. Import from the root instead — see API-MAP.md's Stability table for the full list (20 of them).

React Native / Expo: REST works. Streaming does not — RN's fetch has no response.body. Use createHttpSessionSyncController for bounded history synchronization. Keep the platform-specific event transport for live events.

Quick start

import { createKortix } from "@kortix/sdk";

const kortix = createKortix({
  backendUrl: "https://api.kortix.com/v1",
  getToken: () =>
    supabase.auth
      .getSession()
      .then((s) => s.data.session?.access_token ?? null),
});

// Projects
const projects = await kortix.projects.list();
const detail = await kortix.project(pid).detail();
await kortix.project(pid).secrets.upsert({
  name: "LOCAL_TOOL_TOKEN",
  value,
  strategy: "runtime",
  consumer: "sandbox",
});
await kortix.project(pid).secrets.upsert({
  identifier: "anthropic-primary",
  name: "ANTHROPIC_API_KEY",
  value: providerKey,
  strategy: "broker",
  consumer: "llm_gateway",
});
const visibleSessions = await kortix.project(pid).sessions.list();
const projectInventory = await kortix
  .project(pid)
  .sessions.list({ scope: "project" }); // manager only
const warm = await kortix.project(pid).sessions.ensureWarm();
await kortix
  .project(pid)
  .sessions.claimWarm({ session_id: warm.session.session_id });

// Sessions (id-bound handle)
const s = kortix.session(pid, sid);
const cost = await s.cost(); // reads finalized LLM + compute cost; no runtime start
await s.send("Build me a widget"); // provisions/resumes if needed, then prompts
await s.rewind(userMessageId); // stages a reversible rollback on this session
await s.restoreRewind(); // restores the removed path before the next prompt
await s.previews();

// Lower level: the typed OpenCode REST compatibility client for THIS sandbox.
// `.runtime` throws until the runtime is resolved, and the runtime is keyed by
// the OpenCode session id (NOT the Kortix `sid`) — resolve both via ensureReady.
const { opencodeSessionId } = await s.ensureReady();
await s.runtime.session.prompt({ sessionID: opencodeSessionId, parts });

For OpenCode REST sessions, send() reads the persisted session model and agent before the first prompt on a handle. This prevents a snapshot-inherited OpenCode session from reusing stale snapshot defaults. A per-call choice overrides a setModel() or setAgent() choice. A handle choice overrides the persisted session default.

React runtime

useSession(projectId, sessionId) opens the OpenCode REST runtime returned by POST /start. The hook owns messages, rewind and restore, cancellation, commands, permissions, and questions. Hosts do not construct runtime routes.

A server-rendered host can seed a known OpenCode pin while /start runs:

useSession(projectId, sessionId, {
  initialOpenCodeSessionId: persistedSession.opencode_session_id,
});

Use only a pin that the host authorized for the same (projectId, sessionId). The seed hydrates cached content. It does not choose the runtime identity. The pin returned by /start always replaces a stale seed. The SDK also scopes OpenCode query and synchronization controllers to the sandbox runtime. Two sandboxes cannot share browser cache state when a snapshot exposes the same OpenCode id during adoption.

The facade surface

createKortix(config) returns one client. The table below is illustrative, not exhaustive — see API-MAP.md for the full per-domain surface:

| namespace | what | |---|---| | kortix.projects | list · get · detail · create · provision · update · archive · llmCatalog · modelPicker · sandboxTemplates · sessions (+ more: listForAccount, sandboxHealth, createSession) | | kortix.accounts | list · get · create · members · invites · tokens.{list,create,revoke} (account-scoped CLI PATs, kortix_pat_…) · audit.{log,export,webhooks.*} (filterable project/session reconstruction log) (+ more: updateName, leave, invite, removeMember, updateMemberRole) | | kortix.billing | entitlement/usage reads: accountState · accountStateMinimal · transactions · transactionsSummary · creditBreakdown · usageHistory · usageRollup · sessionCosts.{list,get} · tierConfigurations — plus a curated mutation surface: checkout.{createSession,confirmSession} · subscription.{createPortalSession,cancel,reactivate,scheduleDowngrade,cancelScheduledChange,prorationPreview} · credits.{purchase,autoTopupSettings,configureAutoTopup} | | kortix.marketplace | public marketplace catalog browse + sources (not project-scoped): items · item · itemFile · marketplaces · featured · sources.{list,add,remove} — distinct from the install-scoped project(id).marketplace | | kortix.validateToken() | pasted-API-key validation helper — GET /accounts/me, never throws, resolves {valid, identity?, error?} | | kortix.connectors | Connector data plane for an agent-minted session token: catalog · tools · search · describe · call · uploadAttachment | | kortix.project(id) | id-bound handle: .secrets · .access · .connectors (data plane + configuration + Connections) · .policies · .triggers · .files · .git · .changeRequests (incl. requestChanges) · .sessions · .tokens (project-scoped CLI PATs — the KORTIX_TOKEN shape) · .marketplace / .registry (install/update/remove catalog items) · .setupLinks.{requestSecret,requestConnector} (agent-minted secret-entry / connector links) · .validateManifest · .gitToken · .setDefaultAgent(name) · .session(sid) (+ more namespaces: .review, .approvals, .gateway (incl. .routing and .playground), .channels, .modelDefaults, .sandbox) | | kortix.session(pid, sid) | id-bound handle: lifecycle (get/update/delete/start/restart/stop/setSharing/previews/commit/publicShares/ensureReady) · finalized cost() · send/abort/rewind/restoreRewind/setModel/setAgent · transcript() · .files · runtime URL helpers (health/previewUrl/proxyUrl) · OpenCode REST compatibility escape hatches: stream() and .runtime | | kortix.runtime() | the OpenCode v2 compatibility client for the active sandbox; use a session-scoped handle in multi-tenant code |

Runnable, self-contained scripts for the highest-value flows live in examples/: list projects with a PAT, send + stream, the multi-tenant server-wrapper pattern, headless transcript rendering, cost pass-through / re-billing, and session files + project secrets. Each file's header comment states the env vars and the exact bun run examples/….ts invocation.

Wrapper backends can attach bounded, non-secret scalar context when creating a session. It is persisted across cold recovery/replacement restart and exposed to the agent only as one KORTIX_SESSION_CONTEXT JSON envelope:

await kortix.project(projectId).sessions.create({
  runtime_context: { workspace_id: "org_123", locale: "de" },
});

Do not put credentials in this map. For a white-label/backend wrapper, create an operator-managed connection, store its credential through the dedicated credential endpoint, and pass only the non-secret connection id at session create:

const project = kortix.project(projectId);
const connection = await project.connectors.connections.reconcile({
  connector_alias: "customer-data",
  owner_type: "external",
  owner_id: wrapperUserId,
  label: "Customer data",
  metadata: { tenant_ref: wrapperTenantReference },
});

// Omit `auth` when creating to apply source-advertised authentication.
const auth = await project.connectors.auth.discover({
  slug: "hubspot",
  provider: "postman",
  spec: "https://github.com/HubSpot/HubSpot-public-api-spec-collection",
});
await project.connectors.connections.updateCredential(connection.connection_id, {
  value: shortLivedCapability,
  kind: "secret",
});
await project.sessions.create({
  runtime_context: { locale: "de" },
  connector_bindings: {
    "customer-data": { connection_id: connection.connection_id },
  },
});

For bring-your-own authorization, each logged-in member creates their own connection without supplying an owner id; Kortix derives ownership from the bearer token:

const connection = await project.connectors.connections.reconcileMember({
  connector_alias: "gmail",
  label: "My Gmail",
});
await project.connectors.connections.pipedreamConnect(connection.connection_id);
// Complete OAuth, then:
await project.connectors.connections.pipedreamFinalize(connection.connection_id);
await project.sessions.create({
  connector_bindings: { gmail: { connection_id: connection.connection_id } },
});

Member connections are owner-only even for project managers, and sessions using one must remain private. Project defaults remain shared; external/agent/subject connections remain operator-managed. Every connection is project/connector scoped and resolved on every Connector request, so revocation takes effect without a restart. Credentials are encrypted server-side and are never returned, placed in KORTIX_SESSION_CONTEXT, or injected into the sandbox environment. Raw env and MCP configuration are not session-create inputs.

For OpenCode REST sessions, session.stream() is a thin facade over the framework-free openEventStream primitive (also exported directly, for hosts that want to manage the client themselves): it resolves THIS handle's own runtime (ensureReady()), connects to that runtime's SSE endpoint, and hands you a close()-able handle. No React required — safe to call from a server-side "Kortix as a Backend" wrapper (Node/Bun), a worker, or a CLI:

const handle = await kortix.session(pid, sid).stream({
  onEvent: (event) => console.log(event.type, event),
  onGapRehydrate: (gapMs) => console.warn(`reconnected after a ${gapMs}ms gap`),
});
// later, to stop:
handle.close();

session.stream() emits OpenCode v2 events. Use useSession() in React.

@kortix/sdk/react's useOpenCodeEventStream uses the exact same primitive under the hood — it just also writes into the React Query cache.

Kortix as a Backend (server-side)

createKortix() stores its config — crucially, the bearer-token getter — in a process-wide singleton. That's correct for a host with one config for its whole lifetime (a browser tab, a CLI, a single-tenant server), but unsafe for a server process handling concurrent requests for different end users: two in-flight requests racing through createKortix()/configureKortix() with different tokens clobber each other, and the last write wins for every other in-flight request.

@kortix/sdk/server (Node/Bun only — never import it from a browser bundle; it statically imports node:async_hooks) fixes this with AsyncLocalStorage:

import { createScopedKortix } from "@kortix/sdk/server";

// Express/Hono/Bun.serve — any per-request handler. One scoped client PER
// REQUEST; each end user's token stays isolated to that request's own async
// call tree, even across `await`s, even under concurrency.
app.get("/projects", async (req, res) => {
  const kortix = createScopedKortix({
    backendUrl: process.env.KORTIX_API_URL!,
    getToken: async () => resolveKortixTokenFor(req), // per-end-user PAT/token
  });
  res.json(await kortix.projects.list());
});

createScopedKortix(config) has the same shape as createKortix(config) — every method call (including calls through .project(id) / .session(pid, sid) handles minted at call time) automatically runs inside that config's scope, and it never writes the process-global singleton. For middleware-style wrapping of an entire request body instead, use the lower-level primitive:

import { runWithKortix } from "@kortix/sdk/server";

app.use(async (req, res, next) => {
  await runWithKortix(
    { backendUrl, getToken: async () => resolveKortixTokenFor(req) },
    async () => {
      await next(); // every Kortix call anywhere in this request sees THIS config
    },
  );
});

A runnable version of the pattern is examples/03-server-wrapper.ts, and the full production-shaped reference (per-user project isolation, route policy, rate limiting, cost markup for re-billing) is apps/whitelabel-demo in wrapper mode — see its README.

Rendering chat (the headless chat kit)

Everything needed to render an agent transcript without adopting any Kortix UI: classifyPart/classifyTurn (@kortix/sdk/turns, framework-free) normalize all twelve opencode part types (text, reasoning, tool, file, subtask, patch, snapshot, agent, retry, compaction, step, + a forward-compat unknown) into a typed ClassifiedPart, and normalize a failed assistant turn's info.error into a { name, message } TurnError — so "assistant message with zero parts but an error" renders as a failure, not silence. renderParts (@kortix/sdk/react, though it has no React import) requires a renderer for every part kind at compile time, so a new part type is a build error at your call site instead of a silent drop in production:

import { renderParts, type PartRenderers } from "@kortix/sdk/react";
import { classifyTurn } from "@kortix/sdk/turns";

const renderers: PartRenderers<React.ReactNode> = {
  text: (p) => <Markdown>{p.text}</Markdown>,
  reasoning: (p) => <Thinking text={p.text} />,
  tool: (p) => <ToolCard name={p.tool.name} status={p.tool.status} />,
  file: (p) => <Attachment name={p.filename ?? p.url} />,
  subtask: (p) => <Delegated agent={p.agent} />,
  patch: (p) => <DiffStat files={p.fileCount} />,
  retry: (p) => <Note>{`retrying (attempt ${p.attempt})`}</Note>,
  compaction: () => <Note>context compacted</Note>,
  snapshot: () => null, // internal checkpoint hash — nothing to show
  agent: () => null, // inline @mention, already in the sibling text
  step: () => null, // model-step bookkeeping
  unknown: () => null, // forward-compat: newer server than client
};

function Turn({ message }: { message: MessageWithParts }) {
  const { parts, error, isEmpty } = classifyTurn(message);
  if (isEmpty && !error) return null;
  return (
    <>
      {renderParts(parts, renderers)}
      {error && <TurnFailed {...error} />}
    </>
  );
}

The living reference is apps/whitelabel-demo/src/components/chat/message-view.tsx — one deliberate rendering decision per part kind, with the rationale for each null. For a memoized message-list binding use useChatTurns(messages) (@kortix/sdk/react); for a no-React plain-text version of the same classification see examples/04-render-transcript.ts. On the live side, narrowChatEvent (root barrel) narrows the raw ~50-variant SSE union from session.stream() / openEventStream down to the curated KortixChatEvent union (~14 members) a chat UI actually dispatches on.

Errors

One typed hierarchy, produced by every HTTP layer — backendApi, the platform client's platformFetch, authenticatedFetch, the files client, the opencode client, and ensureReady() all throw/return the same classes (from the root barrel or @kortix/sdk/api-client; @kortix/sdk/react re-exports them too). They're real classes: instanceof works across every host, and name/shape are preserved for legacy error.name === 'ApiError' sniffers.

• ApiError — any failed request; branch on .status / .code (e.g. 'TIMEOUT', 'RUNTIME_UNAVAILABLE', 'ABORTED'). Timeout errors carry .url / .endpoint / .timeout.
• AuthError extends ApiError — getToken() returned null; the request was never sent (code: 'NO_SESSION').
• BillingError — HTTP 402, with the backend's payload on .detail.
• RequestTooLargeError — HTTP 431 (usually a too-large upload batch), with a .detail.suggestion.
• SessionNotReadyError (root barrel) — a session handle's runtime-scoped member (.runtime, .previewUrl(), .proxyUrl()) was touched before ensureReady() resolved this session's own sandbox.

The canonical server-side wrapper shape — catch a 402 and pass the payload through to your own client for re-billing, instead of leaking a Kortix error:

import { ApiError, AuthError, BillingError } from "@kortix/sdk";

try {
  await kortix.session(pid, sid).send(prompt);
} catch (err) {
  if (err instanceof BillingError) {
    // 402 — surface the upgrade/cost payload under YOUR billing story.
    return res.status(402).json({ reason: "quota", detail: err.detail });
  }
  if (err instanceof AuthError)
    return res.status(401).json({ error: "not authenticated" });
  if (err instanceof ApiError)
    return res.status(err.status ?? 502).json({ error: err.message });
  throw err;
}

Every non-streaming request also carries a 30s default timeout (the long-lived SSE event stream is exempt), so a hung sandbox/daemon call can't wedge a server-side handler forever — it surfaces as an ApiError with code: 'TIMEOUT' instead.

Idempotent reads (GET/HEAD) also absorb transient gateway blips: 502, 503, and 504 retry up to two times with 250ms → 500ms backoff before an ApiError is surfaced. Mutations and HTTP 500 responses are never retried.

Subpath modules

Stable, tree-shakeable surfaces (also reachable via the facade). Not exhaustive — see package.json's exports field for the complete list (it also includes ./config, ./api-client, ./feature-flags, ./fresh-sessions, ./instance-routes, ./opencode-errors, ./platform-client, ./event-stream, ./sandbox-connection-store, ./opencode-pending-store, ./session/url, ./idb-sync-cache):

| import | provides | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @kortix/sdk | createKortix, configureKortix, files, the error classes, classifyPart/classifyTurn, narrowChatEvent, openEventStream, domain result types | | @kortix/sdk/server | Node/Bun only — runWithKortix, createScopedKortix, getScopedConfig (per-request config isolation; see "Kortix as a Backend") | | @kortix/sdk/react | every useOpenCode* hook + providers (reactive data), useSession, useChatTurns/renderParts, domain hooks (useProjectSecrets/useProjectTriggers/useChangeRequests) | | @kortix/sdk/turns | framework-free part/turn classification (classifyPart, classifyTurn, toolInfo, turn grouping/cost helpers) | | @kortix/sdk/files | workspace file ops (daemon /file + /find): listFiles, readFile, readBlob, getFileStatus, findFiles, findText, uploadFile, deleteFile, mkdir, renameFile, … | | @kortix/sdk/session | a session's runtime surface — getSessionHealth/isRuntimeReady + proxy/preview URL builders (rewriteLocalhostUrl, proxyLocalhostUrl, detectLocalhostUrls, …) + preview-auth helpers. No "sandbox" in the public surface — a session owns its runtime | | @kortix/sdk/opencode-client | getClient, getClientForUrl + the full opencode v2 type surface (Event, Part, Message, Session, Pty, Config, …) | | @kortix/sdk/projects-client | the raw REST functions (the facade wraps these) | | @kortix/sdk/auth | authenticatedFetch, token accessors | | @kortix/sdk/api-client | the raw backendApi primitive — host code should go through the facade or another subpath module instead of calling this directly | | @kortix/sdk/server-store · @kortix/sdk/sync-store | active-sandbox state · live message/part/status store |

Configuration

configureKortix(config) (called for you by createKortix) wires one seam:

interface KortixPlatformConfig {
  backendUrl: string;
  getToken: () => Promise<string | null>;
  clientSource?: 'api' | 'cli' | 'mobile' | 'web';
  getUserId?: () => Promise<string | null>;
  billingEnabled?: boolean;
  sandboxId?: string | null;
  onError?: (error: unknown, context?: unknown) => void;
  onToast?: (level, message, options?) => void;
  onNotify?: (event) => void;
  featureFlags?: KortixFeatureFlagOverrides; // per-flag overrides for non-Next.js hosts
}

Set clientSource when a non-web host needs its requests separated in the centralized audit log. The SDK sends the validated value as request metadata. Actor identity and permissions still come from the bearer token.

The SDK is host-agnostic: no Next.js / web coupling in the core. The host injects its token getter and toast/notify sinks; the SDK does the rest. Today that's proven in React DOM (apps/web and the apps/whitelabel-demo reference app are the configureKortix/@kortix/sdk/react consumers). The framework-free core modules — turns, session/url, session (health), projects-client, files, transcript — have no React or DOM dependency and are usable from any JS host; apps/mobile already imports @kortix/sdk/turns this way. React Native does not use @kortix/sdk/react. Mobile now uses the framework-free createHttpSessionSyncController for message history, status recovery, and older pagination. Mobile keeps its platform-specific event transport because React Native cannot consume the SDK's fetch-based SSE stream.

Rules of the road

• No @opencode-ai/sdk in host code. Import opencode types/client from @kortix/sdk/opencode-client. The SDK is the sole owner of that dependency. (Holds today — no host imports it.)
• No raw backendApi / authenticatedFetch in host code. Use the facade or a subpath module. (Aspirational: apps/web still calls backendApi via its @/lib/api-client re-export in ~30 files and keeps a parallel authenticatedFetch in apps/web/src/lib/auth-token.ts — migration pending.)
• React data comes from @kortix/sdk/react hooks; imperative actions from the createKortix facade.

Auth

Authorization: Bearer <token> — a Supabase JWT (user sessions) or a Kortix PAT (kortix_pat_…) for server-side / automation use, supplied via getToken.

Tests

pnpm --filter @kortix/sdk typecheck  # package + examples/ (examples/tsconfig.json)
pnpm --filter @kortix/sdk test   # facade, files, react hooks, turns, transcript, session url/health, projects-client domains

See API-MAP.md for the complete endpoint catalogue. It covers the Kortix REST API and OpenCode REST runtime. See CHANGELOG.md for per-release changes.