OpenSandbox Resource Quota Limits: CPU, Memory, and GPU Constraints for Sandbox Containers

OpenSandbox enforces three core resource quota limits—CPU, memory, and GPU—using Kubernetes-style string specifications defined in the resourceLimits parameter when creating sandbox containers.

OpenSandbox provides granular control over sandbox container resource consumption through configurable quota constraints. These limits follow Kubernetes resource specification patterns and are validated against the OpenAPI schema defined in specs/sandbox-lifecycle.yml. When you create a sandbox via the lifecycle API, you can specify exactly how much compute, RAM, and GPU hardware the container is allowed to utilize.

Supported Resource Quota Types

The OpenSandbox runtime recognizes three primary resource dimensions that can be constrained via the resourceLimits map. Each limit uses a specific string format that the server parses and enforces during sandbox execution.

CPU Limits (Millicores)

CPU quotas are expressed in millicores using the Kubernetes standard format. One full CPU core equals 1000m, so specifying "250m" grants the sandbox access to 25% of a single CPU core.

This format appears in the OpenAPI specification at specs/sandbox-lifecycle.yml#L777-L788, where the cpu key expects a string value representing millicores. The runtime translates this value into cgroup CPU quota parameters to throttle container processes.

Memory Limits (Bytes and Human-Readable Units)

Memory constraints accept either raw byte values or human-readable Kubernetes-style units. Valid formats include "512Mi" for 512 mebibytes, "1Gi" for 1 gibibyte, or plain byte strings like "536870912".

According to the architecture documentation in docs/architecture.md#L33, memory is one of the three primary quota dimensions managed by the platform. The server validates these limits in server/src/api/schema.py#L60 before applying them to the sandbox container's memory cgroup.

GPU Limits (Device Count)

GPU quotas specify the number of GPU devices the sandbox may access, formatted as a string integer such as "1" or "2". Unlike CPU and memory, which use divisible units, GPU allocation is discrete—each integer represents one physical or virtual GPU device attached to the container.

The high-level architecture overview confirms GPU as a managed quota dimension alongside CPU and memory, while the README at server/README.md#L19 notes that the quota system supports "CPU/memory limits with Kubernetes-style specs" and extends to GPU resources.

Configuring Resource Limits in OpenSandbox

You define resource quota limits by populating the resourceLimits object in your sandbox creation request. The map accepts string key-value pairs where keys must be cpu, memory, or gpu to be interpreted by the runtime.

REST API Payload (JSON)

When calling the sandbox lifecycle endpoint directly, include the limits as top-level string values:

{
  "image": { "uri": "python:3.11-slim" },
  "timeout": 3600,
  "resourceLimits": {
    "cpu": "500m",
    "memory": "512Mi",
    "gpu": "1"
  },
  "entrypoint": ["python", "-m", "http.server", "8000"]
}

Python SDK

The Python client maps these limits through the ResourceLimits model defined in the generated SDK:

from opensandbox.api.lifecycle.models import CreateSandboxRequest, ImageSpec, ResourceLimits

req = CreateSandboxRequest(
    image=ImageSpec(uri="python:3.11-slim"),
    timeout=3600,
    resourceLimits=ResourceLimits({"cpu": "500m", "memory": "512Mi", "gpu": "1"}),
    entrypoint=["python", "-m", "http.server", "8000"]
)

Go Client

For Go applications using the execd API, define a map with the appropriate struct tags:

type CreateSandboxRequest struct {
    Image struct {
        URI string `json:"uri"`
    } `json:"image"`
    Timeout        int64            `json:"timeout"`
    ResourceLimits map[string]string `json:"resourceLimits"`
    Entrypoint     []string         `json:"entrypoint"`
}

req := CreateSandboxRequest{
    Image: struct{ URI string `json:"uri"` }{URI: "python:3.11-slim"},
    Timeout: 3600,
    ResourceLimits: map[string]string{
        "cpu":    "500m",
        "memory": "512Mi",
        "gpu":    "1",
    },
    Entrypoint: []string{"python", "-m", "http.server", "8000"},
}

Implementation and Validation

The resource quota system is implemented across several key components of the alibaba/OpenSandbox repository:

• specs/sandbox-lifecycle.yml: Defines the ResourceLimits schema at lines 777-788, specifying that only cpu, memory, and gpu keys are officially supported by the API contract.
• server/src/api/schema.py: Contains the Pydantic validation model at line 60 that enforces string typing for all resource limit values at runtime.
• docs/architecture.md: Lists CPU, memory, and GPU as the three managed quota dimensions at line 33, confirming the scope of the resource control plane.
• server/README.md: Documents the Kubernetes-style specification approach at line 19, indicating design parity with standard container orchestration resource definitions.

While resourceLimits is defined as a generic map[string]string allowing additional custom keys without breaking API compatibility, the runtime currently interprets and enforces only cpu, memory, and gpu entries.

Summary

• OpenSandbox supports three resource quota dimensions: CPU (millicores), memory (bytes or human-readable units), and GPU (integer device count).
• Limits are configured via the resourceLimits parameter using Kubernetes-style string specifications when creating sandboxes.
• The quota schema is defined in specs/sandbox-lifecycle.yml and implemented in server/src/api/schema.py, ensuring validation before runtime enforcement.
• Additional custom keys can be added to the resource map without API breakage, but only the three core types are processed by the current runtime.

Frequently Asked Questions

Can I apply custom resource quota limits beyond CPU, memory, and GPU?

While the resourceLimits field accepts any string key-value pair, the OpenSandbox runtime currently interprets and enforces only cpu, memory, and gpu entries. Custom keys can be stored in the map without causing validation errors, but they will not trigger resource constraints in the underlying container runtime.

What happens if a sandbox container exceeds its CPU or memory quota?

The OpenSandbox runtime utilizes Linux cgroups to enforce hard limits. If a sandbox exceeds its memory quota, the kernel OOM killer terminates the container process. For CPU limits, the process is throttled to the specified millicore allocation, causing performance degradation rather than termination.

Does OpenSandbox support fractional GPU allocation?

No, the GPU resource quota supports only whole device allocation via string integers (e.g., "1", "2"). The architecture documentation in docs/architecture.md lists GPU as a discrete resource dimension, and the OpenAPI schema specifies integer string values without decimal support.

Are resource quota limits validated during sandbox creation?

Yes, the server validates all resourceLimits entries against the Pydantic model in server/src/api/schema.py before instantiating the container. Invalid formats (such as non-numeric GPU values or malformed memory units) trigger immediate API errors with descriptive validation messages, preventing misconfigured sandboxes from reaching the execution stage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}