Claude Sandbox SDK

管理 Claude Agent 沙盒服务的 CLI 工具。

安装

pip install claude-sandbox-sdk

使用

启动服务

# 前台运行
claude-sandbox start

# 后台运行
claude-sandbox start --daemon

# 指定端口
claude-sandbox start --port 8300

# 指定地址和端口
claude-sandbox start --host 127.0.0.1 --port 8300

停止服务

claude-sandbox stop

# 强制终止
claude-sandbox stop --force

重启服务

claude-sandbox restart

# 重启并更换端口
claude-sandbox restart --port 8300

# 先同步控制中台投放的资源，再重启
claude-sandbox restart --assets-dir /path/to/bundle

更新 Agent 资源与 MCP 工具

assets/media-studio-agent 与 mcp_tools.py 不再打进 wheel，由 agent 控制中台 维护和投放。控制中台把 bundle 写进沙盒后，执行：

claude-sandbox restart --assets-dir /path/to/bundle

bundle 目录结构（两种形态都接受）：

<bundle>/
  .claude/agents/*.md
  .claude/skills/...
  CLAUDE.md
  settings.json
  mcp_tools.py          # 可选，只在 MCP 有变化时携带

或者把 agent 资源整体放在 <bundle>/media-studio-agent/ 下。同步规则：

• agent 资源复制到工作目录，覆盖同名文件；
• 上次投放、本次 bundle 已不存在的文件会被清理（只清理自己投放过的文件）；
• mcp_tools.py 安装到 ~/.claude-sandbox/runtime/mcp_tools.py，服务启动时 从这里动态加载，不放进工作目录；
• 只带 mcp_tools.py 的 bundle 视为「仅更新 MCP」，不改动工作目录。

MCP 模块必须导出 mcp、set_client_env、_download_file、_wrap_song （与 server.py 的下载接口共用）。它是进程内加载的，因此新增第三方依赖时 需要同步更新沙盒镜像。

首次部署时必须先投放一次 mcp_tools.py，否则服务会拒绝启动。

查看状态

claude-sandbox status

查看日志

# 查看最近 50 行
claude-sandbox logs

# 实时跟踪
claude-sandbox logs --follow

# 查看最近 100 行
claude-sandbox logs --lines 100

配置

配置优先级: CLI 参数 > 环境变量 > 默认值

数据目录

服务运行时数据存储在 ~/.claude-sandbox/:

• pid — 运行中的进程 PID
• port — 当前使用的端口
• server.log — 服务日志
• runtime/mcp_tools.py — 控制中台投放的 MCP 工具模块
• deployed_assets.json — 上次同步到工作目录的文件清单

开发

# 克隆仓库
git clone https://github.com/ai302/claude-sandbox-sdk.git
cd claude-sandbox-sdk

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check .
mypy app/

发布

# 构建
python -m build

# 上传到 PyPI
twine upload dist/*

API 端点

License

MIT