From 4cdce9413add0116536a81520c67de912f21eb3e Mon Sep 17 00:00:00 2001 From: Hyu Date: Sat, 4 Jul 2026 16:39:18 +0800 Subject: [PATCH] docs: add box.default_memory_mb to settings reference and MCP guide (#99) Co-authored-by: dadachann <185672915+dadachann@users.noreply.github.com> --- en/deploy/settings.mdx | 1 + en/usage/mcp/readme.mdx | 1 + en/usage/sandbox/config.mdx | 19 +++++++++++++++++++ zh/deploy/settings.mdx | 3 ++- zh/usage/mcp/readme.mdx | 1 + zh/usage/sandbox/config.mdx | 19 +++++++++++++++++++ 6 files changed, 43 insertions(+), 1 deletion(-) diff --git a/en/deploy/settings.mdx b/en/deploy/settings.mdx index 6b13344bb..53425d5f6 100644 --- a/en/deploy/settings.mdx +++ b/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: diff --git a/en/usage/mcp/readme.mdx b/en/usage/mcp/readme.mdx index 782003d41..756e8d619 100644 --- a/en/usage/mcp/readme.mdx +++ b/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 | stdio MCP runs inside Box. Dependency install and process startup are subject to the sandbox profile, network permission, resource limits, and the mount allowlist. diff --git a/en/usage/sandbox/config.mdx b/en/usage/sandbox/config.mdx index 0e4a1da82..a3bbc6496 100644 --- a/en/usage/sandbox/config.mdx +++ b/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` | diff --git a/zh/deploy/settings.mdx b/zh/deploy/settings.mdx index f21aaf430..e9bd09096 100644 --- a/zh/deploy/settings.mdx +++ b/zh/deploy/settings.mdx @@ -128,7 +128,8 @@ box: allowed_mount_roots: # 默认为 ['']。 - './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: diff --git a/zh/usage/mcp/readme.mdx b/zh/usage/mcp/readme.mdx index af59535ff..2b5beb89d 100644 --- a/zh/usage/mcp/readme.mdx +++ b/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` | stdio MCP 在 Box 中运行，依赖安装和进程启动受 sandbox profile、网络权限、资源限制和挂载白名单影响。 diff --git a/zh/usage/sandbox/config.mdx b/zh/usage/sandbox/config.mdx index 826b851bf..898671540 100644 --- a/zh/usage/sandbox/config.mdx +++ b/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` |