# Configuration reference
> Environment variables and project configuration: INTELLIGENCE_API_KEY, CHANNEL_CODE, PORT, the paired INTELLIGENCE_API_URL / INTELLIGENCE_GATEWAY_WS_URL overrides (bare base URLs, never derived from each other), AGENT_URL for remote AG-UI agents, plus the required tsconfig (jsxImportSource, module settings) and package.json shape (type: module, overrides pin).
- 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`
- `examples/minimal-channel/.env.example`
- `examples/minimal-channel/lib/env.ts`
- `examples/minimal-channel/tsconfig.json`
- `README.md`
---
---
title: "Configuration reference"
description: "Environment variables and project configuration: INTELLIGENCE_API_KEY, CHANNEL_CODE, PORT, the paired INTELLIGENCE_API_URL / INTELLIGENCE_GATEWAY_WS_URL overrides (bare base URLs, never derived from each other), AGENT_URL for remote AG-UI agents, plus the required tsconfig (jsxImportSource, module settings) and package.json shape (type: module, overrides pin)."
---
A Channels process reads its configuration from environment variables at startup and fails fast when a required one is missing. Three variables cover the standard managed setup (`INTELLIGENCE_API_KEY`, `CHANNEL_CODE`, `PORT`), two paired variables override the hosted Intelligence endpoints for self-hosted or non-production environments (`INTELLIGENCE_API_URL`, `INTELLIGENCE_GATEWAY_WS_URL`), and `AGENT_URL` points at a remote AG-UI agent when the agent runs outside the listener process. Beyond environment variables, the project itself must be ESM (`"type": "module"`), pin a single copy of `@ag-ui/client` via `overrides`, and — in any project that renders Channels JSX — point the TypeScript JSX factory at `@copilotkit/channels` with `jsxImportSource`.
## Environment variables
| Variable | Required | Purpose |
| --- | --- | --- |
| `INTELLIGENCE_API_KEY` | Yes | Project-scoped CopilotKit Intelligence API key |
| `CHANNEL_CODE` | Yes (managed Channels) | The exact Channel Code from Intelligence, passed as `createChannel({ name })` |
| `PORT` | No (defaults to `3000`) | Port for the lifecycle HTTP server |
| `INTELLIGENCE_API_URL` | Only for self-hosted / non-production | Bare base URL of the Intelligence HTTP API |
| `INTELLIGENCE_GATEWAY_WS_URL` | Only for self-hosted / non-production | Bare base URL of the Intelligence gateway WebSocket |
| `AGENT_URL` | Only for remote AG-UI agents | HTTP URL of an AG-UI-compatible agent, consumed by `HttpAgent` |
| `OPENAI_API_KEY` | Only when using `BuiltInAgent` with an OpenAI model | Model provider credential for the built-in agent |
The project-scoped API key that authenticates the process to CopilotKit Intelligence. Create it from **API Keys** in the Intelligence project sidebar. A key is required for every Channel — there is no standalone or DIY way to run one. Keep `.env` out of source control and never put this key (or any platform token) in browser code.
Must equal the Channel Code exactly as shown in Intelligence; pass it as the `name` option of `createChannel`. Codes are 3–64 characters, start with a lowercase letter, use lowercase letters and digits separated by single hyphens, are unique per project, and are never the literal `channels`. The value is validated by the runtime, not by `createChannel` — a typo fails at startup and leaves the Channel at **Waiting for runtime** in the dashboard rather than erroring at the call site.
Port for the HTTP server created around the listener. Managed message delivery arrives over the Channel's own gateway socket, not this port — but keep the server: it serves the runtime's web requests, and most hosts require a listening port for health checks. The reference listener reads it as `Number(process.env.PORT ?? 3000)`.
HTTP URL of a remote AG-UI-compatible agent. Pass it to `HttpAgent` from `@ag-ui/client` (also re-exported from `@copilotkit/channels`) and hand that to `createChannel({ agent })`. The built-in agent (`BuiltInAgent` from `@copilotkit/runtime/v2`) runs in the same Node process and needs no `AGENT_URL` and no second server.
Only needed when the agent factory constructs `BuiltInAgent` with an OpenAI model (for example `new BuiltInAgent({ model: "openai:gpt-5.4-mini" })`). A remote AG-UI agent owns its own model credentials.
### Paired Intelligence URL overrides
Hosted Intelligence supplies both endpoint defaults, so a standard managed Channel sets **neither** variable. Override them only for self-hosted or non-production Intelligence — and always **both together**:
Bare base URL of the Intelligence HTTP API, passed as `apiUrl` to `new CopilotKitIntelligence({...})`. Example: `https://intelligence.example.com`.
Bare base URL of the Intelligence gateway WebSocket, passed as `wsUrl` to `new CopilotKitIntelligence({...})`. Example: `wss://realtime.intelligence.example.com`.
The API host and the gateway host are **separate hosts**. Never derive `wsUrl` from `apiUrl` by swapping `https://` for `wss://` — override both or neither. Pass bare base URLs only: the client appends `/api/...`, `/runner`, `/client`, or `/channels` itself, so appending path segments yourself breaks the connection.
```ts title="Wiring the overrides into CopilotKitIntelligence"
import { CopilotKitIntelligence } from "@copilotkit/runtime/v2";
const intelligence = new CopilotKitIntelligence({
apiKey: required("INTELLIGENCE_API_KEY"),
// Both optional; hosted Intelligence supplies the defaults.
apiUrl: process.env.INTELLIGENCE_API_URL,
wsUrl: process.env.INTELLIGENCE_GATEWAY_WS_URL,
});
```
### Example .env files
```dotenv title=".env — managed Channel (hosted Intelligence)"
INTELLIGENCE_API_KEY=
CHANNEL_CODE=support-slack
PORT=3000
# Optional paired overrides for self-hosted or non-production Intelligence:
# INTELLIGENCE_API_URL=https://intelligence.example.com
# INTELLIGENCE_GATEWAY_WS_URL=wss://realtime.intelligence.example.com
```
```dotenv title=".env — remote AG-UI agent (examples/minimal-channel)"
AGENT_URL=
INTELLIGENCE_API_URL=
INTELLIGENCE_GATEWAY_WS_URL=
INTELLIGENCE_API_KEY=
```
## Loading environment variables
The documented start command loads `.env` through Node's native flag — no dotenv dependency required:
```sh
node --env-file=.env --import tsx channel.ts
```
The `examples/minimal-channel` project instead loads `dotenv` in `lib/env.ts` (honoring a `DOTENV_CONFIG_PATH` override) and wraps every read in a fail-fast helper, so a missing variable stops the process at import time instead of producing a half-configured Channel:
```ts title="examples/minimal-channel/lib/env.ts"
import { config } from "dotenv";
config({ path: process.env.DOTENV_CONFIG_PATH, quiet: true });
export const required = (name: string) => {
const value = process.env[name];
if (!value) throw new Error(`Missing ${name}`);
return value;
};
```
Either approach works; the invariant is that required variables are asserted before `createChannel` and `CopilotKitIntelligence` consume them.
A Channel needs **Node.js 22+** (the launcher requires global `WebSocket`) and a long-running process. A serverless request handler cannot host one — the process must own a persistent gateway connection.
## tsconfig requirements
Any project that renders Channels JSX (``, `