​
Overview

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:

  1. Strong isolation. Workloads from different tenants (and different workloads from the same tenant) cannot observe or interfere with each other.
  2. Two compute classes. The same sandbox abstraction runs directly on a host from a host pool (compute_class=ComputeClass.HOST, the default) or as a Kubernetes pod (compute_class=ComputeClass.K8S).
  3. First-class GPU support. GPU-accelerated workloads use the same Sandbox API as CPU workloads. See Resources and GPUs for the compute_class requirement.

To create and run your first sandbox, see Quick Start.


​
Where sandboxes run

A sandbox’s compute class decides where it runs: directly on a host, or as a Kubernetes pod.

​
Host compute class

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.

​
Features by compute class

Sandboxes run on the host compute class unless you set compute_class=ComputeClass.K8S. Some features work on only one of them:

Featurehostk8s
Mounting volumesYesYes
exec, exec_stream, and exec_startYesNo
Workload identity federationYesYes
MCP GatewayYesYes
KernelPolicy.RESTRICTEDYesYes
KernelPolicy.OPENNoYes
Network policiesYesNo
Resource detectionYesNo
Managed SSHYesNo
TunnelsYesNo
Snapshots and suspensionYesNo

​
When to use a Sandbox

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.