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 = 3600, timeout_seconds: float = 30.0, rootless: bool = True, network: str = '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) – Default working directory inside the sandbox. By default, the working directory is the only writable path in the sandbox (unless readonly=False is set). If not provided, the container’s WORKDIR is used.

  • ttl_seconds (int | None) – Optional automatic cleanup time-to-live in seconds.

  • timeout_seconds (float) – Timeout in seconds for sandbox creation.

  • rootless (bool) – If True, run gVisor in rootless mode.

  • network (str) – Network mode for runsc.

  • 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