Strands 开源智能体沙箱 Box，用 Dogwood 策略控制访问

概述

Strands Box 是一个面向 AI 智能体的开源沙箱。它将操作系统隔离与用 Dogwood 编写的语义策略相结合，让你可以控制智能体能够访问什么，以及它们在什么条件下可以行动。

Box 与执行框架无关。你可以选择要运行的智能体程序或二进制文件，在 box.toml 中配置其访问权限，并在 policy.dw 中编写其策略。

宿主操作系统强制执行 box.toml 中的直接访问限制。Strands Shell、面向 Python 的 Monty、出口网关和 MCP 代理会将它们处理的操作发送到嵌入式 Dogwood 本地引擎，由该引擎评估 policy.dw 中的规则。 Box 在智能体进程之外执行其允许或拒绝的决定。

Dogwood 使用 permit 和 forbid 规则。引擎检查的操作默认被拒绝：匹配的 permit 必须允许该操作，而匹配的 forbid 会覆盖该许可。

Box 的解释器和网关共享事件历史，因此规则可以利用先前的操作和经过的时间来决定接下来允许什么。例如，通过 Shell 或 Python 读取文件可以导致网关拒绝之后的出站 HTTP 请求。

预览版：Box 目前支持在搭载 Apple 芯片的 macOS 上本地执行。我们欢迎通过 GitHub issues 提供反馈。在提交更改之前，请阅读 CONTRIBUTING.md。

关键能力

文件、程序和网络限制。智能体的沙箱限制其直接访问。 Box 在启动时报告已配置的授权。
语义与时间策略。Dogwood 规则可以取决于所请求的操作、其参数、先前的操作以及经过的时间。策略引擎检查的操作除非有规则允许，否则一律被拒绝。
跨代码与工具的策略。Strands Shell、面向 Python 的 Monty、出口网关和 MCP 代理使用同一个策略引擎和事件历史。通过一个解释器读取文件可以影响之后的网络请求是否被允许。
请求与工具调用检查。出口网关检查连接和 HTTP 请求，包括其方法和路径。MCP 集成检查已配置的工具调用及其参数。
凭证注入。网关使用已配置的 API 凭证或 AWS SigV4 签名对获准的请求进行身份验证。智能体不会收到底层密钥。
决策记录。Box 以 OTLP JSON 记录策略决策。默认情况下，记录会发送到 <box_dir>/private/telemetry/records.jsonl。

box.toml 中的直接文件系统授权由操作系统强制执行，不会产生单独的 Dogwood 决策。要将策略应用于文件操作，请使用解释器，并将这些文件排除在智能体的直接授权之外。参见文件系统访问和策略。

架构

Box 在自己的进程中运行 Dogwood 本地引擎及其执行组件，位于智能体沙箱之外。Strands Shell、Monty、出口网关和 MCP 代理在允许操作之前会先向引擎检查这些操作。它们还会记录事件，供之后的策略决策使用。

flowchart LR
    subgraph sandbox["Agent OS sandbox"]
        agent["Agent application"]
    end

    net["network requests"]:::label
    py["Python code"]:::label
    sh["shell commands"]:::label
    mc["local MCP calls"]:::label

    subgraph trusted["The box's trusted process (outside the agent sandbox)"]
        proxy["Egress gateway"]
        monty["Monty for Python"]
        shell["Strands Shell"]
        mcp["MCP broker"]
        policy[["Dogwood Local Engine and event history"]]
    end

    agent --- net --> proxy
    agent --- py --> monty
    agent --- sh --> shell
    agent --- mc --> mcp
    proxy -->|"policy checks"| policy
    monty -->|"policy checks"| policy
    shell -->|"policy checks"| policy
    mcp -->|"policy checks"| policy

    classDef label fill:none,stroke:none;

加载中

当 agent 使用诸如 git 或 cargo 之类的程序，或本地 MCP 服务器时， Box 会根据策略检查启动过程，并在自己的沙箱中运行该程序。你可以配置每个程序可以读取或更改哪些文件。agent 可以向 Box 的解释器发送请求，但外部程序和本地 MCP 服务器不能。Box 接收它们的输出和退出状态，并且它们的网络流量默认经过 Box 的网关。详情请参阅安全模型。

关于每个部分运行在哪里、决定什么，以及一个请求如何流经它们，请阅读 Box 架构。

快速开始

按照快速开始指南使用 Box 运行 Strands CLI。要遵循本指南，你需要一台搭载 Apple 芯片的 Mac， macOS 15 或更高版本，来自 Homebrew 的 Node.js 22.21 或更高版本，以及在 us-west-2 中访问 Amazon Bedrock 上的 Claude Opus 5。

下载脚本会校验发布校验和，并将二进制文件解压到 ./box-core。它不会更改你的 PATH 或系统目录：

curl -fsSL https://raw.githubusercontent.com/strands-agents/box/main/download.sh | sh
./box-core/box --version

将下载的二进制文件一起保存在 ./box-core 中。你也可以从源码构建。然后按照指南编写 box.toml 和 policy.dw，并运行 box。

更改 box 允许的内容

编辑 box.toml 以更改 agent 的环境和直接访问授权。编辑 policy.dw 以更改 Box 通过其解释器和网关检查的操作规则。你可以为你的编码 agent 提供策略编写技能，以帮助处理 Dogwood 语法和 Box 支持的操作：

https://raw.githubusercontent.com/strands-agents/box/main/.agents/skills/authoring-box-policy/SKILL.md

示例

运行 Strands Python SDK 示例，这是一个小型 agent，其三个工具使用 Shell。

有关依赖项和运行说明，请参阅示例索引。

从源码构建

这是一个 Cargo 工作区。rust-toolchain.toml 固定编译器版本，rustup 会在首次构建时安装它。使用 rustup 从克隆的仓库构建 box 二进制文件：

git clone https://github.com/strands-agents/box.git
cd box
cargo build --release -p strands-box -p strands-box-containment

将编译后的二进制文件作为 ./target/release/strands-box 运行。将其辅助二进制文件保存在同一目录中。

常见任务通过 just 运行：

just build         # the CLI, the alias image, and the containment trampoline
just test          # workspace tests
just check         # pre-push gate: fmt-check + clippy + test
just test-all      # workspace tests and box example checks

cargo test --workspace --all-features 运行完整测试套件。包含 --all-features 以运行 box_shell 和 box_credentials 测试套件，这些套件需要 test-support 特性。

文档

指南	目录
`docs/user/`	如何安装 Box 并运行 box。
`docs/design/`	架构、执行边界和设计决策。

有关仓库规则和当前状态，请参阅 AGENTS.md。

报告问题

在此仓库上提交 issue。对于疑似安全问题，请先阅读 SECURITY.md。

许可证

Apache License 2.0。