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 = None, timeout_seconds: float = 30.0, rootless: bool = True, network: str = 'none', dns: List[str] | None = None, capabilities: List[str] | None = 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) – 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), enforced by this runtime with a daemon timer. 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.

  • 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