Local development

Your application can serve tools from a laptop without a public URL or tunnel. Set these values in its development environment:

CEREAL_API_KEY=<your development key with read,data,control>
NODE_ENV=development

Run your application normally. The first agent action opens the outbound channel, initializes referenced providers, registers the tools and agent, then performs the action. Frameworks that already set NODE_ENV=development need no extra mode configuration. The same code runs in deployment with NODE_ENV=production and CEREAL_PUBLIC_URL set to your application's HTTPS origin.

const session = await research.sessions.start({
  message: "What are the Orion launch risks?",
  identity: { scope: "user", id: authenticatedUser.id }
})

Session actions wait internally for initialization. Call await research.init() to connect early, and await research.close() during shutdown. Use init({ devMode: true }) or configureCereal({ devMode: true }) to override automatic selection; false forces HTTP callbacks. See mode precedence. The socket code loads only when channel transport is selected.

Development namespaces

CEREAL_DEV_NAME optionally sets the namespace for local agent copies. The default uses your operating system user name. Registered agent and connection slugs receive this suffix, so several developers can work in one development environment. Object references between agents use the same namespace; provider names stay unchanged.

Use a development environment and verify the target shown in the console. The Cereal API key selects the organization and environment; the namespace does not change them.

Serving tools from the CLI

The CLI is useful when you want a dedicated process to load and watch a tool module:

npx @trycereal/cli login
npx @trycereal/cli dev

It looks for cereal.config.ts, then cereal/agent.ts. Export one defined agent as the default or as cereal. The CLI loads TypeScript with tsx, opens the outbound channel, registers declared providers and the agent, and streams session events. Saving a file reloads and re-registers the definition. A syntax error leaves the previous module serving.

The CLI resolves credentials from --api-key, then CEREAL_API_KEY, then its stored personal login. Its --name defaults to the git user name. See CLI options.

The CLI owns its process's callbacks. For a web application whose routes call research.sessions.start(), use the in-application channel configuration above. Run one owner for each development agent to avoid competing callback registrations.

Verification is replaced, not skipped

HTTP callbacks carry a per-request signature. A channel authenticates the outbound socket using a Cereal-issued token; requests arrive over that authenticated stream. Tools receive the same verified session and identity context on both transports. Continue to authorize customer data access inside each tool.

Channel lifecycle · TypeScript quickstart