Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

docs(sandbox): describe how the container pool is actually sized (#18625)

MarMar Labs407ec2c86641
diff --git a/agent/sandbox/providers/self_managed.py b/agent/sandbox/providers/self_managed.py
index 85e02cb424..ceb16cca93 100644
--- a/agent/sandbox/providers/self_managed.py
+++ b/agent/sandbox/providers/self_managed.py
@@ -56,7 +56,7 @@ class SelfManagedProvider(SandboxProvider):
- endpoint: HTTP endpoint (default: "http://sandbox-executor-manager:9385")
- timeout: Request timeout in seconds (default: 30)
- max_retries: Maximum retry attempts (default: 3)
- - pool_size: Container pool size for info (default: 10)
+ - pool_size: Container pool size for info (default: 3)
Returns:
True if initialization successful, False otherwise
diff --git a/agent/sandbox/sandbox_spec.md b/agent/sandbox/sandbox_spec.md
index fe7c699af0..afb559a9c9 100644
--- a/agent/sandbox/sandbox_spec.md
+++ b/agent/sandbox/sandbox_spec.md
@@ -133,12 +133,18 @@ Wraps the existing executor_manager implementation. The implementation file is l
docker pull infiniflow/sandbox-base-nodejs:latest
```
-**Configuration**: Docker API endpoint, pool size, resource limits:
+**Configuration**: Docker API endpoint, request behavior, resource limits:
- `endpoint`: HTTP endpoint (default: "http://sandbox-executor-manager:9385")
- `timeout`: Request timeout in seconds (default: 30)
- `max_retries`: Maximum retry attempts (default: 3)
-- `pool_size`: Container pool size (default: 10)
+
+The container pool is **not** sized from this configuration. sandbox-executor-manager reads
+`SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` from its environment once at startup
+(`agent/sandbox/executor_manager/core/config.py`), so changing the pool size is a deployment
+change that requires restarting that service. A `pool_size` key passed to the provider is carried
+for reporting only — `get_info()` echoes it back — and reloading `sandbox.self_managed` recreates
+the RAGFlow-side client without resizing anything.
**Languages**:
- Python
@@ -162,7 +168,7 @@ Wraps the existing executor_manager implementation. The implementation file is l
- Pool exhaustion causes "Container pool is busy" errors
**Common issues**:
-- `"Container pool is busy"`: Increase `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` (default: 1 in .env, should be 5+)
+- `"Container pool is busy"`: Raise `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` above the baseline your deployment already applies — 5 with the standalone compose file, 3 in the main RAGFlow stack
- `Container creation fails`: Ensure gVisor is installed and accessible at `/usr/local/bin/runsc`
#### 2.2.2 Aliyun code interpreter provider
@@ -507,7 +513,7 @@ Each provider's configuration is stored as a **single JSON object** in the `valu
"name": "sandbox.self_managed",
"source": "variable",
"data_type": "json",
- "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"pool_size\": 10, \"max_memory\": \"256m\", \"timeout\": 30}"
+ "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"max_memory\": \"256m\", \"timeout\": 30}"
}
```
@@ -608,12 +614,19 @@ class SelfManagedProvider(SandboxProvider):
"label": "API Endpoint",
"placeholder": "http://sandbox-executor-manager:9385"
},
- "pool_size": {
+ # Deployment-level: the pool is sized by SANDBOX_EXECUTOR_MANAGER_POOL_SIZE in the
+ # sandbox-executor-manager environment, not by this field, and the UI renders it
+ # read-only. The default below is read from the RAGFlow server's own environment and
+ # falls back to 3, so it can disagree with the manager's actual pool. The standalone
+ # compose file starts that service with 5, and the manager's own in-code fallback is 1.
+ "executor_manager_pool_size": {
"type": "integer",
- "default": 10,
+ "default": int(os.getenv("SANDBOX_EXECUTOR_MANAGER_POOL_SIZE", "3")),
"label": "Container Pool Size",
"min": 1,
- "max": 100
+ "max": 100,
+ "scope": "deployment",
+ "readonly": True
},
"max_memory": {
"type": "string",
@@ -1538,7 +1551,7 @@ PROVIDER_CLASSES = {
"name": "sandbox.self_managed",
"source": "variable",
"data_type": "json",
- "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"pool_size\": 20, \"max_memory\": \"512m\", \"timeout\": 60, \"enable_seccomp\": true, \"enable_ast_analysis\": true}"
+ "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"max_memory\": \"512m\", \"timeout\": 60, \"enable_seccomp\": true, \"enable_ast_analysis\": true}"
},
{
"name": "sandbox.aliyun_codeinterpreter",
@@ -1563,7 +1576,6 @@ PROVIDER_CLASSES = {
"provider_type": "self_managed",
"config": {
"endpoint": "http://sandbox-executor-manager:9385",
- "pool_size": 20,
"max_memory": "512m",
"timeout": 60,
"enable_seccomp": true,
@@ -1584,7 +1596,6 @@ PROVIDER_CLASSES = {
"active": "self_managed",
"self_managed": {
"endpoint": "http://sandbox-executor-manager:9385",
- "pool_size": 20,
"max_memory": "512m",
"timeout": 60,
"enable_seccomp": true,
diff --git a/agent/sandbox/tests/test_providers.py b/agent/sandbox/tests/test_providers.py
index a85e23eb76..9cde83d206 100644
--- a/agent/sandbox/tests/test_providers.py
+++ b/agent/sandbox/tests/test_providers.py
@@ -120,7 +120,7 @@ class TestSelfManagedProvider:
assert provider.endpoint == "http://sandbox-executor-manager:9385"
assert provider.timeout == 30
assert provider.max_retries == 3
- assert provider.pool_size == 10
+ assert provider.pool_size == 3
assert not provider._initialized
@patch("requests.get")
@@ -322,8 +322,9 @@ class TestSelfManagedProvider:
assert "nodejs" in languages
assert "javascript" in languages
- def test_get_config_schema(self):
+ def test_get_config_schema(self, monkeypatch):
"""Test getting configuration schema."""
+ monkeypatch.delenv("SANDBOX_EXECUTOR_MANAGER_POOL_SIZE", raising=False)
schema = SelfManagedProvider.get_config_schema()
assert "endpoint" in schema
@@ -335,11 +336,31 @@ class TestSelfManagedProvider:
assert schema["timeout"]["type"] == "integer"
assert schema["timeout"]["default"] == 30
- assert "max_retries" in schema
- assert schema["max_retries"]["type"] == "integer"
-
- assert "pool_size" in schema
- assert schema["pool_size"]["type"] == "integer"
+ # The pool size is a deployment-level fact, not a writable runtime field, so the schema
+ # exposes it read-only under its real key. The default it reports is read from this
+ # process's own environment and falls back to 3, which can disagree with the pool
+ # sandbox-executor-manager was actually started with. Asserting a writable `pool_size`
+ # pinned a shape the provider has never returned, and the assertion failed rather than
+ # guarding anything.
+ assert "executor_manager_pool_size" in schema
+ assert schema["executor_manager_pool_size"]["type"] == "integer"
+ assert schema["executor_manager_pool_size"]["scope"] == "deployment"
+ assert schema["executor_manager_pool_size"]["readonly"] is True
+ assert schema["executor_manager_pool_size"]["default"] == 3
+ assert isinstance(schema["executor_manager_pool_size"]["default"], int)
+ assert "pool_size" not in schema
+
+ # `max_retries` is documented, accepted and range-checked by the provider
+ # (`self_managed.py:58`, `:66`, `:386`) but get_config_schema() does not offer it, so the
+ # admin form cannot set it. The assertion here used to require it and had been failing;
+ # recording its absence keeps that gap visible rather than deleting the observation, and
+ # turns red the moment the schema grows the field.
+ assert "max_retries" not in schema
+
+ monkeypatch.setenv("SANDBOX_EXECUTOR_MANAGER_POOL_SIZE", "11")
+ schema = SelfManagedProvider.get_config_schema()
+ assert schema["executor_manager_pool_size"]["default"] == 11
+ assert isinstance(schema["executor_manager_pool_size"]["default"], int)
def test_normalize_language_python(self):
"""Test normalizing Python language identifier."""
diff --git a/conf/system_settings.json b/conf/system_settings.json
index 78d154b0bd..e2700a1c16 100644
--- a/conf/system_settings.json
+++ b/conf/system_settings.json
@@ -70,7 +70,7 @@
"name": "sandbox.self_managed",
"source": "variable",
"data_type": "json",
- "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"timeout\": 30, \"max_retries\": 3, \"pool_size\": 10}"
+ "value": "{\"endpoint\": \"http://sandbox-executor-manager:9385\", \"timeout\": 30, \"max_retries\": 3}"
},
{
"name": "sandbox.aliyun_codeinterpreter",