feat(opensandbox): configurable sandbox resource limits and requests (#8305)

* feat(opensandbox): configurable sandbox resource limits and requests

The OpenSandbox provider passes no resources to SandboxSync.create(), so
every sandbox gets the SDK default of 1 CPU / 2Gi and the server's default
requests. Workloads that need more (builds, PDF rendering, data work) can't
get it, and clusters with tight quotas can't ask for less.

Add two optional sandbox options, `resource` (limits) and
`resource_requests`, each a map of resource names to quantities, forwarded
to SandboxSync.create(). Numbers become strings; other value types fail at
provider startup. Unset, null or empty keeps today's defaults.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(opensandbox): reject blank or non-positive resource quantities; document requests

Review follow-up for #8305:
- Reject blank or whitespace resource names and quantities, and numeric
  quantities that are zero, negative or non-finite, at provider startup
  instead of failing at acquire().
- Document that only Kubernetes runtimes apply resource_requests, that an
  omitted request defaults to its limit, and that requests must fit within
  the limits, including the SDK default 1 CPU / 2Gi when resource is unset.
- Bump config_version to 67 (example, chart values, chart README) and add a
  CHANGELOG entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: drop the CHANGELOG entries (generated in batch by maintainers)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Bas Cancrinus 2026-11-17 15:01:07 +01:00 committed by GitHub
parent 3751eb8daf
commit f32570d539
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 97 additions and 4 deletions

View File

@ -1659,6 +1659,8 @@ sandbox:
ready_timeout: 30 # create/readiness timeout seconds
use_server_proxy: false # proxy execd/file traffic through server
secure_access: false # per-sandbox endpoint token; Kubernetes + gateway mode only
resource: {cpu: "2", memory: 4Gi} # sandbox limits; omitted = SDK default 1 CPU / 2Gi
resource_requests: {cpu: "1", memory: 2Gi} # sandbox requests; omitted = server default
sandbox_timeout: 14400 # remote lifetime; 0 = explicit cleanup
bash_command_timeout: 600 # default remote command timeout seconds
replicas: 3 # active + warm cap per gateway process
@ -1671,6 +1673,19 @@ sandbox:
values default to `false`. Quoted values such as `"false"` cause a provider
startup error.
`resource` and `resource_requests` map resource names to Kubernetes quantities
(`cpu`, `memory`, or any name the OpenSandbox runtime accepts). They become the
sandbox's limits and requests. Without `resource`, the SDK asks for 1 CPU and
2Gi; without `resource_requests`, the server decides the requests.
Only Kubernetes runtimes apply `resource_requests`; the Docker runtime ignores
them. On Kubernetes, a request you omit defaults to its limit, and every request
must fit within its limit. That includes the SDK default limits: setting only
`resource_requests: {cpu: "2", memory: 4Gi}` sends limits of 1 CPU and 2Gi, and
the sandbox creation fails. Set `resource` whenever requests exceed those
defaults. Blank names or quantities and zero, negative or non-finite numbers
cause a provider startup error.
Install the optional SDK before selecting this provider:
```bash

View File

@ -8,7 +8,10 @@ cd backend && python -m pytest tests -q -k "opensandbox"
Validate `use_server_proxy` and `secure_access` at provider startup. Accept
booleans, default missing or null values to `false`, and reject strings and
other types before creating an SDK connection.
other types before creating an SDK connection. Validate `resource` and
`resource_requests` the same way: a mapping of non-blank string names to
non-blank string or finite positive numeric quantities, or missing/null/empty
for the SDK default.
## Command deadlines

View File

@ -23,6 +23,8 @@ sandbox:
# ready_timeout: 30
# use_server_proxy: false
# secure_access: false
# resource: {cpu: "2", memory: 4Gi} # limits; default 1 CPU / 2Gi
# resource_requests: {cpu: "1", memory: 2Gi} # requests; default from the server
# sandbox_timeout: 14400 # remote lifetime; 0 means explicit cleanup only
# bash_command_timeout: 600 # default command timeout
# replicas: 3 # active + warm sandboxes per gateway process
@ -49,6 +51,17 @@ needed in DeerFlow. The server must run the Kubernetes runtime with
`[ingress] mode = "gateway"`; the Docker runtime and other ingress modes reject
the create with HTTP 400.
`resource` sets each sandbox's limits and `resource_requests` its requests,
as maps of resource names to Kubernetes quantities. Without `resource`, the
SDK default of 1 CPU and 2Gi applies to every sandbox. Without
`resource_requests`, the server decides the requests. Only Kubernetes runtimes
apply `resource_requests`; Docker ignores them. Kubernetes uses the limit for
any request you omit, and a request must not exceed its limit, including the
SDK default limits when `resource` is unset (a request of 2 CPU without
`resource` fails at sandbox creation). Positive numbers are passed as strings;
blank names or quantities, zero, negative or non-finite numbers, and other
value types cause a provider startup error.
Values in `sandbox.environment` that start with `$` are resolved from the
Gateway process environment once, when `config.yaml` loads; a missing variable
fails the load. The provider injects the resolved values unchanged, so a secret

View File

@ -15,6 +15,7 @@ import threading
import time
import unicodedata
import uuid
from collections.abc import Mapping
from datetime import timedelta
from functools import partial
from pathlib import Path, PurePosixPath
@ -125,6 +126,28 @@ class OpenSandboxProvider(WarmPoolLifecycleMixin[OpenSandboxSandbox], SandboxPro
raise ValueError(f"sandbox.{name} must be true or false")
return value
def resource_quantity(value: Any) -> str | None:
if isinstance(value, str):
return value.strip() or None
if isinstance(value, int | float) and not isinstance(value, bool) and math.isfinite(value) and value > 0:
return str(value)
return None
def resource_option(name: str) -> dict[str, str] | None:
value = option(name)
if value is None:
return None
invalid = ValueError(f"sandbox.{name} must map resource names to positive quantities, e.g. {{cpu: '2', memory: 4Gi}}")
if not isinstance(value, Mapping):
raise invalid
resources: dict[str, str] = {}
for key, raw in value.items():
quantity = resource_quantity(raw)
if not isinstance(key, str) or not key.strip() or quantity is None:
raise invalid
resources[key.strip()] = quantity
return resources or None
api_key = option("api_key")
domain = option("domain")
protocol = option("protocol") or "http"
@ -160,6 +183,8 @@ class OpenSandboxProvider(WarmPoolLifecycleMixin[OpenSandboxSandbox], SandboxPro
"environment": environment,
"replicas": replicas if replicas is not None else self.DEFAULT_REPLICAS,
"idle_timeout": idle_timeout if idle_timeout is not None else self.DEFAULT_IDLE_TIMEOUT,
"resource": resource_option("resource"),
"resource_requests": resource_option("resource_requests"),
}
def _get_sdk(self) -> tuple[type[SandboxSync], type[ConnectionConfigSync], type[RunCommandOpts]]:
@ -318,6 +343,8 @@ class OpenSandboxProvider(WarmPoolLifecycleMixin[OpenSandboxSandbox], SandboxPro
ready_timeout=timedelta(seconds=self._config["ready_timeout"]),
env=self._config["environment"] or None,
metadata=metadata,
resource=self._config["resource"],
resource_requests=self._config["resource_requests"],
connection_config=connection_config,
secure_access=self._config["secure_access"],
)

View File

@ -228,6 +228,9 @@ class SandboxConfig(BaseModel):
secure_access: Ask OpenSandbox to require a per-sandbox access token on
sandbox endpoints (default: false). Needs a Kubernetes runtime in
ingress gateway mode; other servers reject the create with 400.
resource, resource_requests: Sandbox limits and requests as maps of
resource names to quantities, e.g. {cpu: "2", memory: 4Gi}. Without
resource, the SDK default of 1 CPU / 2Gi applies.
ready_timeout: Create/readiness deadline in seconds (default: 30).
sandbox_timeout: Remote lifetime in seconds (default: 14400); 0 requires
explicit provider cleanup.

View File

@ -398,6 +398,36 @@ def test_create_forwards_secure_access(monkeypatch: pytest.MonkeyPatch, configur
provider.shutdown()
def test_create_keeps_sdk_default_resources_when_unset(monkeypatch: pytest.MonkeyPatch) -> None:
provider, sdk = _install(monkeypatch, config={"resource": None, "resource_requests": {}})
provider.acquire("thread-1", user_id="user-1")
assert sdk.create_calls[0]["resource"] is None
assert sdk.create_calls[0]["resource_requests"] is None
provider.shutdown()
def test_create_forwards_resource_limits_and_requests(monkeypatch: pytest.MonkeyPatch) -> None:
provider, sdk = _install(monkeypatch, config={"resource": {"cpu": 2, "memory": " 4Gi "}, "resource_requests": {" cpu ": 0.5, "memory": "1Gi"}})
provider.acquire("thread-1", user_id="user-1")
assert sdk.create_calls[0]["resource"] == {"cpu": "2", "memory": "4Gi"}
assert sdk.create_calls[0]["resource_requests"] == {"cpu": "0.5", "memory": "1Gi"}
provider.shutdown()
@pytest.mark.parametrize("name", ["resource", "resource_requests"])
@pytest.mark.parametrize(
"value",
["2", ["cpu"], {"cpu": True}, {"cpu": None}, {1: "2"}, {"": "1"}, {" ": "1"}, {"cpu": ""}, {"cpu": " "}, {"cpu": 0}, {"cpu": -1}, {"cpu": float("nan")}, {"cpu": float("inf")}],
)
def test_provider_rejects_invalid_resources(monkeypatch: pytest.MonkeyPatch, name: str, value: Any) -> None:
with pytest.raises(ValueError, match=f"sandbox.{name} must map resource names to positive quantities"):
_install(monkeypatch, config={name: value})
@pytest.mark.parametrize("value", ["true", "false", 1, 0])
def test_provider_rejects_non_boolean_secure_access(monkeypatch: pytest.MonkeyPatch, value: Any) -> None:
with pytest.raises(ValueError, match="sandbox.secure_access must be true or false"):

View File

@ -20,7 +20,7 @@
# ============================================================================
# Bump this number when the config schema changes.
# Run `make config-upgrade` to merge new fields into your local config.yaml.
config_version: 66
config_version: 67
# Optional operator-owned literal prompt extensions (see CONFIGURATION.md):
# lead_prompt_overlay:
@ -2013,6 +2013,8 @@ sandbox:
# # ready_timeout: 30 # finite positive create/readiness timeout seconds
# # use_server_proxy: false # proxy execd/file traffic through server
# # secure_access: false # per-sandbox endpoint token; needs Kubernetes + ingress gateway mode
# # resource: {cpu: "2", memory: 4Gi} # sandbox limits; omitted = SDK default 1 CPU / 2Gi
# # resource_requests: {cpu: "1", memory: 2Gi} # sandbox requests; omitted = server default
# # sandbox_timeout: 14400 # finite non-negative remote lifetime seconds; 0 = explicit cleanup
# # bash_command_timeout: 600 # default remote command timeout seconds
# # replicas: 3 # active + warm cap per gateway process

View File

@ -150,7 +150,7 @@ they resolve from the `secrets` map):
```yaml
config: |
config_version: 66
config_version: 67
models:
- name: gpt-4
use: langchain_openai:ChatOpenAI

View File

@ -381,7 +381,7 @@ ingress:
# -- DeerFlow config.yaml content. Secrets MUST stay as $VAR references — never
# inline literal secret values here. The default enables provisioner sandbox.
config: |
config_version: 66
config_version: 67
log_level: info
recursion_limit: 100
max_recursion_limit: 1000