strands-agents/box

Strands Box – What it is

Strands Box is an open‑source sandbox engine that lets you run an AI‑agent program inside a tightly‑controlled environment. The sandbox isolates the agent at the operating‑system level and then applies semantic policies (written in the Dogwood policy language) to every operation the agent tries to perform – file reads, program launches, network calls, or tool invocations.

Why it matters

Running powerful LLM‑based agents on a local machine can be risky: the agent might accidentally read or modify sensitive files, launch unwanted processes, or leak credentials when it calls external APIs. Strands Box gives developers a way to declare exactly what the agent may do and to enforce those rules at runtime, with the ability to make decisions based on the agent’s history (e.g., “after reading a secret file, block any outbound HTTP request”).

Core features (as described in the README)

Feature	What it does
File / program / network restrictions	Direct OS‑level grants are defined in box.toml. Anything not granted is blocked before the agent even sees it.
Semantic & temporal policies	Dogwood rules (permit / forbid) can inspect the operation, its arguments, prior actions, and elapsed time. By default everything is denied unless a permit matches.
Unified policy engine	The same Dogwood engine is used by four “gateways”: Strands Shell, Monty (Python), an egress HTTP gateway, and an MCP broker. Actions taken through any of these are recorded in a shared event history, enabling cross‑tool policies.
Tool‑call checks	The egress gateway validates HTTP method/path; the MCP broker validates configured tool calls and arguments.
Credential injection	When a request is permitted, the gateway can add API keys or AWS SigV4 signatures without exposing the raw secrets to the agent.
Decision telemetry	Every policy decision is logged in OTLP‑compatible JSON lines (records.jsonl) for audit or debugging.
Platform support	Currently runs locally on macOS 15+ with Apple silicon.

How it works – a quick flow

1. Agent runs inside an OS sandbox with only the grants listed in box.toml.
2. When the agent wants to read a file, launch a program, or make a network request, it talks to one of the Box gateways (Shell, Monty, egress, MCP).
3. The gateway forwards the request to the Dogwood Local Engine which evaluates the policy.dw rules against the request and the event history.
4. The engine returns allow or deny. If allowed, the gateway performs the operation (e.g., runs the program in its own sandbox, forwards the HTTP request with injected credentials). If denied, the operation is blocked and a decision record is written.
5. All events are stored in a shared history, so later rules can depend on earlier actions.

Getting started (from the README)

• Prerequisites – macOS 15+ on Apple silicon, Node 22.21+ (via Homebrew), and access to Claude Opus 5 on Amazon Bedrock (us‑west‑2).
• Install – run the provided download.sh script, which verifies a checksum and extracts binaries into ./box-core.
• Run – ./box-core/box --version to verify, then follow the docs/user/getting‑started.md guide to create box.toml and policy.dw and launch your agent.
• Build yourself – clone the repo and use Cargo (cargo build --release -p strands-box -p strands-box-containment). Helper tasks are available via just (build, test, lint, etc.).

Who would use it?

• LLM‑agent developers who need a safe execution environment for autonomous code‑generation agents.
• Security‑focused teams that want audit logs and fine‑grained control over what an agent can touch.
• Researchers experimenting with tool‑using agents and needing deterministic policy enforcement across multiple interpreters.

License

Apache 2.0 – free for commercial or academic use.

---

All details above are taken directly from the repository’s README; no additional features are inferred.