# Deploy and operate

> Run a production Channels listener, expose truthful health checks, handle reconnects and shutdown, and diagnose Intelligence status.

A managed Channel is a long-running worker with an outbound realtime
connection. It is not a serverless request handler. Deploy it like a queue
consumer or WebSocket worker.

## Use the tested runtime pair [#use-the-tested-runtime-pair]

Use this tested package combination. Keep exact versions in your lockfile and
verify compatibility before changing either package.

```bash title="Terminal"
npm install --save-exact @copilotkit/channels@0.11.0 @copilotkit/runtime@1.73.3
```

Run Node.js 22 or later. The managed launcher relies on the global `WebSocket`
available in Node.js 22+.

After you change either package, send a real message again, as in
[Connect and run your agent](/teams/connect).

## Settle before reporting ready [#settle-before-reporting-ready]

Creating the Node listener starts the managed connection for every declared
Channel. Await `ready()` to wait for activation to settle, then inspect
`status()`:

```ts title="health.ts"
const channels = listener.channels;

await channels.ready({ timeoutMs: 30_000 });

const initial = channels.status();
if (initial.overall !== "online") {
  throw new Error(`Channels not online: ${JSON.stringify(initial)}`);
}
```

`ready()` can resolve in `setup_required`; it means activation settled, not
that delivery is healthy. Treat only `status().overall === "online"` as a
healthy connected activation.

The runtime status values are:

| Runtime status   | Meaning                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| `connecting`     | Activation has not settled                                                             |
| `online`         | The managed connection is healthy and can claim delivery invitations                   |
| `setup_required` | The Intelligence provider setup is incomplete                                          |
| `reconnecting`   | The gateway connection dropped and is retrying                                         |
| `error`          | Activation failed, reconnect give-up (~60s default) marked the session not-sendable, or the provider (Slack or Teams) is unhealthy. Read `status().detail` to see which |
| `stopped`        | The Channels control was stopped                                                       |

Treat post-online `error` carefully: after reconnect give-up the client marks
`error` while the gateway connection **keeps retrying**. A successful rejoin
restores `online` without a process restart. Activation-time `error` (bad key,
unreachable gateway, config) is different. Fix configuration and restart the
worker.

The Intelligence UI translates provider and runtime details into its own
operator-facing states such as **Waiting for runtime**, **Conflict**,
**Offline**, **Delivery failing**, and **Online**.

## Expose liveness and readiness separately [#expose-liveness-and-readiness-separately]

- Liveness answers whether the Node process and event loop are running.
- Readiness answers whether `channels.status().overall` is `online`.

- Do not restart for a short `reconnecting` episode. The gateway connection
  reconnects by itself.
- Alert on `error`.
- Restart when your own outage budget runs out.
- Restart when activation failed before the Channel was ever online.

Poll `status()` from your health endpoint or monitoring loop. Do not cache the
startup result forever because an online session can later become reconnecting
or error.

## Shut down cleanly [#shut-down-cleanly]

Register signal handlers before **creating the listener**, not just before
`ready()`. Creating it begins activation, so a signal that arrives during the
connect window must already have somewhere to land. Otherwise it hits Node's
default handler and leaves a live gateway session behind:

```ts title="channel.ts"
let teardown: (() => Promise<void>) | undefined;
const shutdown = async () => {
  await teardown?.();
};

process.once("SIGINT", shutdown);
process.once("SIGTERM", shutdown);

const listener = createCopilotNodeListener({ runtime });
const server = createServer(listener);
teardown = async () => {
  await listener.channels.stop();
  if (server.listening) server.close();
};

await listener.channels.ready({ timeoutMs: 30_000 });
```

Give the worker enough termination grace to stop its managed sessions. Avoid
cutting power before `channels.stop()` has released ownership when a graceful
shutdown is possible.

## Store and rotate secrets [#store-and-rotate-secrets]

Keep these server-side:

```dotenv title=".env"
CPK_INTELLIGENCE_API_KEY=<project-runtime-key>
CHANNEL_CODE=<exact-intelligence-code>

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

Cloud-hosted Intelligence supplies the default endpoints. For a
self-hosted or non-production deployment, override both bases together. Do not
derive one from the other or append `/api`, `/socket`, `/runner`, `/client`, or
`/channels`.

Provider credentials stay in Intelligence. The runner should not contain Slack
tokens or the Teams client secret. Rotate the project runtime key through your
secret manager, restart the listener with the new value, and verify it returns
to **Online**.

## Bound active replicas [#bound-active-replicas]

Intelligence offers each prepared delivery to connected Runtimes that declare
the matching Channel. One Runtime claims that delivery; other replicas can
claim different deliveries at the same time.

Run the same build and Channel declarations on every replica. The managed
listener bounds active and pending delivery work internally. A full Runtime
declines an invitation before it claims the delivery, which leaves another
eligible replica free to claim it. That capacity is not currently exposed as a
public Channel configuration option.

## Observe the full delivery path [#observe-the-full-delivery-path]

At minimum, record these status events:

- startup and the first non-online status
- transitions to `reconnecting`, `error`, and back to `online`
- Channel Code and provider, without credentials

Also record these errors and correlation ids:

- application tool errors and their idempotency ids
- `message.eventId`, `message.turnId`, and `message.deliveryId` for correlation
- `thread.postFile()` failures

Do not log message bodies, hydrated files, API keys, Slack tokens, Teams
secrets, or raw provider payloads by default.

## Release checklist [#release-checklist]

Before release:

1. Build and typecheck the runner on Node.js 22.
2. Confirm the exact package pair is in the lockfile.
3. Start the intended replica set and wait for each listener to report `online`.
4. Send a real provider message and verify a reply.
5. Send `SIGTERM` and confirm graceful shutdown.

Resilience checks:

1. Exercise one tool, one rich message, and one interaction.
2. Restart with a pending approval and confirm your persistence promise.
3. Test a brief network drop and observe `reconnecting` recovery.
4. Send concurrent messages and verify replicas claim distinct deliveries
   within their local bounds.

Use the [Intelligence walkthrough](/teams/intelligence) for control-plane
statuses and [persistence and scaling](/teams/persistence-and-scaling) for
restart-safe application state.
