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 – Container image for the sandbox environment.

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

  • memory – Amount of memory allocated to the sandbox (e.g. “1Gi”, “512Mi”).

  • env – Environment variables to inject into the sandbox.

  • workdir – 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 – 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 – Timeout in seconds for sandbox creation.

  • rootless – If True, run gVisor in rootless mode.

  • network – Network mode (“none”, “public”, “host”, “sandbox”); see SandboxConfig. “public” is the recommended internet-access mode.

  • dns – Optional nameserver IPs for the generated /etc/resolv.conf (public resolvers by default for “public”).

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

  • readonly – 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 – 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 – PRIVATE — testing only. If True, passes –ignore-cgroups to runsc.

  • **kwargs – Additional parameters.

Returns:

A unique string identifier for the created sandbox.