> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Sandboxes

> Use Cessy sandbox execution for controlled custom code while keeping business decisions in commands, events, projections, and policies.

Sandboxes let Cessy run controlled custom code for workflows that cannot be expressed declaratively. Use them carefully.

## Good sandbox use

* deterministic data transforms
* integration payload shaping
* controlled policy support code
* migration helpers
* preview or testing utilities

## Poor sandbox use

* replacing command handlers
* storing business state outside events
* bypassing permissions
* calling secrets from frontend code
* hiding side effects that operators cannot inspect

## Boundaries

Sandboxed code should have explicit inputs, outputs, credentials, timeouts, and error behavior. Keep external calls behind configured adapters when possible.

## Verification

For sandbox-backed workflows, test:

* success path
* invalid input
* external failure
* timeout
* retry behavior
* Activity and error visibility

## Durable container capacity

Existing deployed Agents can declare bounded RAM, combined RAM and swap, CPU,
and PID settings through their supported Workspace/ChangeSet container policy.
Sandbox templates use the same limits. Publication preserves the declaration;
initial provisioning and normal replacement use it while retaining persistent
work and private state.

Omitted settings keep compatible defaults: 2 GiB RAM, two CPUs, 512 PIDs, and
Docker's default swap behavior. App declarations stay within template limits of
8 GiB RAM, 16 GiB combined RAM and swap, four CPUs, and 2,048 PIDs. Invalid
settings fail before replacement.

An operator adjustment changes only the current container. An unchanged
container keeps that temporary adjustment; replacement resets it to the
declared settings or defaults. Operator ceilings do not become app entitlements.

Sandbox inspection distinguishes template intent recorded at provisioning from
live effective capacity and recorded temporary adjustments. If live readback is
unavailable, the last applied observation is explicitly labeled. Historical
workspaces without recorded intent show it as unknown.

The vNext role-based Agent contract retains its platform-selected profile.
Legacy Agents with declared capacity remain preserved in its compatibility base.