docs: add box.default_memory_mb to settings reference and MCP guide (#99)

Co-authored-by: dadachann <[email protected]>

en/deploy/settings.mdx

@@ -129,6 +129,7 @@ box:
             - './data/box'
             - '/tmp'
         workspace_quota_mb: null  # Optional disk quota override (>= 0). null = profile default.
+    default_memory_mb: 1536  # Default nsjail cgroup memory limit per MCP stdio process (MB). Node.js MCP servers (npx/bunx) need more than Python ones due to V8 + WASM overhead. Too low = return_code=137 (OOM). Override per-server with box.memory_mb. Env: BOX__DEFAULT_MEMORY_MB.
     docker:
         cpu_limit_enabled: true  # When false, Docker sandbox containers are started without --cpus. Memory and PID limits still apply.
     e2b:

en/usage/mcp/readme.mdx

@@ -95,6 +95,7 @@ Common fields:
 | `host_path_mode` | Access mode when staging `host_path`; defaults to `ro`. stdio MCP usually stages into the workspace |
 | `startup_timeout_sec` | Box prep + dependency install timeout, default 120s. Connection wait gets about 30s extra |
 | `image` | Runtime image when the Docker backend is used |
+| `memory_mb` | Per-server memory cap (MB); overrides global `box.default_memory_mb` for this server |
 
 <Warning>
 stdio MCP runs inside Box. Dependency install and process startup are subject to the sandbox profile, network permission, resource limits, and the mount allowlist.

en/usage/sandbox/config.mdx

@@ -79,6 +79,24 @@ The local backends (`local` / `docker` / `nsjail`) share these settings:
 | `local.skills_root` | `skills` | Skill package directory; relative paths resolve under `host_root` |
 | `local.allowed_mount_roots` | `[host_root]` | Allowlist of host directories the Agent can mount |
 | `local.workspace_quota_mb` | `null` | Workspace disk quota (MB); `null` = use profile default |
+| `default_memory_mb` | `1536` | Memory limit for each MCP stdio process (MB); overridable via `BOX__DEFAULT_MEMORY_MB` |
+
+## Box Sandbox Memory Configuration
+
+`box.default_memory_mb` sets the nsjail cgroup memory cap for every stdio-mode MCP server process.
+
+| Setting | Notes | Default |
+|---|---|---|
+| `box.default_memory_mb` | MCP process memory cap (MB) | 1536 |
+
+Can be set in config.yaml or via the `BOX__DEFAULT_MEMORY_MB` environment variable.
+
+**When to adjust:**
+- Node.js MCP servers (launched via npx/bunx): V8 + WebAssembly module initialisation needs significant memory; keep at ≥ 1536 MB
+- Python MCP servers (launched via uvx): 512 MB is usually enough, but the default is fine too
+- When memory is exhausted, the process is forcibly killed (return_code=137), logged as "Box managed process exited unexpectedly"
+
+**Per-server override:** Set `box.memory_mb` in the individual MCP server config to override the global default.
 
 ## Docker Backend Configuration (box.docker.*)
 
@@ -149,6 +167,7 @@ box:
 | `BOX__LOCAL__SKILLS_ROOT` | `box.local.skills_root` |
 | `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`, comma-separated |
 | `BOX__LOCAL__WORKSPACE_QUOTA_MB` | `box.local.workspace_quota_mb` |
+| `BOX__DEFAULT_MEMORY_MB` | `box.default_memory_mb` |
 | `BOX__DOCKER__CPU_LIMIT_ENABLED` | `box.docker.cpu_limit_enabled` |
 | `BOX__E2B__API_KEY` | `box.e2b.api_key` |
 | `BOX__E2B__API_URL` | `box.e2b.api_url` |

zh/deploy/settings.mdx

@@ -128,7 +128,8 @@ box:
         allowed_mount_roots:  # 默认为 ['<host_root>']。
             - './data/box'
             - '/tmp'
-        workspace_quota_mb: null  # 可选磁盘配额覆盖 (>= 0)。null 表示使用 profile 默认值。
+        workspace_quota_mb: null  # 可选磁盘配额上限（>=0）。null=套餐默认值。
+    default_memory_mb: 1536  # 每个 MCP stdio 进程的 nsjail cgroup 内存上限（MB）。Node.js 类 MCP（npx/bunx）因 V8+WASM 需要更多内存，过低会导致进程被 OOM 杀死（return_code=137）。可用 BOX__DEFAULT_MEMORY_MB 覆盖。  # 可选磁盘配额覆盖 (>= 0)。null 表示使用 profile 默认值。
     docker:
         cpu_limit_enabled: true  # false 时 Docker 沙箱容器不传 --cpus；内存和 PID 限制仍然生效。
     e2b:

zh/usage/mcp/readme.mdx

@@ -95,6 +95,7 @@ stdio MCP 由 Box Runtime 托管，连接前 LangBot 会：
 | `host_path_mode` | 准备 `host_path` 时的访问模式，默认 `ro`；stdio MCP 通常会先 staging 到工作区 |
 | `startup_timeout_sec` | Box 准备和依赖安装超时，默认 120 秒；连接等待会额外预留约 30 秒 |
 | `image` | Docker 后端使用的运行镜像 |
+| `memory_mb` | 覆盖该服务的内存上限（MB）；优先级高于全局 `box.default_memory_mb` |
 
 <Warning>
 stdio MCP 在 Box 中运行，依赖安装和进程启动受 sandbox profile、网络权限、资源限制和挂载白名单影响。

zh/usage/sandbox/config.mdx

@@ -79,6 +79,24 @@ Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端
 | `local.skills_root` | `skills` | Skill 包目录；相对路径解析到 `host_root` 下 |
 | `local.allowed_mount_roots` | `[host_root]` | Agent 可请求挂载的主机目录白名单 |
 | `local.workspace_quota_mb` | `null` | 工作区磁盘配额（MB），`null` = 用 profile 默认 |
+| `default_memory_mb` | `1536` | MCP stdio 进程内存上限（MB）；可通过 `BOX__DEFAULT_MEMORY_MB` 覆盖 |
+
+## Box 沙箱内存配置
+
+`box.default_memory_mb` 控制每个 stdio 模式 MCP 服务进程的 nsjail cgroup 内存上限。
+
+| 配置项 | 说明 | 默认值 |
+|---|---|---|
+| `box.default_memory_mb` | MCP 进程内存上限（MB）| 1536 |
+
+可通过 config.yaml 或环境变量 `BOX__DEFAULT_MEMORY_MB` 设置。
+
+**为什么需要调整：**
+- Node.js 类 MCP（npx/bunx 启动）：V8 引擎 + WebAssembly 模块初始化需要较多内存，建议 ≥ 1536 MB
+- Python 类 MCP（uvx 启动）：通常 512 MB 已足够，但用默认值也没问题
+- 内存不足时进程会被强制终止（return_code=137），在日志里表现为「Box managed process exited unexpectedly」
+
+**单个 MCP 服务覆盖：** 在 MCP 配置的 `box.memory_mb` 字段单独设置，优先级高于全局默认值。
 
 ## Docker 后端配置（box.docker.*）
 
@@ -149,6 +167,7 @@ box:
 | `BOX__LOCAL__SKILLS_ROOT` | `box.local.skills_root` |
 | `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`，逗号分隔 |
 | `BOX__LOCAL__WORKSPACE_QUOTA_MB` | `box.local.workspace_quota_mb` |
+| `BOX__DEFAULT_MEMORY_MB` | `box.default_memory_mb` |
 | `BOX__DOCKER__CPU_LIMIT_ENABLED` | `box.docker.cpu_limit_enabled` |
 | `BOX__E2B__API_KEY` | `box.e2b.api_key` |
 | `BOX__E2B__API_URL` | `box.e2b.api_url` |