开始使用

安装

准备工具链、构建公开客户端、打包守护进程并启动网关。

本页内容+

前置要求

工作区使用 Rust 2021 edition，最低 Rust 版本为 1.85。本地 Docker 必须可访问。打包容器内守护进程需要 Zig 和 cargo-zigbuild，或已配置好的 cross。

验证

docker info
rustc --version
cargo --version

运行一次 bin/setup-musl-cross 来引导首选的 Zig 构建路径。可用时，打包任务会回退到 cross。

CLI crate 会生成三个按权限域划分的可执行文件。sandbox-mcp 只有一个二进制文件，但每个服务器进程都通过 --set 选择且仅选择一个操作目录。

Shell

cargo build -p sandbox-cli --all-features -p sandbox-mcp

控制台服务器和 SPA 是分离的。需要浏览器界面时，使用 bin/start-sandbox-console-stack，它会按依赖顺序构建资源与服务器。

Docker provider 会把静态 Linux-musl sandbox-daemon 上传到每个容器。打包目标必须与 manager.docker.daemon_binary_path 指定的构件一致。

Shell

bin/setup-musl-cross
cargo run -p xtask -- package

仅在生成最终的 fat-LTO 构件时使用 --profile release。默认的 package-fast profile 用于本地 Docker 迭代。

内容待补充：当前启动器要求 dist/git 下同时存在两个平台专用 Git 工具链归档，但尚未记录由源代码生成它们的流程。在该流程发布前，安装文档不能声称仅靠干净代码仓库即可启动。

使用仓库包装脚本，让所有客户端加载同一令牌并找到本地调试二进制文件。网关会以私有权限创建并复用 ~/.ephemeral-sandbox/gateway.token。

Shell

export PATH="$PWD/bin:$PATH"
sandbox-gateway-token path

当服务安装需要由系统管理令牌位置时，请设置 SANDBOX_GATEWAY_TOKEN_FILE。不要把令牌写入 YAML，也不要暴露给浏览器代码。

启动器会构建主机网关和客户端，打包缺失或过期的守护进程，仅停止经过 PID 文件验证的网关，然后启动新的后台进程。

Shell

start-sandbox-docker-gateway --rebuild-binary
sandbox-manager-cli list_sandboxes
sandbox-observability-cli snapshot

如果启动失败，请查看启动器输出的日志路径，并按照网关故障排查步骤处理。