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

> Discover OpenSandbox resource quota limits for CPU, memory, and GPU constraints. Learn how OpenSandbox manages sandbox containers with Kubernetes-style specifications.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: understanding
- Published: 2026-03-08

---

**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`](https://github.com/alibaba/OpenSandbox/blob/main/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:

```json
{
  "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:

```python
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:

```go
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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/specs/sandbox-lifecycle.yml) and implemented in [`server/src/api/schema.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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.