Sandboxes
What Chalk sandboxes are, where they run, and when to use one.
Chalk sandboxes are lightweight, isolated execution environments for running arbitrary code, such as agent workloads, model inference, data pipelines, or any container-based task. Each sandbox runs inside a gVisor-hardened container with its own filesystem, network namespace, and resource limits.
Sandboxes are designed around three principles:
compute_class=ComputeClass.HOST, the default) or as a Kubernetes pod (compute_class=ComputeClass.K8S).Sandbox API as CPU workloads. See Resources and GPUs for the compute_class requirement.To create and run your first sandbox, see Quick Start.
A sandbox’s compute class decides where it runs: directly on a host, or as a Kubernetes pod.
The host compute class is the default. Chalk runs the sandbox directly on a host from a
host pool, outside Kubernetes pods. In a self-hosted deployment, the
hosts run in your cloud account. In a Chalk Serverless deployment, Chalk provides
them. When you create a sandbox without additional configuration, it uses the host compute class:
from chalkcompute import Image, Sandbox
sandbox = Sandbox(image=Image.debian_slim()).run()
Chalk provisions and scales the hosts in each pool, within the pool’s limits. Sandboxes are scheduled across availability zones and can cold-start in under two seconds for common base images.
Sandboxes run on the host compute class unless you set
compute_class=ComputeClass.K8S. Some features work on only one of them:
| Feature | host | k8s |
|---|---|---|
| Mounting volumes | Yes | Yes |
exec, exec_stream, and exec_start | Yes | No |
| Workload identity federation | Yes | Yes |
| MCP Gateway | Yes | Yes |
KernelPolicy.RESTRICTED | Yes | Yes |
KernelPolicy.OPEN | No | Yes |
| Network policies | Yes | No |
| Resource detection | Yes | No |
| Managed SSH | Yes | No |
| Tunnels | Yes | No |
| Snapshots and suspension | Yes | No |
Use a Sandbox for a task you address directly as a single workload: running generated agent code, a one-off data backfill, or a per-session workspace that is torn down when the session ends. Sandboxes also run for hours or days, as Long-running sandboxes describes.
For replicated, HTTP-fronted workloads with autoscaling, use a Scaling Group. For function-shaped invocations, use Functions.
Run length alone does not decide between a sandbox and a scaling group, since both
survive disconnects and can be reattached to by name. Choose by how the workload is
reached: a sandbox is one instance you run commands in over exec, while a scaling
group serves an HTTP endpoint backed by replicas that Chalk scales. A long-lived agent
session that you drive through a web UI belongs in a scaling group, which is why
Deep coding agents uses one.