cloudrouter

cloudrouter - 开发云沙箱

cloudrouter 用于管理开发云沙箱。使用这些命令创建、管理和访问支持 GPU 和浏览器自动化的远程开发环境。

调用此技能时

当用户调用 /cloudrouter 或 /cr，但未指定具体任务时，请展示可用模式：

cloudrouter - Cloud Development Sandboxes

  Modes:
    cloudrouter start .                    Sync current directory to a cloud sandbox
    cloudrouter start --size small .       Smaller sandbox (2 vCPU, 8 GB)
    cloudrouter start --gpu T4 .           Sandbox with T4 GPU (16GB VRAM)
    cloudrouter start --gpu A100 .         Sandbox with A100 GPU (40GB VRAM)
    cloudrouter start --gpu H100 .         Sandbox with H100 GPU (80GB VRAM)

  Manage:
    cloudrouter ls                         List all sandboxes
    cloudrouter code <id>                  Open VS Code in browser
    cloudrouter jupyter <id>               Open Jupyter Lab in browser
    cloudrouter pty <id>                   Open terminal session
    cloudrouter vnc <id>                   Open VNC desktop
    cloudrouter stop <id>                  Pause sandbox
    cloudrouter resume <id>                Resume paused sandbox

  Browser automation:
    cloudrouter browser snapshot -i <id>       Get interactive elements
    cloudrouter browser open <id> <url>        Navigate to URL
    cloudrouter browser screenshot <id>        Take screenshot

  Run "cloudrouter start --help" for all options.

设置

在执行任何其他操作之前，每次开始 cloudrouter 任务时都必须先运行此命令。 不要询问用户——直接自动运行：

npm install -g @manaflow-ai/cloudrouter   # Install/update CLI

此命令具有幂等性，即使已是最新版本，也可以安全运行。这可确保 Agent 始终使用最新的 CLI。

这会同时将 cloudrouter 和 cr（简写）安装为 CLI 命令。

然后进行身份验证：

cloudrouter login

如果用户尚未登录，请先提示他们运行 cloudrouter login，然后再使用其他命令。

快速开始

cloudrouter login                        # Authenticate (opens browser)
cloudrouter start .                      # Create sandbox from current directory
cloudrouter start --gpu T4 .             # Create sandbox with GPU
cloudrouter start --size small .         # Create smaller sandbox
cloudrouter code <id>                    # Open VS Code
cloudrouter jupyter <id>                 # Open Jupyter Lab
cloudrouter pty <id>                     # Open terminal session
cloudrouter ls                           # List all sandboxes

首选： 始终使用 cloudrouter start . 或 cloudrouter start <local-path> 将本地目录同步到云沙箱。与从 git 仓库克隆相比，这是推荐的工作流。

命令

身份验证

cloudrouter login               # Login (opens browser)
cloudrouter logout              # Logout and clear credentials
cloudrouter whoami              # Show current user and team

创建沙箱

# Standard sandbox (syncs local directory) — DO NOT pass --size, default is large (8 vCPU, 32 GB)
cloudrouter start .                        # Create from current directory (recommended)
cloudrouter start ./my-project             # Create from a specific local directory
cloudrouter start -o .                     # Create and open VS Code immediately
cloudrouter start -n my-sandbox .          # Create with a custom name

# Size presets — only use if the user specifically requests a different size
cloudrouter start --size small .           # 2 vCPU, 8 GB RAM, 20 GB disk — only if user asks
cloudrouter start --size medium .          # 4 vCPU, 16 GB RAM, 40 GB disk — only if user asks
cloudrouter start --size large .           # 8 vCPU, 32 GB RAM, 80 GB disk (DEFAULT — no flag needed)
cloudrouter start --size xlarge .          # 16 vCPU, 64 GB RAM, 160 GB disk — only if user asks

# With GPU (auto-selects Modal provider)
cloudrouter start --gpu T4 .               # T4 GPU (16GB VRAM)
cloudrouter start --gpu L4 .               # L4 GPU (24GB VRAM)
cloudrouter start --gpu A10G .             # A10G GPU (24GB VRAM)
cloudrouter start --gpu A100 .             # A100 GPU (40GB VRAM) - requires approval
cloudrouter start --gpu H100 .             # H100 GPU (80GB VRAM) - requires approval
cloudrouter start --gpu H100:2 .           # Multi-GPU: 2x H100

# With custom resources (override --size values)
cloudrouter start --cpu 12 --memory 49152 .  # Custom CPU and memory
cloudrouter start --disk 100 .               # Custom disk size (GB)
cloudrouter start --image ubuntu:22.04 .     # Custom container image

# From git repo (URL as positional arg or --git flag)
cloudrouter start https://github.com/user/repo    # Clone git repo directly
cloudrouter start --git user/repo                  # Clone via shorthand
cloudrouter start --git user/repo -b main          # Clone specific branch

# Provider selection
cloudrouter start -p e2b .                 # Use E2B provider (default)
cloudrouter start -p modal .               # Use Modal provider

# Custom timeout (default: 600s = 10 min)
cloudrouter start --timeout 1800 .         # 30-minute timeout — good for standard tasks
cloudrouter start --timeout 7200 --gpu T4 .  # 2-hour timeout — USE FOR GPU/TRAINING TASKS

规格预设

规格	vCPU	内存	磁盘	备注
small	2	8 GB	20 GB	轻量任务
medium	4	16 GB	40 GB	标准开发
large	8	32 GB	80 GB	默认
xlarge	16	64 GB	160 GB	高负载工作

除非用户明确要求特定规格，否则不要传入 --size。 默认规格为 large（8 vCPU、32 GB），适合大多数任务。无必要地使用 --size small 会拖慢构建速度，还可能导致内存不足。

单独的资源参数（--cpu、--memory、--disk）会覆盖 --size 的值。

GPU 选项

GPU	显存	适用场景	可用性
T4	16GB	推理、小型模型微调	自助使用
L4	24GB	推理、图像生成	自助使用
A10G	24GB	中型模型训练	自助使用
L40S	48GB	推理、视频生成	需要审批
A100	40GB	大型模型训练（7B-70B）	需要审批
A100-80GB	80GB	超大型模型	需要审批
H100	80GB	快速训练、研究	需要审批
H200	141GB	最大内存容量	需要审批
B200	192GB	最新一代、前沿模型	需要审批

需要审批的 GPU：请联系 [email protected]。

多 GPU：在 GPU 类型后附加 :N，例如 --gpu H100:2 表示使用 2 块 H100。

所有 start 参数

-n, --name <name>       Name for the sandbox
-o, --open              Open VS Code after creation
    --size <preset>     Machine size: small, medium, large (default), xlarge
    --gpu <type>        GPU type (T4, L4, A10G, L40S, A100, H100, H200, B200)
    --cpu <cores>       CPU cores (overrides --size)
    --memory <MiB>      Memory in MiB (overrides --size)
    --disk <GB>         Disk size in GB (overrides --size)
    --image <image>     Container image (e.g., ubuntu:22.04)
    --git <repo>        Git repository URL or user/repo shorthand
-b, --branch <branch>   Git branch to clone
-p, --provider <name>   Sandbox provider: e2b (default), modal
-T, --template <id>     Template ID — DO NOT use template names from `cloudrouter templates`; use --gpu flags instead
    --timeout <secs>    Sandbox timeout in seconds (default: 600 = 10 minutes; use 7200+ for GPU tasks)

警告： 不要将模板名称（例如 cmux-devbox-base）传给 -T 参数。这些是显示名称，不是有效的模板 ID。

别名： cloudrouter start、cloudrouter create 和 cloudrouter new 的作用相同。

管理沙箱

cloudrouter ls                           # List all sandboxes
cloudrouter ls -p modal                  # List only GPU sandboxes
cloudrouter ls -p e2b                    # List only Docker sandboxes
cloudrouter status <id>                  # Show sandbox details and URLs
cloudrouter stop <id>                    # Pause sandbox (preserves state, can resume)
cloudrouter pause <id>                   # Same as stop — alias
cloudrouter resume <id>                  # Resume a paused sandbox
cloudrouter extend <id>                  # Extend sandbox timeout (default: +1 hour)
cloudrouter extend <id> --seconds 7200   # Extend by 2 hours
cloudrouter delete <id>                  # Delete sandbox permanently
cloudrouter templates                    # List available templates

重要： stop 和 pause 是同一命令——都会保留沙箱状态。使用 resume 恢复已暂停的沙箱。使用 delete（别名：rm、kill）永久销毁沙箱。

不要将 --timeout 与 extend 一起使用——对应的参数是 --seconds。

访问沙箱

cloudrouter code <id>           # Open VS Code in browser
cloudrouter jupyter <id>        # Open Jupyter Lab in browser
cloudrouter vnc <id>            # Open VNC desktop in browser
cloudrouter pty <id>            # Interactive terminal session

使用沙箱

cloudrouter pty <id>                       # Interactive terminal session (use for ongoing work)
cloudrouter ssh <id> <command>             # Execute a one-off command via SSH
cloudrouter ssh <id> "ls -la"              # Run a command (always quote the command string)
cloudrouter pty-list <id>                  # List active PTY sessions

重要： 交互式操作优先使用 cloudrouter pty。快速执行一次性命令时使用 cloudrouter ssh。

关键：始终给命令字符串加引号。 cloudrouter ssh <id> ls -la 会失败，因为 -la 会被解析为 cloudrouter 参数。务必用引号括起来：cloudrouter ssh <id> "ls -la"。

重要：运行任何 npm 命令前修复权限

在新沙箱中运行 npm install 或任何 npm 命令之前，务必先运行此命令：

cloudrouter ssh <id> "sudo chown -R 1000:1000 /home/user/.npm"

否则，npm install 会因 .npm/_cacache 上的 EACCES/ENOENT 错误而失败。每个沙箱只需执行一次，并且必须在首次 npm 操作之前完成。不要跳过此步骤。

文件传输

在本地计算机和沙箱之间上传和下载文件或目录。

命令签名：

• cloudrouter upload <id> [local-path] — 接受 1–2 个位置参数：沙箱 ID 和可选的本地路径
• cloudrouter download <id> [local-path] — 接受 1–2 个位置参数：沙箱 ID 和可选的本地路径
• 使用 -r <remote-path> 标志指定非默认远程目录（默认值：/home/user/workspace）
• 请勿将远程路径作为位置参数传入 — 这会导致错误。请始终使用 -r 标志。

# Upload (local -> sandbox)
cloudrouter upload <id>                            # Upload current dir to /home/user/workspace
cloudrouter upload <id> ./my-project               # Upload directory to workspace
cloudrouter upload <id> ./config.json              # Upload single file to workspace
cloudrouter upload <id> . -r /home/user/app        # Upload to specific remote path
cloudrouter upload <id> . --watch                  # Watch and re-upload on changes
cloudrouter upload <id> . --delete                 # Delete remote files not present locally
cloudrouter upload <id> . -e "*.log"               # Exclude patterns
cloudrouter upload <id> . --dry-run                # Preview without making changes

# Download (sandbox -> local)
cloudrouter download <id>                          # Download workspace to current dir
cloudrouter download <id> ./output                 # Download workspace to ./output
cloudrouter download <id> ./output -r /home/user/app  # Download specific remote dir to ./output

警告： -r 标志需要的是目录路径，而不是文件路径。要下载单个文件，请下载其父目录，然后在本地访问该文件。

常见错误： cloudrouter download <id> /remote/path /local/path — 这会传入 3 个位置参数并导致失败。请改用 cloudrouter download <id> /local/path -r /remote/path。

浏览器自动化（cloudrouter browser）

通过 agent-browser 控制沙箱中的 Chrome 浏览器。cloudrouter browser 命令封装了 agent-browser，并通过 SSH 在沙箱内运行命令。

启动延迟： 沙箱创建后，浏览器可能不会立即就绪。如果 cloudrouter start 后立即执行 browser 命令失败，请等待几秒钟后重试。

导航

cloudrouter browser open <id> <url>        # Navigate to URL
cloudrouter browser back <id>              # Navigate back
cloudrouter browser forward <id>           # Navigate forward
cloudrouter browser reload <id>            # Reload page
cloudrouter browser url <id>               # Get current URL
cloudrouter browser title <id>             # Get page title

检查页面

cloudrouter browser snapshot -i <id>               # Interactive elements only (RECOMMENDED)
cloudrouter browser snapshot <id>                  # Full accessibility tree
cloudrouter browser snapshot -c <id>               # Compact output
cloudrouter browser screenshot <id>                # Take screenshot (base64 to stdout)
cloudrouter browser screenshot <id> out.png        # Save screenshot to file
cloudrouter browser screenshot <id> --full         # Full page screenshot

与元素交互

cloudrouter browser click <id> @e1                 # Click element by ref
cloudrouter browser click <id> "#submit"           # Click by CSS selector
cloudrouter browser dblclick <id> @e1              # Double-click element
cloudrouter browser fill <id> @e2 "[email protected]" # Clear input and fill value
cloudrouter browser type <id> @e3 "some text"      # Type without clearing (appends)
cloudrouter browser press <id> Enter               # Press key (Enter, Tab, Escape, etc.)
cloudrouter browser hover <id> @e4                 # Hover over element
cloudrouter browser focus <id> @e5                 # Focus element
cloudrouter browser scroll <id> down 500           # Scroll (up/down/left/right, optional px)
cloudrouter browser scrollintoview <id> "#element"  # Scroll element into view (CSS selector only, NOT @e refs)
cloudrouter browser select <id> @e7 "option-value" # Select dropdown option
cloudrouter browser check <id> @e8                 # Check checkbox
cloudrouter browser uncheck <id> @e9               # Uncheck checkbox
cloudrouter browser upload <id> @e10 /tmp/file.pdf # Upload file to file input
cloudrouter browser drag <id> @e1 @e2              # Drag and drop

等待命令

cloudrouter browser wait <id> @e1                  # Wait for element to appear
cloudrouter browser wait <id> 2000                 # Wait milliseconds

获取信息

cloudrouter browser get-text <id> @e1              # Get element text content
cloudrouter browser get-value <id> @e2             # Get input value
cloudrouter browser get-attr <id> @e3 href         # Get specific attribute
cloudrouter browser get-html <id> @e4              # Get innerHTML
cloudrouter browser get-count <id> ".item"         # Count matching elements
cloudrouter browser get-box <id> @e5               # Get bounding box
cloudrouter browser is-visible <id> @e1            # Check if element is visible
cloudrouter browser is-enabled <id> @e1            # Check if element is enabled
cloudrouter browser is-checked <id> @e1            # Check if checkbox is checked

语义定位器（refs 的替代方式）

当元素 refs 不可靠时（动态页面），请使用语义定位器：

cloudrouter browser find <id> text "Sign In" click              # Find by visible text and click
cloudrouter browser find <id> label "Email" fill "[email protected]" # Find by label and fill
cloudrouter browser find <id> placeholder "Search" type "query"  # Find by placeholder
cloudrouter browser find <id> testid "submit-btn" click          # Find by data-testid

注意： find <id> role button click 会查找页面上的第一个按钮 — 无法按按钮名称筛选。使用 find <id> text "Button Name" click 可通过可见文本定位特定按钮。没有 --name 标志。

JavaScript 和控制台

cloudrouter browser eval <id> "document.title"                   # Evaluate JavaScript
cloudrouter browser console <id>                                 # View console messages
cloudrouter browser errors <id>                                  # View JavaScript errors

标签页和框架

cloudrouter browser tab-list <id>                  # List open tabs
cloudrouter browser tab-new <id> "https://..."     # Open new tab
cloudrouter browser tab-switch <id> 2              # Switch to tab by index
cloudrouter browser tab-close <id>                 # Close current tab
cloudrouter browser frame <id> "#iframe-selector"  # Switch to iframe
cloudrouter browser frame <id> main                # Switch back to main frame

Cookie 和存储

cloudrouter browser cookies <id>                   # List cookies
cloudrouter browser cookies-set <id> name value    # Set a cookie
cloudrouter browser cookies-clear <id>             # Clear all cookies
cloudrouter browser storage-local <id>             # Get all localStorage
cloudrouter browser storage-local <id> key         # Get specific key
cloudrouter browser storage-local-set <id> k v     # Set localStorage value
cloudrouter browser storage-local-clear <id>       # Clear localStorage

状态管理

cloudrouter browser state-save <id> /tmp/auth.json   # Save cookies, storage, auth state
cloudrouter browser state-load <id> /tmp/auth.json   # Restore saved state

浏览器设置

cloudrouter browser set-viewport <id> 1920 1080    # Set viewport size
cloudrouter browser set-device <id> "iPhone 14"    # Emulate device
cloudrouter browser set-geo <id> 37.7749 -122.4194 # Set geolocation
cloudrouter browser set-offline <id> on            # Toggle offline mode
cloudrouter browser set-media <id> dark            # Emulate color scheme (dark/light)

网络拦截

cloudrouter browser network-route <id> "**/api/*"            # Intercept requests
cloudrouter browser network-route <id> "**/ads/*" --abort    # Block requests
cloudrouter browser network-unroute <id>                     # Remove all routes
cloudrouter browser network-requests <id>                    # List tracked requests

对话框

cloudrouter browser dialog-accept <id>             # Accept alert/confirm/prompt
cloudrouter browser dialog-accept <id> "answer"    # Accept prompt with text
cloudrouter browser dialog-dismiss <id>            # Dismiss dialog

元素选择器

有两种选择元素的方式：

• 来自快照的元素 refs： @e1、@e2、@e3……（首选 — 来自 cloudrouter browser snapshot -i）
• CSS 选择器： #id、.class、button[type="submit"]

快照输出会将 refs 显示为 [ref=e1]，但在命令中使用时，请在前面加上 @：例如，@e1。

高效浏览器自动化的提示

1. 标志必须放在沙盒 ID 之前。 这点至关重要。cloudrouter browser snapshot -i <id> 可以正常工作。cloudrouter browser snapshot <id> -i 会悄悄返回空结果或错误结果。始终将 -i、-c、--full 等标志放在沙盒 ID 之前。

2. 交互前始终先获取快照。 未先运行 cloudrouter browser snapshot -i <id> 时，绝不要使用 @e1。只有获取快照后，引用才会存在。

3. DOM 发生变化后始终重新获取快照。 点击导致页面跳转、打开下拉菜单、提交表单或触发动态内容后，都要重新获取快照。旧引用可能指向不同的元素。

4. 不要混用快照模式。 完整的 snapshot 和 snapshot -i 会为相同元素分配不同的引用编号。如果使用 -i 获取快照，始终使用该 -i 快照中的引用进行交互。上次运行的是 -i 时，不要使用完整快照中的引用，反之亦然。

5. 使用 snapshot -i（仅交互元素）。 -i 标志只返回可操作元素（按钮、输入框、链接），比完整的无障碍树高效得多。所有交互都使用 -i。

6. 表单字段使用 fill，不要使用 type。 fill 会先清除已有内容，这几乎总是你想要的行为。type 会将内容追加到已有内容后。

7. 页面跳转后等待。 点击链接或提交表单后，使用 cloudrouter browser wait <id> 2000，或等待特定元素出现，再获取快照，以确保页面已完全加载。

8. 使用 url / title 验证页面跳转。 点击链接或提交表单后，确认已到达预期页面。

9. 保存身份验证状态以供复用。 登录后，使用 cloudrouter browser state-save <id> /tmp/auth.json 保存 Cookie 和存储数据。之后的会话中使用 state-load 重新加载。

10. 必要时改用语义定位器。 如果页面高度动态，引用总是失效，请使用 cloudrouter browser find <id> text "Submit" click，而不是引用。

注意： cloudrouter browser 命令会通过 SSH 在沙盒内运行 agent-browser。浏览器自动化始终使用 cloudrouter browser 命令。

沙盒 ID

沙盒 ID 的格式类似 cr_abc12345。运行命令时使用完整 ID。可从 cloudrouter ls 或 cloudrouter start 的输出中获取 ID。

常见工作流

在沙盒中创建和开发（首选：本地到云端）

cloudrouter start ./my-project                                      # Creates sandbox, uploads files
cloudrouter ssh cr_abc123 "sudo chown -R 1000:1000 /home/user/.npm" # ⚠ MUST run before any npm command
cloudrouter ssh cr_abc123 "cd /home/user/workspace && npm install"   # Install dependencies
cloudrouter code cr_abc123                                          # Open VS Code
cloudrouter pty cr_abc123                                           # Open terminal (e.g. npm run dev)

GPU 工作流：ML 训练

GPU 任务始终使用较长的超时时间。 训练任务很容易持续数小时。至少使用 --timeout 7200（2 小时）。之后可随时使用 cloudrouter extend <id> 延长超时时间。

cloudrouter start --gpu A100 --timeout 7200 ./ml-project  # 2-hour timeout for training
cloudrouter pty cr_abc123                                  # Open terminal
# Inside: pip install -r requirements.txt && python train.py
cloudrouter extend cr_abc123                               # Extend +1 hour if needed
cloudrouter download cr_abc123 ./checkpoints               # Download trained model

Jupyter 工作流

cloudrouter start ./notebooks         # Create sandbox
cloudrouter jupyter cr_abc123         # Open Jupyter Lab in browser

文件传输工作流

cloudrouter upload cr_abc123 ./my-project     # Push local files to sandbox
# ... do work in sandbox ...
cloudrouter download cr_abc123 ./output       # Pull files from sandbox to local

浏览器自动化：登录网站

cloudrouter browser open cr_abc123 "https://example.com/login"
cloudrouter browser snapshot -i cr_abc123
# Output: @e1 [input type="email"] placeholder="Email"
#         @e2 [input type="password"] placeholder="Password"
#         @e3 [button] "Sign In"

cloudrouter browser fill cr_abc123 @e1 "[email protected]"
cloudrouter browser fill cr_abc123 @e2 "password123"
cloudrouter browser click cr_abc123 @e3
cloudrouter browser wait cr_abc123 2000               # Wait for navigation
cloudrouter browser snapshot -i cr_abc123              # Re-snapshot after navigation!
cloudrouter browser screenshot cr_abc123 /tmp/result.png

浏览器自动化：抓取数据

cloudrouter browser open cr_abc123 "https://example.com/data"
cloudrouter browser wait cr_abc123 2000
cloudrouter browser snapshot -i cr_abc123     # Get interactive elements
cloudrouter browser get-text cr_abc123 @e5    # Extract specific element text
cloudrouter browser screenshot cr_abc123      # Visual capture

暂停和恢复工作流

cloudrouter stop cr_abc123            # Pause (preserves state)
# ... later ...
cloudrouter resume cr_abc123          # Resume where you left off

沙盒生命周期与清理

并发限制： 用户最多可以同时运行 10 个沙盒。如果用户即将达到此限制，请提醒他们并建议清理未使用的沙盒。如果他们需要更高的限制，应联系 [email protected]（达到限制时，CLI 也会显示此消息）。

清理规则——请谨慎操作：

1. 仅操作你在本次会话中创建的沙盒。 切勿停止或删除你未创建或无法识别的沙盒。如果你在 cloudrouter ls 中看到未知沙盒，请不要操作——它们可能属于用户或其他工作流。

2. 清理前先延长运行时间。 停止或删除你创建的沙盒之前，请考虑用户是否可能想检查它。如果你创建了用户应该查看的内容（正在运行的应用、训练好的模型、浏览器自动化结果等），请使用 cloudrouter extend <id> 延长沙盒的运行时间，让用户有时间查看。分享相关 URL（VS Code、VNC、Jupyter 等），以便他们访问。

   • 使用 --seconds <N> 设置自定义时长（默认值为 3600，即 1 小时）。请勿使用 --timeout——extend 不支持该标志。
   • 示例：cloudrouter extend cr_abc123 --seconds 1800 可延长 30 分钟。

3. 默认停止（暂停），而非删除。 除非沙盒显然可以丢弃（例如，未生成任何产物的快速测试），否则优先使用 cloudrouter stop <id>，而不是 cloudrouter delete <id>。已停止的沙盒可以使用 cloudrouter resume <id> 恢复；已删除的沙盒则会永久消失。如果 cloudrouter stop 失败（虚拟机可能已停止运行），沙盒很可能已经停止。只有当用户需要释放沙盒名额时，才可以使用 cloudrouter delete <id> 进行清理；不要主动删除——仅在用户需要更多空间或明确提出要求时删除。

4. 完成后进行清理。 任务完成且用户不再需要沙盒时，请停止它。不要让沙盒无限期运行——它们会占用并发名额。

5. 监控并发情况。 创建新沙盒前，运行 cloudrouter ls 检查正在运行的沙盒数量。如果有 8 个或更多活动沙盒，请提醒用户，并询问是否可以在创建新沙盒前停止其中一些。切勿在不提醒用户的情况下触及限制。

6. 如果达到限制： 告知用户他们已达到 10 个沙盒的并发限制。建议停止不再需要的沙盒。如果他们需要更多容量，请引导他们联系 [email protected] 申请提高限制。

清理工作流：

cloudrouter ls                                   # Check running sandboxes and count
cloudrouter extend cr_abc123                     # Extend by 1 hour (default)
cloudrouter extend cr_abc123 --seconds 3600      # Extend by custom duration
# ... share URLs, let user verify ...
cloudrouter stop cr_abc123                       # Pause when done (can resume later)
cloudrouter delete cr_abc123                     # Delete only if clearly disposable

展示 URL 和截图

在有助于建立信任或验证进度时，主动向用户分享经过身份验证的沙箱 URL 和截图。用户看不到沙箱内部发生的事情，因此向他们展示工作证据很重要。

何时展示 URL：

• 创建沙箱或设置环境后，分享 VS Code URL（cloudrouter code <id>），让用户检查工作区
• 部署或启动服务后，分享 VNC URL（cloudrouter vnc <id>），让用户查看运行情况
• Jupyter 正在运行时，分享 Jupyter URL（cloudrouter jupyter <id>），让用户验证笔记本
• 只要用户可能想自行验证、检查或与沙箱交互，就分享 URL

何时截取并分享截图：

• 完成视觉任务后（例如 UI 更改、Web 应用部署），使用 cloudrouter browser screenshot <id> /tmp/out.png 截图并展示
• 遇到异常或意外情况时，截图让用户确认
• 执行产生可见结果的浏览器自动化步骤后（表单提交、页面导航、登录流程）
• 用户要求你以视觉方式检查或验证某项内容时

**通用规则：**如果你认为用户能从查看工作成果中受益，就展示 URL 或截图。宁可多展示，不要少展示——这有助于建立信任，并让用户及时了解进展。

安全：开发服务器 URL

重要：绝不要分享或输出原始 E2B 端口转发 URL。

当开发服务器在沙箱中运行时（例如，Vite 使用端口 5173，Next.js 使用端口 3000），E2B 会创建可公开访问的 URL，例如 https://5173-xxx.e2b.app。这些 URL 没有身份验证——任何拥有链接的人都可以访问正在运行的应用程序。

规则：

• 绝不要输出类似 https://5173-xxx.e2b.app、https://3000-xxx.e2b.app 或任何 https://<port>-xxx.e2b.app 的 URL
• 绝不要根据沙箱元数据构造或猜测 E2B 端口 URL
• 始终告知用户通过 VNC 查看开发服务器：cloudrouter vnc <id>
• VNC 受令牌身份验证保护（?tkn=），是查看开发服务器输出的唯一安全方式
• 可以分享经过身份验证的 URL：VS Code（cloudrouter code <id>）、VNC（cloudrouter vnc <id>）、Jupyter（cloudrouter jupyter <id>）——这些 URL 具有适当的令牌身份验证，可以安全展示

启动开发服务器时：

Dev server running on port 5173
  View it in your sandbox's VNC desktop: cloudrouter vnc <id>
  (The browser inside VNC can access http://localhost:5173)

绝不要这样做：

Frontend: https://5173-xxx.e2b.app   <- WRONG: publicly accessible, no auth

常见问题与解决方法

问题	解决方法
npm install 因 EACCES/ENOENT 错误而失败	在新沙盒中运行任何 npm 命令前，务必先运行 cloudrouter ssh <id> "sudo chown -R 1000:1000 /home/user/.npm"
cloudrouter ssh <id> ls -la 因“unknown flag”而失败	始终将命令放在引号中：cloudrouter ssh <id> "ls -la"
snapshot <id> -i 返回空结果或错误结果	标志要放在 ID 前面：snapshot -i <id>
start 后立即执行浏览器命令失败	等待几秒钟——Chrome 需要时间启动
find ... role button click 点击了错误的按钮	使用 find ... text "Button Name" click，按可见文本定位
extend --timeout 300 失败	使用 --seconds：extend <id> --seconds 300
snapshot 中的 Refs 与 snapshot -i 中的不匹配	不要混用模式——交互时坚持使用 snapshot -i
开发服务器正在运行，但无法访问	使用 cloudrouter browser open <id> "http://localhost:PORT"——不要公开 E2B 端口 URL
长时间运行的 ssh 命令卡住	交互式或长时间运行的命令请使用 cloudrouter pty；ssh 适用于快速的一次性操作
scrollintoview @e1 因“Unsupported token”而失败	scrollintoview 和 highlight 只接受 CSS 选择器（例如 "#id"、".class"），不接受 @e refs
pkill -f 终止了 SSH 会话（退出代码 143/255）	pkill -f 的模式可能会匹配 SSH 会话。只需再运行一条 ssh 命令即可恢复
pdf 命令将文件保存到远程路径	文件会保存在沙盒内（例如 /tmp/page.pdf）。使用 cloudrouter download 将其下载到本地
storage-local <id> key 显示“Done”而非值	使用 eval <id> "localStorage.getItem('key')"，以可靠地获取特定的 localStorage 值
DOM 更改后出现过期 ref 错误	点击或提交表单后务必重新进行快照。错误中的“timed out”表示 ref 已过期
cloudrouter stop 失败／沙盒无法访问	VM 可能已停止。如果需要释放沙盒配额，请使用 cloudrouter delete <id> 清理
通过 ssh 运行 create-next-app 时卡住	ssh 不支持交互式提示。请使用 pty 运行交互式安装程序，或通过管道传入输入

全局标志

-t, --team <team>   Team slug (overrides default)
-v, --verbose       Verbose output