From f32570d53996914a9d5da61ffc46d242e1c8b86e Mon Sep 17 00:00:00 2001 From: Bas Cancrinus <7222814+bascan@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:01:07 +0100 Subject: [PATCH] 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 * 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 * chore: drop the CHANGELOG entries (generated in batch by maintainers) Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- backend/docs/CONFIGURATION.md | 15 ++++++++++ .../deerflow/community/opensandbox/AGENTS.md | 5 +++- .../deerflow/community/opensandbox/README.md | 13 ++++++++ .../community/opensandbox/provider.py | 27 +++++++++++++++++ .../harness/deerflow/config/sandbox_config.py | 3 ++ backend/tests/test_opensandbox_provider.py | 30 +++++++++++++++++++ config.example.yaml | 4 ++- deploy/helm/deer-flow/README.md | 2 +- deploy/helm/deer-flow/values.yaml | 2 +- 9 files changed, 97 insertions(+), 4 deletions(-) diff --git a/backend/docs/CONFIGURATION.md b/backend/docs/CONFIGURATION.md index 1832c6801b..635f23ebc6 100644 --- a/backend/docs/CONFIGURATION.md +++ b/backend/docs/CONFIGURATION.md @@ -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 diff --git a/backend/packages/harness/deerflow/community/opensandbox/AGENTS.md b/backend/packages/harness/deerflow/community/opensandbox/AGENTS.md index 440ad3c5db..a2a2a0bc81 100644 --- a/backend/packages/harness/deerflow/community/opensandbox/AGENTS.md +++ b/backend/packages/harness/deerflow/community/opensandbox/AGENTS.md @@ -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 diff --git a/backend/packages/harness/deerflow/community/opensandbox/README.md b/backend/packages/harness/deerflow/community/opensandbox/README.md index c51c83dc3f..88af6f6482 100644 --- a/backend/packages/harness/deerflow/community/opensandbox/README.md +++ b/backend/packages/harness/deerflow/community/opensandbox/README.md @@ -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 diff --git a/backend/packages/harness/deerflow/community/opensandbox/provider.py b/backend/packages/harness/deerflow/community/opensandbox/provider.py index af169cb425..0deae1cea3 100644 --- a/backend/packages/harness/deerflow/community/opensandbox/provider.py +++ b/backend/packages/harness/deerflow/community/opensandbox/provider.py @@ -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"], ) diff --git a/backend/packages/harness/deerflow/config/sandbox_config.py b/backend/packages/harness/deerflow/config/sandbox_config.py index b96e58fd58..92765c211e 100644 --- a/backend/packages/harness/deerflow/config/sandbox_config.py +++ b/backend/packages/harness/deerflow/config/sandbox_config.py @@ -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. diff --git a/backend/tests/test_opensandbox_provider.py b/backend/tests/test_opensandbox_provider.py index 412322a4c8..f93362f4e3 100644 --- a/backend/tests/test_opensandbox_provider.py +++ b/backend/tests/test_opensandbox_provider.py @@ -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"): diff --git a/config.example.yaml b/config.example.yaml index 25ca877c70..65b091a110 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -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 diff --git a/deploy/helm/deer-flow/README.md b/deploy/helm/deer-flow/README.md index c4e10d1e00..a0ddf653c5 100644 --- a/deploy/helm/deer-flow/README.md +++ b/deploy/helm/deer-flow/README.md @@ -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 diff --git a/deploy/helm/deer-flow/values.yaml b/deploy/helm/deer-flow/values.yaml index 4ca23cd42c..b71e67452d 100644 --- a/deploy/helm/deer-flow/values.yaml +++ b/deploy/helm/deer-flow/values.yaml @@ -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