Environments

An organization contains environments. Use separate environments for development and production. Agents, sessions, connections, providers, and secrets are isolated within each environment. Each API key grants access to exactly one environment.

await client.environments.create({
  environment: {
    slug: "prod",
    kind: "production",          // "development" | "production"
    group: "customer-facing"
  }
})
await client.environments.list()
await client.environments.get({ slug: "prod" })
await client.environments.archive({ slug: "old-staging" })   // keeps rows, refuses writes

There are two kinds, and only production changes anything: a member may run agents there and may not redefine them. Everything else is development with a slug that says which, whether it is the shared one, a branch's or a developer's own.

Environment slugs are unique within an organization. A resource ID from another environment returns a not-found error.

API keys

An API key determines its environment. Set CEREAL_API_KEY in each deployment to that environment's key. No environment header is needed; a conflicting header is rejected. See credentials for scopes, restrictions, and personal tokens.

Scopes and roles

read, data, control, with no implication between them, and a person's role collapsing onto the same three. See scopes and roles.

Members

Who belongs to the organization, and who may change that, is on organizations and members.

Spend caps

Caps are set on an environment and on individual keys, and are checked at sessions.create, sessions.send and when an agent spawns a sub-agent, never mid-turn.

await client.environments.update({
  update: {
    slug: "dev",
    spend: { costUsdPerMonth: 50, tokensPerMonth: 20_000_000 }
  }
})

A spend cap does not interrupt an active turn or prevent answering an approval. Usage can therefore exceed the cap during a turn. New work beyond the cap returns SpendLimitExceeded with HTTP 402. See usage and spend.

Retention

Each environment carries a retention policy with five windows in days. An omitted field means unlimited, never "off". See retention.

Deploy code-defined agents

Deploy the same application code with each environment's API key and model credentials. The SDK registers its providers, connections and agent definitions in that environment when initialized. Unchanged agent definitions reuse the existing version. See deployment for callback configuration and verification.

Copy to environment

For an agent managed in the console, open the agent and choose Copy to environment. Choose a target, check its provider, connection and secret references, then copy. You need configuration access in both environments. Secret values, sessions and tool application code are not copied.

The copy writes a version to the agent with the same slug in the target, creating it if needed, and records the source version. Future edits are independent. If application code defines that slug, its next SDK registration can replace the copied definition.