create#

SandboxRuntime.create(image: str, cpu: float = 0.0, memory: str | int | float = 0, 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', readonly: bool = True, _oci_spec_transform_fn: Callable[[Dict], Dict | None] | None = None, _ignore_cgroups: bool = False, **kwargs) → str[source]#

Provision the sandbox instance and return unique instance ID.

Parameters:

  • image (str) – Container image for the sandbox environment.

  • cpu (float) – Number of CPU cores allocated to the sandbox.

  • memory (str | int | float) – 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.

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

  • _oci_spec_transform_fn (Callable[[Dict], Dict | None] | None) – PRIVATE — development/testing only. Called with the fully-built OCI spec dict before it is written; may mutate in place or return a new dict. Must be cloudpickle-serializable. No stability guarantees. Accepts a transform function.

  • _ignore_cgroups (bool) – PRIVATE — testing only. If True, passes –ignore-cgroups to runsc.

  • **kwargs – Additional parameters.

Returns:

A unique string identifier for the created sandbox.

Return type:

str