Installation

Install Cognitio in a JavaScript or TypeScript application.

Use Node.js 22+ or Bun 1.3.11+. Cognitio is an ESM package with TypeScript declarations included. A model provider API key is required when you run a model request, but not to install the SDK.

​

Install the package

Choose the package manager your application already uses:

npm

npm install cognitio-agent-sdk@2.0.1

Keep optional dependencies enabled. They provide the native runtime for your platform; there is no separate CLI to download or start. Commit your application’s lockfile for reproducible installs.

​

JavaScript projects

Save scripts as .mjs, as in the quickstart, or set "type": "module" in your application’s package.json to use ESM in .js files.

node --env-file=.env agent.mjs

Use --env-file when your provider key is in .env. If you already exported the key in the same shell, node agent.mjs is sufficient.

​

TypeScript projects

For a Node.js project, install a TypeScript runner and enable ESM:

npm pkg set type=module
npm install --save-dev tsx typescript @types/node

Save a guide’s complete TypeScript example as agent.ts, then run:

node --env-file=.env --import tsx agent.ts

Bun can run the same TypeScript file directly:

bun run agent.ts

Guides that import zod also need it in your application:

npm install zod@4.1.8

​

Supported local runtimes

Operating system	Architecture	Notes
macOS	Apple Silicon (arm64), Intel (x64)	Matching runtime selected automatically.
Linux	arm64, x64	Packages available for glibc and musl, including Alpine.
Windows	arm64, x64	Matching runtime selected automatically.

The x64 packages use the baseline runtime build. Install dependencies on the target platform instead of copying node_modules from a different operating system or architecture. See troubleshooting if your package manager omitted the runtime package.

For an environment where you run the server separately, use remote connections.

​

Upgrade an application

Upgrade the main package and commit the updated lockfile:

npm install cognitio-agent-sdk@latest

The SDK pins its platform packages to the matching version. You do not need to upgrade a background runtime separately. Review the changelog before upgrading an existing application.

​

Custom runtime binaries

Most applications should use the bundled runtime. For a custom runtime build, pass an absolute executable path with spawn.binaryPath or set COGNITIO_BIN_PATH. Explicit overrides bypass the automatic bundled-version check, so the custom runtime must implement the SDK’s protocol.

import { Agent } from "cognitio-agent-sdk"

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  spawn: { binaryPath: "/absolute/path/to/cognitio" },
  disallowedTools: ["*"],
})

try {
  console.log((await agent.run("Say hello.")).text)
} finally {
  await agent.close()
}

Replace the placeholder path before running this advanced example. Explicit spawn options give this Agent its own runtime, which close() releases. See lifecycle and cleanup for shared and borrowed clients.