box README

The project's README from github.com/strands-agents/box. As one markdown file: README.md.

Strands

Strands Box

An open source sandbox engine for AI agents.

Commit Activity Open Issues Open PRs Discord

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

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 (strands-agents/box)

Searching Database…

417 ·GitHub
Box
Что это?Box — песочница с открытым кодом для запуска ИИ-агентов, ограничивающая то, что они могут исполнять, читать, писать и куда могут обращаться по сети: она сочетает изоляцию на уровне ОС с движком политик (Dogwood) и инъекцией учётных данных, так что секреты никогда не доходят до агента.
Это библиотека для импорта или песочница, внутри которой запускается мой агент?Box — самостоятельный движок песочницы, а не библиотека: вы настраиваете доступы уровня ОС в box.toml и семантические правила в policy.dw, затем запускаете выбранную программу-агента через собственные интерпретаторы Box (Strands Shell, Monty для Python) и шлюзы.
Как запустить Box?Следуйте руководству по началу работы: запустите скрипт скачивания, который проверяет контрольную сумму релиза и распаковывает бинарники в ./box-core (или соберите из исходников с Cargo), затем напишите box.toml и policy.dw и запустите бинарник box.
Что нужно перед прохождением руководства по началу работы?Нужен Mac на Apple silicon с macOS 15 или новее, Node.js 22.21+ установленный через Homebrew, и доступ к Claude Opus 5 на Amazon Bedrock в регионе us-west-2.
Готов ли Box к продакшену на любой машине?Нет — это превью-релиз, который сейчас поддерживает только локальное выполнение на macOS с Apple silicon; поддержка Linux запланирована, но ещё не вышла.
Видит ли агент когда-либо API-ключи, которыми пользуется?Нет — egress-шлюз сам аутентифицирует разрешённые исходящие запросы, используя настроенные API-учётные данные или подпись AWS SigV4, а процесс агента никогда не получает самих секретов.
Что такое Dogwood?Dogwood — язык политик, который использует Box, построенный на правилах permit и forbid; каждая проверяемая операция по умолчанию запрещена, если её не разрешает правило permit, а совпадающее правило forbid всегда перевешивает это разрешение.
Что такое Strands Shell и Monty?Это встроенные интерпретаторы Box для shell-команд и Python-кода соответственно; оба пропускают каждую выполняемую операцию через движок политик Dogwood перед исполнением.
Может ли политика заблокировать последующее действие из-за уже случившегося?Да — интерпретаторы и шлюзы Box делят общую историю событий, поэтому правило может, например, запретить более поздний исходящий HTTP-запрос из-за более раннего чтения файла.
Что делает MCP-брокер?Он сверяет настроенные вызовы MCP-инструментов и их аргументы с политикой Dogwood, прежде чем пропустить вызов инструмента к MCP-серверу — так же, как egress-шлюз проверяет сетевые запросы.
What are similar projects?brig, agent-governance-toolkit, harness-sdk, cynative, nono, mantis, strix, omnigent
Which topics is it in?zero-trust, ai-safety, opentelemetry, sandboxing, network-security, harness, sandbox, apple-silicon, cybersecurity, security-tools, agentic-ai, agents
Creator
strands-agents
Size
3.2 MB
Stars
417
Updated
CommitOct 16Releasev0.1.0Oct 07
Age
14d
Commits · 90 Days