Back to Details

dev-desktop-sandbox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Desktop (Electron) sandbox instances

桌面（Electron）沙箱实例

make dev
+ 
make start
(Electron) uses 
MUX_ROOT
for persisted state (config, sessions, worktrees, etc.). Running multiple Electron instances against the same mux root is noisy and risky during development.
This skill documents the repo workflow for starting multiple desktop dev instances in parallel (including from different git worktrees) by giving each instance its own temporary 
MUX_ROOT
.
make dev
+ 
make start
（Electron）使用
MUX_ROOT
来存储持久化状态（配置、会话、工作树等）。在开发过程中，针对同一个Mux根目录运行多个Electron实例会产生干扰且存在风险。
本技能文档记录了仓库的工作流，通过为每个实例分配独立的临时
MUX_ROOT
，实现并行启动多个桌面开发实例（包括来自不同Git工作树的实例）。

Quick start

快速开始

bash
make dev-desktop-sandbox
bash
make dev-desktop-sandbox

What it does

功能说明

  • Creates a fresh temporary 
    MUX_ROOT
    directory
  • Copies these files into the sandbox if present (unless disabled by flags): 
    • providers.jsonc
      (provider config)
    • config.json
      (project list)
  • Picks free ports:
    • Vite devserver port (used by the renderer)
    • Electron remote debugging port (optional)
  • Runs 
    make dev
    with: 
    • MUX_ROOT=<temp>
    • MUX_VITE_PORT=<free-port>
  • Waits for Vite to be reachable, then runs 
    make build-static
    (Electron expects 
    dist/splash.html
    )
  • Launches Electron (
    bunx electron .
    ) with: 
    • MUX_ROOT=<temp>
    • MUX_DEVSERVER_HOST=127.0.0.1
    • MUX_DEVSERVER_PORT=<vite-port>
    • MUX_SERVER_PORT=0
      by default (avoids 
      EADDRINUSE
      if your 
      config.json
      pins 
      apiServerPort
      )
    • CMUX_ALLOW_MULTIPLE_INSTANCES=1
      (so you can run alongside another dev instance)
  • 创建全新的临时
    MUX_ROOT
    目录
  • 如果存在以下文件，则将其复制到沙箱中（可通过标志禁用）： 
    • providers.jsonc
      （提供商配置）
    • config.json
      （项目列表）
  • 选择空闲端口：
    • Vite开发服务器端口（供渲染器使用）
    • Electron远程调试端口（可选）
  • 运行
    make dev
    并携带以下参数： 
    • MUX_ROOT=<temp>
    • MUX_VITE_PORT=<free-port>
  • 等待Vite服务可达后，运行
    make build-static
    （Electron需要
    dist/splash.html
    文件）
  • 启动Electron（
    bunx electron .
    ）并携带以下参数： 
    • MUX_ROOT=<temp>
    • MUX_DEVSERVER_HOST=127.0.0.1
    • MUX_DEVSERVER_PORT=<vite-port>
    • 默认
      MUX_SERVER_PORT=0
      （避免当你的
      config.json
      固定了
      apiServerPort
      时出现
      EADDRINUSE
      错误）
    • CMUX_ALLOW_MULTIPLE_INSTANCES=1
      （允许与其他开发实例同时运行）

Options

可选参数

bash
undefined
bash
undefined

Start with a clean instance (do not copy providers or projects)

启动干净的实例（不复制提供商或项目配置）

make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers --clean-projects"
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers --clean-projects"

Skip copying providers.jsonc

跳过复制providers.jsonc

make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers"
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-providers"

Clear projects from config.json (preserves other config)

清空config.json中的项目（保留其他配置）

make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-projects"
make dev-desktop-sandbox DEV_DESKTOP_SANDBOX_ARGS="--clean-projects"

Use a specific root to seed from (defaults to $MUX_ROOT then ~/.mux-dev then ~/.mux)

使用指定的根目录作为种子（默认为$MUX_ROOT，其次是~/.mux-dev，最后是~/.mux）

SEED_MUX_ROOT=~/.mux-dev make dev-desktop-sandbox
SEED_MUX_ROOT=~/.mux-dev make dev-desktop-sandbox

Keep the sandbox root directory after exit (useful for debugging)

退出后保留沙箱根目录（便于调试）

KEEP_SANDBOX=1 make dev-desktop-sandbox
KEEP_SANDBOX=1 make dev-desktop-sandbox

Pin Vite port

固定Vite端口

VITE_PORT=5174 make dev-desktop-sandbox
VITE_PORT=5174 make dev-desktop-sandbox

Control how long we wait for Vite to come up (ms)

控制等待Vite启动的时长（毫秒）

VITE_READY_TIMEOUT_MS=120000 make dev-desktop-sandbox
VITE_READY_TIMEOUT_MS=120000 make dev-desktop-sandbox

Enable/pin Electron remote debugging port (defaults to an auto-picked free port)

启用/固定Electron远程调试端口（默认为自动选择的空闲端口）

ELECTRON_DEBUG_PORT=9223 make dev-desktop-sandbox
ELECTRON_DEBUG_PORT=9223 make dev-desktop-sandbox

Disable Electron remote debugging entirely

完全禁用Electron远程调试

ELECTRON_DEBUG_PORT=0 make dev-desktop-sandbox
ELECTRON_DEBUG_PORT=0 make dev-desktop-sandbox

Override the internal API server port (defaults to 0/random for sandboxes)

覆盖内部API服务器端口（沙箱中默认为0/随机端口）

MUX_SERVER_PORT=3772 make dev-desktop-sandbox
MUX_SERVER_PORT=3772 make dev-desktop-sandbox

Override which make binary to use

覆盖使用的make二进制文件

MAKE=gmake make dev-desktop-sandbox
undefined
MAKE=gmake make dev-desktop-sandbox
undefined

Optional: deeper Electron isolation (
MUX_E2E=1
)

可选：更深层次的Electron隔离（
MUX_E2E=1
）

Even with a unique 
MUX_ROOT
, Electron's 
userData
directory (localStorage, window state, single-instance lock, etc.) is not automatically relocated unless 
MUX_E2E=1
is set.
If you want full isolation (including 
userData
), run:
bash
MUX_E2E=1 make dev-desktop-sandbox
即使使用了唯一的
MUX_ROOT
，Electron的
userData
目录（包含localStorage、窗口状态、单实例锁等）也不会自动迁移，除非设置了
MUX_E2E=1
。
如果需要完全隔离（包括
userData
），请运行：
bash
MUX_E2E=1 make dev-desktop-sandbox

Security notes

安全注意事项

  • providers.jsonc
    may contain API keys.
  • The sandbox root directory is created on disk (usually under your system temp dir).
  • This flow intentionally does not copy 
    secrets.json
    .
  • providers.jsonc
    可能包含API密钥。
  • 沙箱根目录会创建在磁盘上（通常位于系统临时目录下）。
  • 本工作流特意不复制
    secrets.json
    文件。