create#
- ray.experimental.sandbox.create(image: str, cpu: float | None = None, memory: str | int | float | None = None, env: Dict[str, str] | None = None, workdir: str | None = None, ttl_seconds: int | None = None, timeout_seconds: float = 30.0, rootless: bool = True, network: str = 'none', dns: List[str] | None = None, cidr_allowlist: List[str] | None = None, capabilities: List[str] | None = None, resources: Dict[str, float] | None = None, disk: str | int | float = 0, num_gpus: float | None = None, **kwargs) ActorHandle[source]#
Create a remote sandbox environment managed by a Ray actor.
Spawns a
Sandboxactor on the Ray cluster to manage the sandbox lifecycle and returns anActorHandle. For low-level local sandbox management on the current node (e.g., inside custom worker actors), useSandboxRuntimeinstead.The sandbox writes to a private copy-on-write overlay over its image. Sandboxes that share an image don’t see each other’s writes, the cached image is never modified, and the overlay is discarded with the sandbox.
- Parameters:
image (str) – Container image for the sandbox environment.
cpu (float | None) – Number of CPU cores allocated to the sandbox.
memory (str | int | float | None) – Amount of memory allocated to the sandbox (e.g. “1Gi”, “512Mi”).
env (Dict[str, str] | None) – Environment variables to inject into the sandbox.
workdir (str | None) – Working directory for commands; None uses the image’s WORKDIR.
ttl_seconds (int | None) – Optional time-to-live in seconds, wall-clock from creation (not idle time). None (default) or <= 0 disables it.
timeout_seconds (float) – Timeout in seconds for sandbox creation.
rootless (bool) – If True, run gVisor in rootless mode.
network (str) – Network mode (“none”, “public”, “host”, “sandbox”); see
SandboxConfig. “public” is the recommended internet-access mode.dns (List[str] | None) – Optional nameserver IPs for the generated /etc/resolv.conf (public resolvers by default for “public”).
cidr_allowlist (List[str] | None) – Optional egress allowlist for network=”public”: only the listed destinations are reachable (plus DNS to the
dnsresolvers). None means the public internet, with internal addresses left out as a best effort, and a denylist keeps instance metadata and the Kubernetes API service closed whatever the list says; seeSandboxConfig.capabilities (List[str] | None) – Linux capabilities, written exactly (None keeps the runtime default;
[]means none). UseDOCKER_DEFAULT_CAPABILITIESfor Docker parity.resources (Dict[str, float] | None) – Custom logical resource requirements.
disk (str | int | float) – Size cap of the root filesystem overlay (e.g. “10Gi”); writes past it fail with ENOSPC. Zero (default) means no cap; see
SandboxConfig.num_gpus (float | None) – Number of GPUs to schedule the sandbox actor with. The sandbox gets every GPU Ray assigns the actor, exposed through CDI. This is the only way to give a sandbox created here GPUs.
**kwargs – Additional options. The removed
readonlyoption is still recognized:readonly=Falseis ignored with a deprecation warning, andreadonly=Trueraises aValueError.
- Returns:
A Sandbox actor handle.
- Return type:
PublicAPI (alpha): This API is in alpha and may change before becoming stable.