Development channels

When NODE_ENV=development, the SDK automatically uses development channels. Use a development CEREAL_API_KEY. Your first agent action opens an outbound connection to hosted Cereal, registers providers and agent configuration, and waits internally until the channel is usable.

import { assistant } from "./agents.js"

const session = await assistant.sessions.start({ message: "Hello" })
// Optional at startup instead: await assistant.init()
// At shutdown:
await assistant.close()

With NODE_ENV=production, the same code uses HTTP callbacks. Set CEREAL_PUBLIC_URL to your deployed application's HTTPS origin. No development branch is needed. Agents without application tool or hook handlers need no channel or callback origin.

Explicit mode overrides

For an application-wide override, configure once before the first agent action:

import { configureCereal } from "@trycereal/sdk"

configureCereal({ devMode: true })

Or override the mode while initializing an agent early:

await assistant.init({ devMode: true })

Use false to force HTTP callbacks, including when NODE_ENV=development. An init() override applies to referenced agents too; router.init() accepts that same option. Later actions reuse the selected mode, including retries after initialization failure. Call close() before initializing with a different mode.

Selection follows this order:

1. init({ devMode }).
2. configureCereal({ devMode }).
3. An explicit transport setting, then CEREAL_TRANSPORT (channel or http).
4. NODE_ENV=development selects channels; every other value, including unset or test, selects HTTP.

Development mode controls callback delivery and local agent namespaces. The API key still selects the Cereal organization and environment. Both modes connect to hosted Cereal.

What travels over the channel

MCP tool requests, hook deliveries and tool decisions travel over the outbound socket. The connection has no public URL. The SDK dispatches each request through the same tool and hook implementations used by HTTP callbacks. Channel authentication replaces the individual HTTP signatures; the handler still receives verified context.

The channel reconnects with bounded exponential backoff. Authorization failures stop reconnection. Initial registration failures reject the triggering action and close the channel; a later action can retry. Closing an agent also cancels a pending connection wait. Each local agent gets its own socket identity and a consistent namespace for references.

CLI and low-level access

The Cereal CLI can load a module, watch it and serve its callbacks in a CLI-owned process. Use the in-application transport above when your application itself starts sessions through its defined agent. Avoid having both processes own the same development agent's callbacks.

@trycereal/sdk/dev exposes startDevChannel for integrations that manage their own channel lifecycle. Its handle has init(), resync() and close(). Application code normally uses agent.init() and agent.close().

CerealDevOptions · CerealDevHandle