@tcb-sandbox/cli

TRW 的官方命令行工具：一种安装，两种用法。

安装

npm install -g @tcb-sandbox/cli
# 或
pnpm add -g @tcb-sandbox/cli

两种用法

| 用法 | 命令 | 说明 | |------|------|------| | 本地起服务 | tcb-sandbox serve | 启动内置 TRW，默认 http://127.0.0.1:9000 | | 只当客户端 | tcb-sandbox <tool> | 调用已有 TRW（远端或本地） |

快速开始

# 1. 起一个本地 sandbox（从一个目录初始化 workspace）
tcb-sandbox serve --cow-source ~/src/my-project

# 2. 后面就像远程一样用它
tcb-sandbox --endpoint http://127.0.0.1:9000 health
tcb-sandbox --endpoint http://127.0.0.1:9000 bash "npm test"
tcb-sandbox --endpoint http://127.0.0.1:9000 read README.md

# 3. 收尾时再做本地实验管理
tcb-sandbox local status
tcb-sandbox local apply

本地受管工作副本

本地模式现在支持一个 workspace-internal local workflow。目标不是改动远端语义，而是让 serve 起出来的 workspace 在本机自洽工作，所有本地改动都留在这个 workspace 里。

1. serve --cow-source 起一个本地 sandbox
2. 后面主要通过 http / mcp / 现有 CLI 像远程一样使用
3. 只有在看改动、收改动、分叉实验时，才进入 local ... 子命令

# 从一个目录初始化 / 复用 workspace，再起本地 TRW
tcb-sandbox serve --cow-source ~/src/my-project

# 查看当前副本相对 sandbox baseline 的改动
tcb-sandbox local status --output json

# 将当前 workspace 状态吸收到 sandbox 根
tcb-sandbox local apply

# 丢弃副本改动，按 sandbox baseline 重建
tcb-sandbox local discard

# 从当前副本创建 checkpoint，再分叉两条方案
tcb-sandbox local checkpoint create base
tcb-sandbox local branch create base plan-a
tcb-sandbox local branch create base plan-b

# 直接起某个 branch 的本地 TRW
tcb-sandbox local branch serve plan-a

语义：

• --cow-source <path>：指定用来初始化 workspace 内容的目录
• --workspace-root <path>：指定 workspace 目录；不传时默认 ~/.tcb-sandbox/workspace/<basename>-cow
• 受管 workspace 自带 .tcb-sandbox-local-mode.json 和 .tcb-sandbox-local/，它们是本地状态的唯一权威
• local ...：不传 workspace 参数时，优先取当前目录中的受管 workspace；否则回退到 HOME 下最近一次 serve/local ... 使用过的 .tcb-sandbox-local-active.json 指针
• local ...：全部是 local-only 命令，不走 TRW HTTP API
• local checkpoint create：把当前 workspace 内容冻结到 serve 根作用域 下
• local branch create：始终从 serve 根作用域 的 checkpoint 派生新 branch workspace
• local apply / local branch apply：只会把状态吸收到 sandbox 根 workspace，不会回写 --cow-source
• local branch serve：直接对某个 branch 起本地 TRW
• 这版实现是 workspace 内部管理，不是内核级 overlayfs；边界干净，平台依赖低

环境变量

export TCB_SANDBOX_ENDPOINT=https://your-gateway.com
export TCB_SANDBOX_HEADERS_JSON='{"X-Trace-Id":"demo"}'

# 然后可直接使用
tcb-sandbox health
tcb-sandbox bash "ls -la"

命令列表

| 命令 | 说明 | |------|------| | serve | 启动本地 TRW | | local ... | 管理本地受管工作副本、checkpoint、branch | | health | 健康检查 | | read / write / edit | 文件操作 | | bash | 执行命令 | | grep / glob / ls | 搜索 | | batch | 批量执行 | | git-push | Git 提交（仅 server ENABLE_GIT_ARCHIVE=true 时可用） | | add-mcp-servers / remove-mcp-servers / list-mcp-servers | MCP 管理 | | mcporter | mcporter CLI | | secrets | 密钥管理 | | files | 文件传输 | | preview | 预览服务 | | pty | PTY 终端 |

测试说明

• pnpm test：先重打 embedded TRW，再跑 CLI 契约回归、本地受管工作副本单测、serve 真实集成验证
• 跨门面（HTTP/MCP/CLI/E2B）完整矩阵请使用 sibling ../trw-example 的 pnpm start 或 pnpm test:full

本地模式详情

# 从目录初始化 workspace
tcb-sandbox serve --cow-source ~/src/my-project

# 自定义 workspace 目录
tcb-sandbox serve --cow-source ~/src/my-project --workspace-root ~/tmp/my-project-cow

# 指定端口
tcb-sandbox serve --cow-source ~/src/my-project --port 8080

# 使用自定义 TRW 入口（开发用）
export TCB_SANDBOX_TRW_ENTRY=/path/to/your/dist/index.js
tcb-sandbox serve --cow-source ~/src/my-project

限制

• local ... 命令是本地文件系统操作；其他常规命令才是 HTTP 客户端
• 本地 local ... 命令只认 workspace metadata，不处理任意普通目录
• HOME 下只保存 .tcb-sandbox-local-active.json 指针；checkpoint / branch / baseline / sandbox profile 都在 workspace 内
• checkpoint / branch 的元数据始终挂在 serve 绑定的 sandbox 根下，不会因为你切到 branch 而换作用域
• root apply 会刷新 sandbox baseline；branch apply 会把 branch 内容吸收到 sandbox 根，再刷新 baseline
• local mode 对 symlink 不做展开、重写、校验；会按原样保留，目标语义由用户自己负责
• 文件传输受 6MB 限制

更多文档

• docs/quick-start.md — 快速上手
• docs/local-mode.md — 本地模式详解
• docs/thin-client.md — 薄客户端说明