Strands Box
An open source sandbox engine for AI agents.
Overview
Strands Box is an open source sandbox for AI agents.
It combines operating-system isolation with semantic policies
written in Dogwood, so you can control
what agents can access and the conditions under which they can act.
Box is harness-agnostic. You choose the agent program or binary to run, configure
its access in box.toml, and write its policies in policy.dw.
The host OS enforces the direct access restrictions in box.toml. Strands Shell,
Monty for Python, the egress gateway, and the MCP broker send the operations
they handle to the embedded Dogwood Local Engine, which evaluates the rules in
policy.dw. Box enforces its allow or deny decisions outside the agent process.
Dogwood uses permit and forbid rules. Operations checked by the engine are
denied by default: a matching permit must allow the operation, and a matching
forbid overrides that permission.
Box's interpreters and gateways share an event history, so rules can use earlier
actions and elapsed time to decide what is allowed next. For example, a file read
through Shell or Python can cause the gateway to deny a later outbound HTTP request.
Preview: Box currently supports local execution on macOS with Apple silicon.
We welcome feedback through GitHub issues.
Read CONTRIBUTING.md before submitting a change.
Key capabilities
- File, program, and network restrictions. The agent's sandbox limits its
direct access. Box reports the configured grants at startup.
- Semantic and temporal policies. Dogwood rules can depend on the requested
operation, its arguments, earlier actions, and elapsed time. Operations checked
by the policy engine are denied unless a rule permits them.
- Policy across code and tools. Strands Shell, Monty for Python, the egress
gateway, and the MCP broker use one policy engine and event history. A file read
through one interpreter can affect whether a later network request is allowed.
- Request and tool-call checks. The egress gateway checks connections and
HTTP requests, including their method and path. The MCP integration checks
configured tool calls and their arguments.
- Credential injection. The gateway authenticates permitted requests with
configured API credentials or AWS SigV4 signing. The agent does not receive the
underlying secrets.
- Decision records. Box records policy decisions in OTLP JSON. By default,
records go to
<box_dir>/private/telemetry/records.jsonl.
Direct filesystem grants in box.toml are enforced by the OS and do not produce
individual Dogwood decisions. To apply a policy to file operations, use the
interpreters and keep those files out of the agent's direct grants. See
filesystem access and policy.
Architecture
Box runs the Dogwood Local Engine and its enforcement components in its own
process, outside the agent's sandbox. Strands Shell, Monty, the egress gateway,
and the MCP broker check operations with the engine before allowing them.
They also record events that later policy decisions can use.
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;
When the agent uses a program such as git or cargo, or a local MCP server,
Box checks the launch against policy and runs the program in its own sandbox.
You configure which files each program can read or change. The agent can send
requests to Box's interpreters, but external programs and local MCP servers
cannot. Box receives their output and exit status, and their
network traffic goes through Box's gateway by default. See the
security model for details.
For each part, where it runs, what it decides, and how one request moves through them, read
Box architecture.
Getting started
Follow the getting-started guide to run
Strands CLI with Box. To follow this guide, you need a Mac with Apple silicon and
macOS 15 or later, Node.js 22.21 or later from Homebrew, and access to Claude
Opus 5 on Amazon Bedrock in us-west-2.
The download script checks the release checksum and unpacks the binaries into
./box-core. It does not change your PATH or system directories:
curl -fsSL https://raw.githubusercontent.com/strands-agents/box/main/download.sh | sh
./box-core/box --version
Keep the downloaded binaries together in ./box-core.
You can also build from source. Then follow the guide to
write box.toml and policy.dw, and run the box.
Change what the box allows
Edit box.toml to change the agent's environment and direct access grants. Edit
policy.dw to change the rules for operations Box checks through its interpreters
and gateways. You can give your coding agent the policy-authoring skill for help
with Dogwood syntax and Box's supported actions:
https://raw.githubusercontent.com/strands-agents/box/main/.agents/skills/authoring-box-policy/SKILL.md
Examples
Run the Strands Python SDK example for a small
agent whose three tools use Shell.
See the example index for dependencies and run instructions.
Build from source
This is a Cargo workspace. rust-toolchain.toml pins the compiler, and rustup
installs it on the first build. Build the box binaries from a clone with
rustup:
git clone https://github.com/strands-agents/box.git
cd box
cargo build --release -p strands-box -p strands-box-containment
Run the compiled binary as ./target/release/strands-box. Keep its helper
binaries in the same directory.
Common tasks run through 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 runs the full suite. Include
--all-features to run the box_shell and box_credentials suites, which require
the test-support feature.
Documentation
| Guide |
Contents |
docs/user/ |
How to install Box and run a box. |
docs/design/ |
Architecture, enforcement boundaries, and design decisions. |
See AGENTS.md for the repository rules and the current state.
Reporting a problem
Open an issue on this repository. For a suspected security problem, read
SECURITY.md first.
License
Apache License 2.0.
Box 是一个用于运行 AI 智能体的开源沙箱，限制它们能执行、读取、写入以及在网络上访问的内容，将操作系统级隔离与策略引擎（Dogwood）和凭据注入相结合，确保密钥永远不会到达智能体。