dev-server-sandbox

用途

dev-server-sandbox 用于解决 xum 开发服务器无法在同一根目录下并行运行的问题。make dev-server 启动的 xum 后端服务器使用锁文件 <XUM_ROOT>/server.lock（开发环境默认位于 ~/.xum-dev/server.lock），因此每个 xum 根目录只能运行一个开发服务器。该技能通过为每个实例分配独立的临时 XUM_ROOT，支持并行启动多个 dev-server 实例，包括来自不同 git worktree 的实例。

主要能力

创建全新的临时 XUM_ROOT 目录。
在存在时复制以下文件到沙箱（除非被标志禁用）：
- providers.jsonc（provider 配置）
- config.json（项目列表）
- 每个文件独立地从第一个包含它的根目录播种（依次为 $XUM_ROOT、遗留的 $MUX_ROOT、~/.xum[-dev]、遗留的 ~/.mux[-dev] / ~/.cmux），因此只有 config.json 的根目录不会丢失 provider 配置。
在 provider 凭据环境变量可能静默覆盖或与预期设置不匹配时，将其从服务器环境中剥离：使用 --clean-providers 时剥离全部（包括 Bedrock 的 AWS_REGION 和 AWS_BEARER_TOKEN_BEDROCK；共享 AWS 凭据如 AWS_PROFILE 保留）；否则仅剥离那些会遮蔽已播种的 providers.jsonc 条目（该条目有 apiKey 但无显式 baseUrl）的 *_BASE_URL 环境变量（API key 环境变量始终保留，以便环境密钥回退仍然有效）。
选择空闲端口（BACKEND_PORT、VITE_PORT）。
默认在沙箱内禁用教程（设置 XUM_ENABLE_TUTORIALS_IN_SANDBOX=1 可重新启用）。
允许所有主机（VITE_ALLOWED_HOSTS=all），以便在端口转发域名后正常工作。
使用上述环境覆盖运行 make dev-server。

使用方式

快速开始：

make dev-server-sandbox

在智能体中使用 bash.monitor：当需要沙箱在继续或结束回合时保持运行，可将其作为受监控的后台 bash 启动。监控器会在服务器输出有用信息时唤醒工作区；仅在需要周边日志时调用 task_await。

bash({
  script: "make dev-server-sandbox",
  display_name: "Dev Server Sandbox",
  run_in_background: true,
  timeout_secs: 1800,
  monitor: {
    filter: "ready|listening|localhost|ERROR|EADDRINUSE|failed|Failed",
    cooldown_ms: 1000,
    max_events: 3,
  },
});

此方式适用于面向行的服务器就绪/错误信息。对于外部状态轮询（PR 检查、部署健康、远程 CI），应改用后台任务/工作流监控器。

选项

# 以干净实例启动（不复制 providers 或 projects）
make dev-server-sandbox DEV_SERVER_SANDBOX_ARGS="--clean-providers --clean-projects"

# 跳过复制 providers.jsonc
make dev-server-sandbox DEV_SERVER_SANDBOX_ARGS="--clean-providers"

# 从 config.json 中清除项目（保留其他配置）
make dev-server-sandbox DEV_SERVER_SANDBOX_ARGS="--clean-projects"

# 使用特定根目录进行播种（默认：按文件从 $XUM_ROOT、遗留 $MUX_ROOT、~/.xum[-dev]、遗留 ~/.mux[-dev] / ~/.cmux）
SEED_XUM_ROOT=~/.xum-dev make dev-server-sandbox

# 退出后保留沙箱根目录（便于调试）
KEEP_SANDBOX=1 make dev-server-sandbox

# 固定端口（必须不同）
BACKEND_PORT=3001 VITE_PORT=5174 make dev-server-sandbox

# 为沙箱 dogfooding 重新启用教程
XUM_ENABLE_TUTORIALS_IN_SANDBOX=1 make dev-server-sandbox

# 覆盖使用的 make 二进制文件
MAKE=gmake make dev-server-sandbox

适用场景

需要同时运行多个 xum 开发服务器实例进行并行开发或测试。
从不同 git worktree 启动开发服务器。
在智能体工作流中作为受监控的后台任务运行开发服务器。

限制与安全说明

providers.jsonc 可能包含 API 密钥。
沙箱根目录会创建在磁盘上（通常位于系统临时目录下）。
此流程有意不复制 secrets.json。
关于收费、价格、平台支持等具体信息，资料中暂未提供。

技能介绍

用途

主要能力

使用方式

选项

适用场景

限制与安全说明