> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```sh npm theme={null}
npm install cognitio-agent-sdk@2.0.1
```

```sh pnpm theme={null}
pnpm add cognitio-agent-sdk@2.0.1
```

```sh Bun theme={null}
bun add 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](https://cognitio-agent.mintlify.site/quickstart.md), or set `"type": "module"` in your application's `package.json` to use ESM in `.js` files.

```sh theme={null}
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:

```sh theme={null}
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:

```sh theme={null}
node --env-file=.env --import tsx agent.ts
```

Bun can run the same TypeScript file directly:

```sh theme={null}
bun run agent.ts
```

Guides that import `zod` also need it in your application:

```sh theme={null}
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](https://cognitio-agent.mintlify.site/troubleshooting.md#the-runtime-cannot-be-found) if your package manager omitted the runtime package.

For an environment where you run the server separately, use [remote connections](https://cognitio-agent.mintlify.site/cookbook/remote.md).

## Upgrade an application

Upgrade the main package and commit the updated lockfile:

```sh theme={null}
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](https://cognitio-agent.mintlify.site/changelog.md) 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.

```ts theme={null}
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](https://cognitio-agent.mintlify.site/cookbook/lifecycle.md) for shared and borrowed clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.