SpadeBox 实战：用 Rust 沙箱为 AI Agent 打造安全工具箱和 JS 运行时

AI Agent 的能力边界取决于它能调用的工具——文件读写、网络请求、代码执行，缺一不可。但给 Agent 一把完整的 bash 和无限网络权限，就像把整栋楼的钥匙交出去。你不是第一个为此失眠的开发者。

SpadeBox 是一个用 Rust 编写的轻量级沙箱工具箱和 JS 运行时，专门为 AI Agent 设计。它不依赖 Docker 或 VM，直接用 cap-std 做文件系统沙箱、域名白名单做 HTTP 控制、Boa JS 引擎做代码隔离。

安装

SpadeBox 支持三种语言的包管理器：

pip install spadebox

npm install @spadebox/spadebox

cargo add spadebox-core

三种语言的 API 设计完全一致，参数名和调用链相同，切换语言无需重新学习。详细文档见 spadebox.github.io。

沙箱工具箱：三层隔离设计

SpadeBox 提供三大类工具，每类都有独立的沙箱策略：

1. 文件系统工具

提供 read_file、write_file、edit_file、move、grep、glob 六个操作，全部通过 cap-std 沙箱化——Agent 只能访问你明确指定的目录。

from spadebox import SpadeBox

sb = (SpadeBox()
    .enable_files("/workspace")
    .enable_http()
    .allow("api.github.com", ["GET"])
    .enable_js())

tools = sb.tools()  # 传给 LLM 作为可用工具

result = sb.call_tool("read_file", '{"path": "src/main.py"}')

关键区别：不给 bash 工具。SpadeBox 的设计哲学是”用精确工具替代万能的 bash”——grep 就是搜索，glob 就是列举文件，write_file 就是写文件。Agent 不需要 ls | grep | sort | tail 这样的管道链，每个操作都有对应的专用工具。

2. HTTP 网络工具

网络访问使用域名白名单模式。你告诉 SpadeBox 允许访问哪些域名和 HTTP 方法，超出范围的请求直接被拒绝：

sb = (SpadeBox()
    .enable_http()
    .allow("api.example.com", ["GET", "POST"])
    .allow("*.cdn.example.com", ["GET"]))

还有内置的密钥管理功能：为 HTTP 域名注册凭据后，得到一个 token 传给 Agent，SpadeBox 在发送请求时自动替换为真实密钥。Agent 永远不知道原始凭据是什么。

3. JavaScript 代码执行

提供 js_repl（交互式 JS 执行）和 js_exec（执行整个 JS 文件）两个工具。JS 引擎使用 Boa，与文件系统和网络走相同的沙箱策略：

sb.enable_js()

result = sb.call_tool("js_repl", '{"code": "2 + 2"}')

你还可以将自定义函数暴露给 JS 运行时，让 Agent 用 JS 脚本调用你的业务逻辑。

MCP 集成：一行命令启动

如果你使用 MCP 协议管理工具，SpadeBox 提供开箱即用的 MCP server：

spadebox-mcp --files /workspace

spadebox-mcp --allow "api.example.com:GET,POST" --allow "*.cdn.example.com:GET"

spadebox-mcp --files /workspace --allow "api.github.com:GET" --js

在 Claude Code 或 Cursor 的 MCP 配置中添加一个 SpadeBox 入口，就能让 Agent 拥有安全的文件操作和网络请求能力。

实战：构建文件搜索 Agent

from spadebox import SpadeBox

sb = (SpadeBox()
    .enable_files("/workspace")
    .enable_http()
    .allow("api.github.com", ["GET"]))

tools = sb.tools()  # SpadeBox 自动生成工具描述

result = sb.call_tool("grep", '{"pattern": "API_KEY", "path": "."}')

Agent 即使试图 ../../etc/passwd，cap-std 也会将其拦截。

SpadeBox VS 传统方案

SpadeBox 填补了”无沙箱”和”容器级沙箱”之间的空白。

注意事项

• 不是完整的操作系统级沙箱：保护文件系统和网络层面，不阻止对 CPU/内存的无限制使用
• JS 引擎有限制：Boa 是一个正在开发的 JS 引擎，某些 ES2022+ 特性可能尚未支持
• Secret 管理是静态的：首次注册后 token 不会自动轮换，长期运行需额外刷新
• 缺少 Bash 工具：设计选择，如果需要 shell 命令需额外集成

总结

SpadeBox 解决的是 AI Agent 日常工具需要安全沙箱的问题。它让你用最少的修改成本，给 Agent 的文件操作、网络请求和 JS 执行加上沙箱边界。如果你正在构建一个需要与文件系统交互的 AI Agent，花 5 分钟安装 SpadeBox——比追着删除 Agent 产生的垃圾文件省心得多。