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, capabilities: List[str] | None = None, resources: Dict[str, float] | None = None, readonly: bool = True, **kwargs) → ActorHandle[source]#

Create a remote sandbox environment managed by a Ray actor.

Spawns a Sandbox actor on the Ray cluster to manage the sandbox lifecycle and returns an ActorHandle. For low-level local sandbox management on the current node (e.g., inside custom worker actors), use SandboxRuntime instead.

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. On a readonly rootfs an explicit workdir is also the sandbox’s only writable path; see SandboxConfig.

  • 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”).

  • capabilities (List[str] | None) – Linux capabilities, written exactly (None keeps the runtime default; [] means none). Use DOCKER_DEFAULT_CAPABILITIES for Docker parity.

  • resources (Dict[str, float] | None) – Custom logical resource requirements.

  • readonly (bool) – If True (default), mount container image rootfs in read-only mode such that only workdir is writable. If False, the entire root filesystem is writable. Writes are isolated within a per-sandbox copy-on-write overlay filesystem, ensuring multiple sandboxes running the same container image do not interfere with each other or modify the base image.

  • **kwargs – Additional options.

Returns:

A Sandbox actor handle.

Return type:

ActorHandle

PublicAPI (alpha): This API is in alpha and may change before becoming stable.

On this page