From 6287efde18f1502f46e999fcb603f71388c9cce9 Mon Sep 17 00:00:00 2001
From: Yongteng Lei <yongtengrey@outlook.com>
Date: Mon, 16 Jun 2025 13:41:27 +0800
Subject: [PATCH] Docs: add sandbox FAQ (#8284)

### What problem does this PR solve?

Add sandbox FAQ.

#7699 #7973 #8049 #8196 #8226.

### Type of change

- [x] Documentation Update
- [x] Refactoring
---
 sandbox/.env.example       |  9 +++++
 sandbox/Makefile           |  1 +
 sandbox/README.md          | 73 ++++++++++++++++++++++++++++++++++++++
 sandbox/docker-compose.yml |  2 ++
 4 files changed, 85 insertions(+)
 create mode 100644 sandbox/.env.example

diff --git a/sandbox/.env.example b/sandbox/.env.example
new file mode 100644
index 000000000..e88ed561c
--- /dev/null
+++ b/sandbox/.env.example
@@ -0,0 +1,9 @@
+# Copy this file to `.env` and modify as needed
+
+SANDBOX_EXECUTOR_MANAGER_POOL_SIZE=5
+SANDBOX_BASE_PYTHON_IMAGE=sandbox-base-python:latest
+SANDBOX_BASE_NODEJS_IMAGE=sandbox-base-nodejs:latest
+SANDBOX_EXECUTOR_MANAGER_PORT=9385
+SANDBOX_ENABLE_SECCOMP=false
+SANDBOX_MAX_MEMORY=256m # b, k, m, g
+SANDBOX_TIMEOUT=10s # s, m, 1m30s
diff --git a/sandbox/Makefile b/sandbox/Makefile
index 6258b6456..da07da2b7 100644
--- a/sandbox/Makefile
+++ b/sandbox/Makefile
@@ -32,6 +32,7 @@ all: setup start
 # 🌱 Initialize environment + install dependencies
 setup: ensure_env ensure_uv
 	@echo "📦 Installing dependencies with uv..."
+	@$(UV) sync --python 3.11
 	source $(ACTIVATE_SCRIPT) && \
 	export PYTHONPATH=$(PYTHONPATH)
 	@$(UV) pip install -r executor_manager/requirements.txt
diff --git a/sandbox/README.md b/sandbox/README.md
index a0f421688..2e4e209ff 100644
--- a/sandbox/README.md
+++ b/sandbox/README.md
@@ -213,6 +213,79 @@ To add Node.js dependencies:
 
 ---
 
+## 📋 FAQ
+
+### ❓Sandbox Not Working?
+
+Follow this checklist to troubleshoot:
+
+- [ ] **Is your machine compatible with gVisor?**
+
+  Ensure that your system supports gVisor. Refer to the [gVisor installation guide](https://gvisor.dev/docs/user_guide/install/).
+
+- [ ] **Is gVisor properly installed?**
+
+  **Common error:**
+
+  `HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Read timed out.`
+
+  Cause: `runsc` is an unknown or invalid Docker runtime.
+  **Fix:**
+
+  - Install gVisor
+
+  - Restart Docker
+
+  - Test with:
+
+    ```bash
+    docker run --rm --runtime=runsc hello-world
+    ```
+
+- [ ] **Is `sandbox-executor-manager` mapped in `/etc/hosts`?**
+
+  **Common error:**
+
+  `HTTPConnectionPool(host='none', port=9385): Max retries exceeded.`
+
+  **Fix:**
+
+  Add the following entry to `/etc/hosts`:
+
+  ```text
+  127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager
+  ```
+
+- [ ] **Have you enabled sandbox-related configurations in RAGFlow?**
+
+  Double-check that all sandbox settings are correctly enabled in your RAGFlow configuration.
+
+- [ ] **Have you pulled the required base images for the runners?**
+
+  **Common error:**
+
+  `HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Read timed out.`
+
+  Cause: no runner was started.
+
+  **Fix:**
+
+  Pull the necessary base images:
+
+  ```bash
+  docker pull infiniflow/sandbox-base-nodejs:latest
+  docker pull infiniflow/sandbox-base-python:latest
+  ```
+
+- [ ] **Did you restart the service after making changes?**
+
+  Any changes to configuration or environment require a full service restart to take effect.
+
+
+### ❓Container pool is busy?
+
+All available runners are currently in use, executing tasks/running code. Please try again shortly, or consider increasing the pool size in the configuration to improve availability and reduce wait times.
+
 ## 🤝 Contribution
 
 Contributions are welcome!
diff --git a/sandbox/docker-compose.yml b/sandbox/docker-compose.yml
index 69176542c..445fdac72 100644
--- a/sandbox/docker-compose.yml
+++ b/sandbox/docker-compose.yml
@@ -21,6 +21,8 @@ services:
       - SANDBOX_BASE_PYTHON_IMAGE=${SANDBOX_BASE_PYTHON_IMAGE-"sandbox-base-python:latest"}
       - SANDBOX_BASE_NODEJS_IMAGE=${SANDBOX_BASE_NODEJS_IMAGE-"sandbox-base-nodejs:latest"}
       - SANDBOX_ENABLE_SECCOMP=${SANDBOX_ENABLE_SECCOMP:-false}
+      - SANDBOX_MAX_MEMORY=${SANDBOX_MAX_MEMORY:-256m} # b, k, m, g
+      - SANDBOX_TIMEOUT=${SANDBOX_TIMEOUT:-10s} # s, m, 1m30s
     healthcheck:
       test: ["CMD-SHELL", "curl --fail http://localhost:9385/healthz || exit 1"]
       interval: 10s