# Installation
> Install @copilotkit/channels with @copilotkit/runtime as a version-locked pair, enforce ESM with npm pkg set type=module, pin @ag-ui/client via overrides to avoid the duplicate-AbstractAgent compile failure, and configure tsconfig with jsxImportSource for the Channels JSX runtime.
- Repository: CopilotKit/channels-sdk
- GitHub: https://github.com/CopilotKit/channels-sdk
- Human docs: https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161
- Complete Markdown: https://grok-wiki.com/public/docs/copilotkit-channels-sdk-4c947e3e6161/llms-full.txt
## Source Files
- `.agents/skills/build-channels-agent/SKILL.md`
- `README.md`
- `examples/minimal-channel/package.json`
- `examples/minimal-channel/tsconfig.json`
---
---
title: "Installation"
description: "Install @copilotkit/channels with @copilotkit/runtime as a version-locked pair, enforce ESM with npm pkg set type=module, pin @ag-ui/client via overrides to avoid the duplicate-AbstractAgent compile failure, and configure tsconfig with jsxImportSource for the Channels JSX runtime."
---
A working Channels project requires four things installed and configured before any code runs: `@copilotkit/channels` and `@copilotkit/runtime` at matching versions, ESM enabled in `package.json`, a single deduplicated copy of `@ag-ui/client`, and a tsconfig that points the JSX factory at `@copilotkit/channels` instead of React. Each of these has a specific, documented failure mode when skipped, so the install order below is not optional polish — it is the difference between a project that typechecks and one that fails with misleading errors.
## Prerequisites
- **Node.js 22 or later.** The launcher requires the global `WebSocket` implementation that ships with Node 22+.
- **A long-running Node process or container.** A Channel owns a persistent gateway connection to CopilotKit Intelligence; a serverless request handler cannot host one.
- **A CopilotKit Intelligence API key** (free tier available). There is no standalone or DIY way to run a Channel.
## Install the package pair
`@copilotkit/channels` is batteries-included: one install provides the engine, the JSX vocabulary, the UI primitives, the testing API, and every platform adapter (on subpaths such as `@copilotkit/channels/slack`, `/teams`, `/discord`, `/telegram`, `/whatsapp`). `@copilotkit/runtime` is required to *start* a Channel — the runtime owns the Channel lifecycle.
```sh
npm install @copilotkit/channels @copilotkit/runtime
npm install --save-dev tsx typescript @types/node
npm pkg set type=module
```
Channels and Runtime ship and are tested together as a pair. Always upgrade both packages in the same change. Known-good pairs verified against the SDK's own compiled samples:
| `@copilotkit/channels` | `@copilotkit/runtime` | Notes |
| --- | --- | --- |
| `0.7.1` | `1.66.1` | Adds `defineChannelComponent` and native-node helpers (0.7+ only) |
| `0.6.1` | `1.65.0` | The pair pinned by the hosted Slack guide |
To lock a known-good pair exactly:
```sh
npm install --save-exact @copilotkit/channels@0.6.1 @copilotkit/runtime@1.65.0
```
Standalone `@copilotkit/channels-ui`, `-slack`, `-teams` (and similar) packages exist and work, but the single umbrella dependency is the documented path. Do not import from `@copilotkit/channels-ui` unless it is a direct dependency — as a transitive dep it resolves under npm's hoisted layout but fails under pnpm's isolated one.
## Enforce ESM
The standard listener startup uses top-level `await` (`await channels.ready(...)`), so the project must be an ES module:
```sh
npm pkg set type=module
```
Skipping this produces the compile error:
```text
TS1309: The current file is a CommonJS module whose imports will produce 'require' calls
```
The `examples/minimal-channel` project in this repository ships with `"type": "module"` already set in its `package.json`.
## Pin @ag-ui/client to one copy
**Dedupe `@ag-ui/client` or the project will not compile.** Channels and Runtime both depend on one exact version, but a transitive dependency (`@ag-ui/mcp-middleware`) pulls an older one, and npm nests it. Two copies means two separate `AbstractAgent` type declarations, so passing *any* agent to `createChannel({ agent })` fails with a confusing error about "separate declarations of a private property `_debug`". This is the single most common reason a correct-looking Channel refuses to typecheck.
First find the version Runtime declares:
```sh
npm ls @ag-ui/client
```
Then pin that version in `package.json` and reinstall:
```json
{
"overrides": {
"@ag-ui/client": "0.0.57"
}
}
```
```json
{
"pnpm": {
"overrides": {
"@ag-ui/client": "0.0.57"
}
}
}
```
```json
{
"resolutions": {
"@ag-ui/client": "0.0.57"
}
}
```
Use the version your installed `@copilotkit/runtime` declares — `0.0.57` is the version matching the pairs above. The `examples/minimal-channel` project takes the equivalent route of declaring `"@ag-ui/client": "^0.0.57"` as a direct dependency under pnpm.
## Configure tsconfig
Any file that contains Channels JSX must have the `.tsx` extension, and the tsconfig must point the JSX factory at Channels — this is not React. Without `jsxImportSource`, the JSX tree compiles against React's types and fails.
```json title="tsconfig.json"
{
"compilerOptions": {
"target": "ES2022",
"jsx": "react-jsx",
"jsxImportSource": "@copilotkit/channels",
"module": "nodenext",
"moduleResolution": "nodenext",
"strict": true,
"types": ["node"]
}
}
```
Point `jsxImportSource` at `@copilotkit/channels` — the package you installed — not at `@copilotkit/channels-ui`, which is only a transitive dependency of the umbrella package.
A listener that renders no JSX can omit `jsx` / `jsxImportSource` entirely. The `examples/minimal-channel` project posts plain text only, so its tsconfig uses `"module": "ESNext"` with `"moduleResolution": "Bundler"` and no JSX settings. Add the JSX options the moment you introduce a `.tsx` file.
## Verify the install
```sh
npm ls @ag-ui/client
```
Exactly one version should appear in the tree (deduped entries pointing at the same version are fine). Two distinct versions mean the overrides pin is missing or the lockfile predates it — reinstall after adding the pin.
```sh
npm pkg get type
```
Expected output: `"module"`.
```sh
npx tsc --noEmit
```
A clean pass confirms the pair versions match, `@ag-ui/client` is deduplicated, and the JSX configuration resolves. The `_debug` private-property error at this stage always means duplicate `@ag-ui/client` copies; `TS1309` always means missing `type: module`.
Once TypeScript is clean, the standard way to run a listener during development is:
```sh
node --env-file=.env --import tsx channel.ts
```
## Common install failures
| Symptom | Cause | Fix |
| --- | --- | --- |
| `separate declarations of a private property '_debug'` | Two nested copies of `@ag-ui/client` | Add the `overrides` pin, reinstall |
| `TS1309: The current file is a CommonJS module` | Missing `"type": "module"` | `npm pkg set type=module` |
| JSX props rejected / React types in errors | Missing `jsxImportSource` | Set `"jsxImportSource": "@copilotkit/channels"` |
| Import from `@copilotkit/channels-ui` fails under pnpm | Transitive dep not hoisted | Import from `@copilotkit/channels` root instead |
| APIs like `createBot` / `defineBotTool` not found | Pre-release names that were never shipped | Use `createChannel`, `defineChannelTool` |
## Next
Create the Channel in Intelligence, write the listener, set the four environment variables, and verify `status().overall === "online"`.
Let `npx copilotkit@latest channels setup` and the hosted guide drive the install and provider configuration for you.
Every environment variable plus the full required `tsconfig` and `package.json` shape.
Full write-ups of the duplicate `@ag-ui/client` error, TS1309, and other documented failure modes.