box.toml configuration reference
box.toml is the complete run configuration for one box. Pass its path through
strands-box run --config FILE; the tutorial’s download names the binary box. Box reads the
selected file and its policy on every start.
Audience: an operator who runs an agent or another command under a box, and who declares the paths, hosts, credentials, MCP servers, and telemetry targets it can use. The example on this page is the box that getting started builds: the Strands CLI on a Mac. Each section below annotates it. To write the policy the file points at, read policy, and point a coding agent at the policy-authoring skill.
Example
Section titled “Example”Getting started builds this macOS example one file at a time, and the block is
the tutorial’s my-box/box.toml, with its one longer comment shortened to a line.
# To author or change the policy next to this file, point your coding agent at the skill:# https://raw.githubusercontent.com/strands-agents/box/6097aed88c4c0e0a3f115efc40ad2b0e0c100c64/.agents/skills/authoring-box-policy/SKILL.md
# The box's name, and where it keeps its own state. The agent can't reach box_dir.name = "strands"box_dir = "<HOME>/box-tutorial/my-box/state"# The policy file, next to this one.policy = "policy.dw"
[agent]# The program the box starts. Node loads the preload file first, then runs the CLI.command = [ "/opt/homebrew/bin/node", "--import=<HOME>/box-tutorial/proxy-preload.mjs", "/opt/homebrew/lib/node_modules/@strands-agents/cli/bin/strands.js", # Give the agent its shell and web fetch, and no file tools, so the policy decides each file it works on. "--set", 'builtinTools={"*":false,"shell":true,"web_fetch":{"transport":"direct"}}', # Keep sessions and memory out of the project. "--set", 'session.dir="<HOME>/box-tutorial/strands-home/sessions"', "--set", 'memory.dir="<HOME>/box-tutorial/strands-home/memory"',]# The directory the agent starts in. This alone grants nothing.workspace = "<HOME>/box-tutorial/my-project"# The agent gets these variables, plus the ones the box adds. Nothing comes from your shell.env = { AWS_REGION = "us-west-2", HOME = "<HOME>/box-tutorial/strands-home", PATH = "/usr/bin:/bin", TERM = "xterm-256color" }
# What the agent's own process can touch without asking the policy.[agent.filesystem]# Node loads the CLI, and the CLI reads its settings.read = ["/opt/homebrew/lib/node_modules/@strands-agents/cli", "~/box-tutorial/strands-home"]# Node loads the preload file, and reads Homebrew's OpenSSL settings when it starts.read_file = ["~/box-tutorial/proxy-preload.mjs", "/opt/homebrew/etc/openssl@3/openssl.cnf"]# The CLI writes its sessions and memory.write = ["~/box-tutorial/strands-home"]# The CLI lists the names in its working directory. It can't open the files itself.list = ["~/box-tutorial/my-project"]
# The box adds your Bedrock API key to each Bedrock request; the agent gets a stand-in value.[egress.model]destinations = ["bedrock-runtime.us-west-2.amazonaws.com"]secret.ref = "env://AWS_BEARER_TOKEN_BEDROCK"<HOME> is a placeholder for your home directory. Getting started replaces it with
sed -i '' "s|<HOME>|$HOME|g" my-box/box.toml.
Use full paths for box_dir, workspace, and env.HOME. Filesystem list entries can start with ~.
An unknown key at any level is a load error.
The file carries eleven keys. name and box_dir are required.
| Key | Type | Meaning |
|---|---|---|
name | string | Which box this is. One path component of letters, digits, ., _, or -, at most 32 bytes. |
box_dir | string | Where the box keeps its private state. Required, and absolute. |
policy | string | The Dogwood policy, relative to this file’s directory unless absolute. Absent means no authored policy, and absent policy denies. |
[agent] | table | The one process the box runs. |
[tool.<name>] | tables | One process each, which the agent selects by invocation. The label takes the same characters as name. |
[egress.<name>] | tables | Which secret attaches to which outbound destination. |
[mcp.<name>] | tables | The MCP servers this box declares. |
[telemetry.<label>] | tables | Where this box’s decision records and agent spans go. |
file-attributes | boolean | Whether write folders on macOS may also set file times, and with them set-ID bits, the group, the owner, and access control lists. false by default. |
[experimental-features] | table | Optional experimental features: native filesystem policy checks and tool grammars. Each is disabled by default. |
[limits] | table | Execution limits for Strands Shell. |
The example uses five of the eleven: name, box_dir, policy, [agent], and one
[egress.<name>] table. It declares no tool, no MCP server, and no telemetry target.
name and box_dir are the two required keys. name labels the box in its record and its
telemetry. box_dir selects the box: one directory is one box. A name outside
its limits is refused with box name "<name>" is invalid: <reason>; use one component of letters, digits, '.', '_', or '-'.
Box creates the directory box_dir names, with mode 0700, and creates no directory above it.
Create the parent yourself, or the run is refused with the box directory's parent does not exist; create it, because Box creates no directory above the one `box_dir` names. Everything Box writes
for a box is under box_dir, or under a path the file names. The example’s
box_dir is my-box/state, under the my-box directory the operator made for the two files.
box_dir may not be the agent’s workspace or lie below it, and neither box.toml nor policy.dw
may lie inside it. Each is refused by name: `box_dir` <path> is equal to or below the agent's workspace <path>, configuration source <path> is inside `box_dir` <path>, and policy source <path> is inside `box_dir` <path>.
The directory holds bin, run, trust, and private. None of them is a home, and no box reaches
its own private tree from inside. It stays until you delete it: end the run process to stop a box,
and remove the directory after run has exited to delete one. Do not remove the directory while
its run is alive: on macOS, the kernel kills a shell or Python call of that box whose program file
loses a name during its security assessment.
Keep other boxes’ configuration and state outside write access
Section titled “Keep other boxes’ configuration and state outside write access”Keep each box’s configuration, policy, and generated state in locations controlled by the operator.
Do not grant a workload write access to another box’s box_dir, configuration file (box.toml), or policy file (policy.dw).
Keep each policy file outside every other box’s filesystem grants.
Review the filesystem lists for the agent, tools, and local MCP servers before starting a workload.
A directory grant can include another box’s files beneath that directory.
For example, write access to /work/projects can include a second box’s configuration under /work/projects/other-box.
Box protects the configuration and policy that the current run loaded.
It does not automatically discover and protect every other box’s files.
A directory name such as .strands-box alone provides no protection for another box.
If a workload changes another box’s configuration or policy, that box reads the changes on its next run.
Write access that includes another running box’s box_dir can also expose its broker socket, run/box.sock.
Requests through that socket use the receiving box’s policy.
If a filesystem grant must enclose another box, add native exclusions through filesystem.deny.
Exclude that box’s box_dir and the directories that hold its configuration and policy.
Apply these exclusions to the agent, each tool, and each local MCP server with the grant.
These exclusions also block connections through the other box’s run/box.sock path.
On Linux, these directories must exist before startup.
The startup output lists each filesystem grant, including a broad grant that encloses another box’s directory. Inspect these paths for access to other boxes’ files. The output reports the granted access and does not remove another box’s files from it. The workload starts without waiting for you to approve that output.
Restrict file operations through Strands Shell and Monty separately with policy forbid rules.
Protect each other box’s box_dir and the directories that hold its configuration and policy.
Cover each directory and its descendants for fs:read, fs:write, fs:delete, and fs:move.
Also forbid fs:move on enclosing directories that could relocate these protected paths.
A forbid overrides matching permits. Adding a narrower permit leaves any broader permit active.
A native filesystem.deny entry does not restrict these requests through the box’s trusted process.
file-attributes
Section titled “file-attributes”On macOS, a write folder refuses most calls that set a file’s times: utimensat, which touch
calls, and setattrlist, which cp -p and rsync -t use. Only utimes works. So touch,
cp -p, and rsync -t fail with Operation not permitted. The file-attributes switch lets a
write folder set them. The key goes at the top of the file, above the first table:
file-attributes = trueThe default is false, and the switch applies to the agent, every tool, and every local MCP server
in the box. It has no effect on Linux, which accepts the key. With the switch off, the box renders
no rule for it. A box that sets it stores its record at version 25 or newer, depending on its
other configured features.
An older build refuses a version it does not support.
With the switch on, a process in a write folder can set the times of a file there. It can also set
the file’s set-user-ID and set-group-ID bits, change its group, store an access control list on it,
and, in a box that runs as root, give it to another user. macOS has no rule that allows the times
and refuses these. See
file attributes on macOS for what that means and how to
undo it. Flags such as uchg, ownership changes through chown, and chmod of the set-ID bits stay
refused. A path outside the write folders, and a file the box protects, stay unwritable. tar -x
restores times with the switch, but an archive that macOS tar made with its default metadata
still fails to restore the owner and the flags. Extract it with tar -x --no-mac-metadata.
The box prints one line for each process the switch applies to, in the startup disclosure:
strands-box: [agent] file attributes: may set file times, set-user-ID and set-group-ID bits, the group, the owner, and access control lists on files in its writable grants. Linux prints no line.
[limits]
Section titled “[limits]”| Key | Type | Default | Meaning |
|---|---|---|---|
shell.timeout | positive integer or false | 30 | Seconds allowed for one submitted Strands Shell call, including its commands and pipelines. false disables the Shell and broker execution deadlines. |
To allow ten minutes, add [limits] with shell.timeout = 600. The equivalent nested table is
[limits.shell] with timeout = 600. Output leaves the original deadline unchanged.
Set shell.timeout = false to disable this limit, or omit the key for the 30-second default.
Connection and write operations retain their transport timeouts.
Zero, negative numbers, fractions, strings, true, and values too large for the platform’s clock
are load errors.
This setting applies to the calls forwarded by zsh, bash, and sh, including Python called
inside the Shell. Python’s own limits also apply, including
with shell.timeout = false. Synchronous Python execution can delay timeout reporting.
See Shell timeouts for the call scope and
stored configuration for rollback.
[experimental-features]
Section titled “[experimental-features]”Native filesystem policy checks require a compatible, signed build and explicit selection:
[experimental-features]native-filesystem-policy = trueThe default is false. Unknown feature names are errors.
Signed macOS releases include the adapter, but leave it disabled until you select it.
An unsupported build refuses true before the workload starts.
See native filesystem policy for build requirements, coverage, and recovery behavior.
tool-grammars = true turns on tool grammars, which are experimental and off
by default.
[agent] and [tool.<name>]
Section titled “[agent] and [tool.<name>]”Both tables hold one process, in one shape:
| Key | Type | Meaning |
|---|---|---|
command | string array | The first entry is the program; the rest are its fixed leading arguments. Arguments passed to run come after them. |
workspace | string | The process’s initial working directory. The box enters it; a filesystem list grants reach to it. |
env | table | The literal environment. HOME and PATH default to the operator’s own; every other variable is present only when env names it. |
[<table>.filesystem] | table | The path lists the process’s own system calls reach. Eight for [agent]; six for a [tool.<name>], which has no metadata or exec list. |
native-filesystem-policy | boolean | Optional override of the global experimental setting for this process and its descendants. See workload selection. |
[tool.<name>.grammar] | table | Experimental, and [tool.<name>] only. The tool grammar for the program this tool runs. See [tool.<name>.grammar]. |
The box adds the runtime minimum to every process; see the runtime minimum.
The program is a full path or a bare name. A bare name uses env.PATH when set.
Otherwise, Box uses the operator’s PATH, or /usr/bin:/bin if it is absent. A relative path with more than one
component is refused: `command` element 0 "<program>" is a relative path; write an absolute path, or a bare name that `env.PATH` resolves. Scripts on Linux require
interpreter grants. The example’s command runs
Homebrew’s node, which loads the preload file and then the CLI’s script; the arguments after the
script are the CLI’s own.
workspace is absolute, and it is optional: when absent, the box uses the directory run was
started from. The directory must exist, and it may not be the operator’s home. The box enters it.
The process reads nothing in it until a list in filesystem names it: the example’s workspace is
the project, and the list entry below is what lets the CLI see the names in it.
env.PATH contains full directory paths separated by :. Box uses these entries as written, so ~ stays literal.
For example, use /home/alex/.local/bin:/usr/bin:/bin instead of ~/.local/bin:/usr/bin:/bin.
When the box declares an MCP server, it also protects directories on the PATH of the shell that starts Box.
Keep those directories and their parents outside filesystem write grants.
For example, a search directory /work/tools/bin prevents a write grant for /work/tools.
Changing env.PATH in box.toml does not change this protection.
env is literal. Four kinds of name have their own rule:
- Names Box sets itself, which a table cannot claim:
HTTP_PROXY,HTTPS_PROXY,http_proxy,https_proxy,NO_PROXY,no_proxy,SSL_CERT_FILE,NODE_EXTRA_CA_CERTS,NODE_USE_ENV_PROXY,CODEX_CA_CERTIFICATE,AWS_CA_BUNDLE,REQUESTS_CA_BUNDLE,GIT_SSL_CAINFO,PWD,USER, and every name that starts withOTEL_EXPORTER_OTLP_. - Names the dynamic loader reads, refused: every name that starts with
LD_orDYLD_. Box’s own aliases run in the box, so their loader would read the value too. A runtime’s own option variables, such asNODE_OPTIONS,BASH_ENV,RUBYOPT,JAVA_TOOL_OPTIONS, andPYTHONPATH, are the operator’s to set, and they reach only the process whose table names them. Thezsh,bash,sh,python3, andpythonaliases run in Box and do not read them, so a shell or Python option variable reaches a real interpreter that the table runs or spawns, and not an alias call. HOME: an absolute path. It stays the operator’s own home unless[agent] env.HOMEnames another directory; the example namesstrands-home, so the CLI reads its settings and writes its sessions there. A home insidebox_diris refused with`env.HOME` is <path>, which lies in trusted Box state. The box directory holds `bin`, `run`, `trust`, and `private`, and none of them is a home. Name a directory outside it, or omit `env.HOME` for the operator's own home, and a home that enclosesbox_diris refused with`env.HOME` is <path>, which encloses the box directory <path>. A declared home is reachable, so a home above the box directory would put this box's own state, and any sibling box's, inside the reachable set. Name a home beside the box directory rather than above it, or omit `env.HOME` for the operator's own home.TMPDIR: an absolute path.
A name Box sets is refused with `env` name "<name>" is set by the box itself, so a table cannot claim it. A dynamic-loader name is refused with `env` name "<name>" is read by the dynamic loader of every program in the box, Box's own aliases included, so a table cannot set it.
TERM and COLORTERM reach the process only when env names them, so a program that picks colors
from them renders plain otherwise. The example names TERM; an operator who wants a program’s
colors writes their own terminal’s values for both.
The agent reaches every [egress.<name>] route, every [tool.<name>], and every [mcp.<name>]
the file declares. A tool or MCP server reaches every
egress route and starts no tool or MCP server of its own. All of them share one egress gateway, so
the box is the credential boundary: a process that must not hold a credential goes in another box.
Each tool and each stdio MCP server runs in its own separate sandbox (see
the sandboxes for tools and local MCP servers).
Script commands on Linux
Section titled “Script commands on Linux”On Linux, a script in command[0] requires existing filesystem grants for every program in its
#! interpreter chain. Missing coverage prevents the process from starting.
The refusal identifies the canonical interpreter path to grant. This path can differ from the spelling in the script.
| Declared process | Required interpreter coverage in its own filesystem table |
|---|---|
[agent] | exec, naming each interpreter file or a directory that covers it. |
[tool.<name>] or local [mcp.<name>] | read or read_file. Existing writable grants also count where they permit execution and satisfy the Linux read-write requirement. |
Tool and local-server tables do not accept an exec list. System paths have no exemption.
#!/usr/bin/env python3 requires coverage for both env and the selected python3.
If either program is itself a script, its interpreter also requires coverage. Denials and protected paths still restrict access.
These fragments assume /opt/check/check.sh starts with #!/usr/bin/dash, and /usr/bin/dash is
an executable regular file. Use the canonical path when the interpreter is a symbolic link.
An agent script uses:
[agent]command = ["/opt/check/check.sh"]
[agent.filesystem]exec = ["/usr/bin/dash"]A declared tool script uses:
[tool.check]command = ["/opt/check/check.sh"]
[tool.check.filesystem]read_file = ["/usr/bin/dash"]Apply the same interpreter grants under [mcp.<name>.filesystem] for a local server.
A tool interpreter granted through read or read_file can still need separate read grants for
non-system libraries. Interpreter discovery does not automatically grant those libraries.
Alternatively, put the native interpreter in command[0] and grant read access to the script:
[agent]command = ["/usr/bin/dash", "/opt/check/check.sh"]
[agent.filesystem]read_file = ["/opt/check/check.sh"]The command has an implicit executable grant. The script is an argument that the interpreter reads. Other files the program needs still require their own coverage.
Box checks the original grants before preserving any additional path spelling needed to start the script.
Preserving a spelling adds no authority over a different file.
On macOS, Box grants a declared command’s interpreter chain automatically.
A workload-selected program without a tool table requires its interpreter chain to have existing exec coverage on either platform.
[agent.filesystem] and [tool.<name>.filesystem]
Section titled “[agent.filesystem] and [tool.<name>.filesystem]”Each list, and what one entry in it grants. [agent.filesystem] takes all eight;
[tool.<name>.filesystem] takes six, and a metadata or exec list there is refused by name at
load. A tool’s sandbox states what a tool reaches in
their place.
Every process’s writable grants must exclude the installed Box programs, their hard-link names, mounted aliases, and enclosing directories. Installation integrity describes the checks and refusals.
| List | What each entry grants |
|---|---|
read | Read the path. A directory entry covers everything below it. |
write | Write the path. On macOS, add read to permit reads, and setting a file’s times needs file-attributes. Linux requires explicit read access across the entire write scope. |
read_file | Read one exact file. The entry names a file. |
write_file | Write one exact file. Linux requires explicit read access to that file. The entry names an existing file. |
list | List the directory without content access on macOS. Linux refuses this list. |
metadata | Inspect file properties below a directory without content access on macOS. Linux omits this grant without an error. [agent.filesystem] only. |
exec | Run the path. A file entry names an executable; a directory entry covers the binaries below it. [agent.filesystem] only. |
deny | Refuse the path, even when another list grants it. Linux requires the target to exist. |
On Linux, a launch with real or effective user ID zero refuses sandbox directory write grants before the workload starts.
Run Box as a non-root account to grant sandbox directory writes.
Root launches support explicitly granted existing-file writes and read-only directory access.
Private /tmp storage remains writable and separate from the surrounding OS.
The same restriction applies when a container maps a non-root account to user ID zero.
These filesystem lists govern sandbox access. Shell and Python requests through Box use separate policy and reach checks in the trusted process. This restriction does not change their file ownership or permission to create files.
On Linux, write access permits ordinary file writes. Permission changes, including executable-bit
changes, require a requested mode without set-user-ID or set-group-ID bits. Changing a file’s
owner or group, or requesting either special bit during creation, remains forbidden. These requests fail with EPERM (operation not permitted).
Opening an existing file without creation flags does not use its supplied creation mode.
Existing shared-group directories retain Linux’s normal group inheritance for new subdirectories.
A permission change also fails if its requested mode keeps a set-user-ID or set-group-ID bit
that the file or directory already has. The request must clear both bits to succeed.
This includes directories that inherited their group bit: GNU chmod g+w and even
chmod 755 preserve that bit and fail. A refused request leaves the existing permissions unchanged.
Direct access by operating system
Section titled “Direct access by operating system”The read and write lists state separate permissions. These rules also apply to local servers
under [mcp.<name>.filesystem].
| Requested access | Settings | macOS | Linux |
|---|---|---|---|
| Read-only | read or read_file | Supported | Supported |
| Write-only | write or write_file, without covering read access | Supported | Startup refuses the configuration before any workload runs |
| Read-write | Explicit read and write grants | Supported | Files are supported; directories require a non-root launch |
| Read directory with writable child | Parent in read, child in write or write_file | Supported | Files are supported; writable child directories require a non-root launch |
| Write directory with only a readable child | Parent in write, child in read or read_file | Supported | Startup refuses the uncovered write-only scope |
Linux writable mounts also allow reads. Box requires an explicit read grant that covers each entire write grant. An exact-file read covers only that file. A directory read covers that directory and its descendants. Execute grants do not satisfy this requirement.
For Linux read-write access from a non-root account, put a directory in both read and write. For one file, use
read_file and write_file. To retain read-only access, remove the write grant.
An agent’s read grant on a recognized Linux loader directory also permits shared-library loading.
If overlapping writes make that directory writable, startup refuses it without a directory exec grant.
This includes writes granted through another spelling or an ancestor directory.
Remove the write access, or explicitly grant execution where the existing path protections permit it.
An exec entry for one file does not authorize the whole directory.
Ordinary read-write data directories and the broader execution mode for tools remain unchanged.
Startup output states read-only, write-only, or read-write for each content-access grant.
For partial overlaps, the parent entry also identifies the overlapping grants that allow both.
Denials and protected paths still restrict access. Duplicate or nested grants of the same
operation still cause startup refusal.
The example uses four lists. read covers the CLI’s install tree and strands-home, read_file
names the preload file and Homebrew’s OpenSSL settings, write covers strands-home, and list
names the project. strands-home is in both read and write to request read-write access explicitly.
On macOS, the project is in list alone, so the CLI sees its names while policy decides each file its shell opens.
Linux refuses this example’s list entry. See the platform comparison.
Each entry is absolute, or is ~ or starts with ~/. An entry carries no pattern, no control
character, and no .. component. A directory entry that encloses this box’s box.toml and
policy.dw grants everything below it except the directory that holds those two files.
An entry names the file the kernel checks, so an entry that is itself a symbolic link is refused,
and the refusal names what the link points at. Whether a path such as /bin/sh is a link depends
on the surrounding OS, so the same exec = ["/bin/sh"] entry loads under one and is refused under
another. Write the target the refusal names.
No policy decision covers a filesystem list, so run discloses each entry on stderr before the
workload starts, under strands-box: [agent] runs <program> with no policy decision over these paths:. Getting started shows the example’s disclosure. A credential store, such as ~/.aws or
~/.ssh, is disclosed by name as well, as strands-box: [tool.<name>]: exposes ~/.ssh (read) for
a tool granted the operator’s SSH directory.
On Linux, preserved interpreter spellings appear in a separate section before the runtime minimum:
strands-box: [tool.check] interpreter aliases for configured access: alias /bin/sh -> /usr/bin/dash (interpreter spelling)The arrow maps the script’s spelling to the file its configured grants already authorize. The section appears only when Box preserves an interpreter spelling.
With no filesystem table, the process reaches its command and the runtime minimum. The
command’s own exec grant is implicit: a process may always run its command, and the startup
disclosure shows that grant as exec <command> (command, implicit). So removing a directory from
exec does not refuse the process’s own command. The controls on a host binary are the
shell:spawn permit and the [tool.<name>] table; shell policy
states how a rule spells program_path.
What is refused
Section titled “What is refused”Every refusal below names the table and the entry, as `[agent]` filesystem entry "<entry>" is refused: <reason>. <path> stands for the path the message names, and filesystem.read for
whichever list holds the entry. Shape refusals happen at parse; existence and identity refusals
happen after the box directory is created and before the workload starts.
| Entry | Refusal |
|---|---|
| A relative path | `filesystem.read` path "<entry>" must be absolute or start with `~/`, so a checked-in configuration holds in every clone |
| A pattern or a control character | `filesystem.read` path "<entry>" must be exact and contain no pattern or control character |
A .. component | `filesystem.read` path "<entry>" carries `..`; name the path it means |
| The same path twice in one list | `filesystem.read` path <path> is duplicated |
| A path that does not exist | <path> is not there: No such file or directory (os error 2). A grant on a path that does not exist grants nothing and says so nowhere |
| A symbolic link | <path> is a symbolic link to <target>. A grant carries the identity the kernel checks, so a link renders a rule that matches nothing; name <target> instead |
| A spelling the kernel resolves elsewhere | <path> is not the path the kernel checks, which is <path>. A grant carries the identity it acts on, so name that path instead |
A directory in read_file or write_file | <path> is a directory; `read_file` names one file, and a tree belongs in `read` |
A file in list | <path> is a file, and `list` enumerates a directory tree |
A file in metadata | <path> is a file, and a file's metadata comes with the `read_file` or `exec` grant that names it |
A file in exec that is not executable | <path> is not an executable regular file |
| Two grants of one operation that name one path, or that nest | <path> lies inside <path>, granted by `read`. The union is the wider grant, so the narrower one enforces nothing it appears to |
A grant wholly inside a deny entry or the directory that holds box.toml and policy.dw | <path> is at or inside <path>, which no grant reaches. The grant would render and reach nothing, so it is refused rather than left enforcing nothing |
| A writable grant that reaches the policy file without subtracting it | `write` reaches this box's policy file, <path>. A grant may enclose it only when it is subtracted, and nothing subtracts it here |
A writable grant at or above a directory on the operator’s PATH | <path> is at or above <path>, which is on the search path this box resolves a bare-name MCP program against (excerpt). Keep the directory and its parents outside write grants. |
| A writable grant can change an installed Box program, a hard-link name, or an enclosing directory | this write grant can change trusted Box executable <path> or its path. Keep the Box installation outside every process's write grants |
| A system directory or a credential store the box always refuses | <path> is refused beneath every grant: <reason> |
Create the path first, or name the existing directory above it. The same rule holds for a
[tool.<name>] command that names a file the workload has not built yet, which is refused with
containment config failed: path does not exist: <path>. In the example, the CLI install,
strands-home, the preload file, and the project all exist before the first run, because the
tutorial’s earlier steps made them.
A write grant alone is not runnable. The agent’s sandbox refuses to map code from a writable
grant. When the agent’s command or one of its interpreters lies inside a writable grant, the
startup disclosure carries a warning:
strands-box: warning: [agent] command <path> lies inside the writable grant <path>, so the process can replace the program it runs.
On Linux, an agent also needs an explicit exec grant for an automatically discovered writable loader or shared library.
Otherwise, startup fails with writable dependency <path> needed by <program> has no explicit execution grant.
A read or read_file entry does not resolve this error.
Remove write access to the library, or grant execution if the agent should run code it can change.
The same check covers writable symbolic-link paths and hard-link aliases.
Immutable hard-linked libraries retain automatic execution access when Box can verify their ownership, permissions, and mount boundaries.
A read-only file that the workload owns remains writable for this check because its owner can change its permissions.
Ordinary local mounts can retain this exception when their ownership rules agree.
Remapped ownership, nested mounts, unrecognized filesystem types, and inconclusive checks can still require explicit execution permission.
Tools and local MCP servers retain their broader execution permission for their own filesystem grants.
Their filesystem tables reject exec; only [agent.filesystem] accepts that list.
[tool.<name>] selection
Section titled “[tool.<name>] selection”A tool table applies when a program the agent’s shell starts begins with the tool’s command: the
same program, then the same fixed arguments. Box resolves each configured tool program before the
workload starts and keeps that file identity for the run. The longest matching prefix wins.
Every declared tool is selectable, and a program under one of the agent’s own exec entries needs no table of its own.
The example box declares no tool, so a program its shell names is a shell:spawn decision with no
table behind it, and the example policy permits none. A git tool for the CLI’s shell, with git from
brew install git, needs read on the Homebrew trees git loads from, and read and write on
the project:
[tool.git]command = ["/opt/homebrew/bin/git"]env = { PATH = "/usr/bin:/bin", GIT_CONFIG_NOSYSTEM = "1", GIT_CONFIG_GLOBAL = "/dev/null" }
[tool.git.filesystem]read = [ "/opt/homebrew/Cellar", "/opt/homebrew/opt", "/opt/homebrew/etc", "/opt/homebrew/bin", "~/box-tutorial/my-project",]write = ["~/box-tutorial/my-project"]A shell:spawn permit that admits git goes with the table, which by itself starts nothing.
A list entry that names a credential store gives the selected tool the operator’s long-lived
credential bytes. To give a tool a secret, bind it with an [egress.<name>] secret.ref, and keep a
tool’s env for non-secret literals.
Configured command integrity
Section titled “Configured command integrity”Each configured tool program must exist before the run starts. Box checks grants in [agent],
every [tool.<name>], and every local [mcp.<name>] table against those programs.
| Condition | Refusal text | Next action |
|---|---|---|
| A command file is absent, or a bare command name has no executable match on its search path. | path does not exist or cannot resolve bare executable | Install the command before startup, or correct its path or env.PATH. |
| A writable grant can overwrite the command or replace its path, including a symbolic-link route or enclosing directory. | this write grant can change the command or its path | Keep configured tools outside every process’s write grants. |
| A command has more than one hard link, which are filesystem names for the same file, and Box can’t rule out that the user that runs Box can write it. | has <n> hard links, and the user that runs Box may be able to write it | Use a copy with one filesystem name, or install the command so that this user can’t write it. |
| The command’s file identity changes during the run. A command with more than one hard link also counts as changed when its link count, owner, group, or mode changes. | changed after this run loaded it | Update the program between runs. |
Box accepts a command with more than one hard link when the user that runs Box can’t write it
through any name. The file belongs to another user, such as root, has no group or other write
permission, and no access-control entry lets this user write it. Most system programs are like
this, such as /usr/bin/git on macOS and /usr/bin/perl on Ubuntu.
During the run, Strands Shell and Monty refuse changes to these programs and their enclosing paths, even when policy permits the operation. Reads still require the applicable policy permission. Build output covered by the agent’s own grants remains writable when no tool table names it.
To update a configured tool, end the current run. Update the program from the surrounding OS. Start a new run to resolve and validate the updated program.
Installation integrity
Section titled “Installation integrity”Before the workload starts, Box checks its installed executable, containment launcher, and socket-alias image against every process’s writable grants.
The socket-alias image routes shell and Python commands to Box’s policy checks.
The check covers [agent], every [tool.<name>], and every local [mcp.<name>] table.
For the macOS package layout, Box protects an executable regular file named box beside Box.app as the package launcher.
A standalone application bundle does not require that wrapper. A nearby directory, symbolic link, or non-executable file named box does not prevent startup.
Operator-created launch scripts and additional symbolic-link names are outside this installation inventory.
Keep those launch paths and their containing directories outside workload write grants.
Box accepts hard links only when it finds every name in the installation directory or its immediate
deps directory. This includes Cargo’s build layout. Before each contained launch, Box checks the
original file identities and hard-link counts.
Linux also checks the files through existing mounts. On macOS, Box checks verified Data-volume spellings.
A writable grant must exclude these aliases and their enclosing directories.
| Condition | Refusal text | Next action |
|---|---|---|
| Box cannot account for every hard-link name. | has hard links outside the installation inventory. Install an independent copy | Install independent copies of the Box programs. |
| Linux cannot read or finish a stable inventory of mounted aliases. | cannot inventory mounted executable aliases: <reason> | Restore access to the process mount table and mapped files, then retry after mount changes finish. |
| A recorded file name points to another file, or the hard-link count changes during the run. | changed after this run loaded it. Stop Box before updating its installation | End the run before installation updates. |
Strands Shell and Monty also refuse changes to these files and their enclosing paths, even when policy permits the operation. Reads still require the applicable policy permission.
End every active run before installation updates. Update the installation from the surrounding OS. Start a new run to validate the updated files.
[tool.<name>.grammar]
Section titled “[tool.<name>.grammar]”This table holds the tool grammar for the program its [tool] runs, and it loads only when
[experimental-features] tool-grammars = true. The feature is experimental, and a rule on a grammar
action doesn’t take effect yet, so run warns at startup for each grammar; a user guide for tool
grammars is coming later.
Each of these is refused at startup, before any box state exists:
- A grammar while
tool-grammarsis off:invalid `[tool.git]` table: `grammar` is experimental: set `tool-grammars = true` in `[experimental-features]` to load it. - A grammar on
[agent]:invalid `[agent]` table: `grammar` is refused on `[agent]`: .... A grammar on[mcp.<name>]is an unknown field there. - A
programthat the tool’scommanddoesn’t run, such as[tool.gh] command = ["gh"]withprogram = "git":invalid `[tool.gh]` table: `tool.gh.grammar.program` is "git", but `command` runs "gh"; .... - Two grammars with one
program:tool grammar refused: `tool.brew_git.grammar` and `tool.git.grammar` both have `program = "git"`; keep one grammar for each program. - Two grammars with one
name:tool grammar refused: `tool.git.grammar` and `tool.hub.grammar` both have `name = "git"`; give each grammar its own name. - A grammar that breaks a rule of the grammar format. Each refusal names the key, as a path in
box.toml:tool grammar refused: `tool.git.grammar.shell.push.usage` has a `[` with no `]`. - A policy that names a
Tool::action that no grammar declares:policy file ... will not load: policy references unknown action: ... unrecognized action `Tool::git::Action::"push"` ....
An older build refuses a box that uses a grammar, so before you go back to one, turn
tool-grammars off, remove every grammar table, and start the box once with this build.
[egress.<name>]
Section titled “[egress.<name>]”Each table binds one secret to a set of destinations, and its name is the operator’s own label.
The example’s [egress.model] binds AWS_BEARER_TOKEN_BEDROCK to the Bedrock endpoint, and run
reads the key from its own environment. The agent, and every tool or MCP server in the box, gets a
placeholder in that variable, and the gateway swaps the key in on each request to the destination.
A binding attaches a credential to a request the policy already permitted, and grants no network
reach of its own: the example policy’s net:connect and http:request rules are what let the
requests out. The current reference for this table is
egress.md.
| Key | Type | Meaning |
|---|---|---|
destinations | string array | A host, host:port, a path prefix or /* suffix, or a *. wildcard. A pattern that matches every host is refused, and two entries may not overlap. |
protocol | string | http, the default and the only accepted value. |
secret.ref | string | env://NAME for a variable on the operator’s side, or aws://PROFILE for SigV4 signing. Required. A literal value is refused. |
secret.placement | string | header (default), basic_auth, or query_param. |
secret.header | string | The header the secret lands in. Defaults to Authorization. |
secret.prefix | string | Text before the secret in the header value. Defaults to Bearer on Authorization, and empty elsewhere. |
secret.param | string | The query-parameter name. Required by, and only valid for, placement = "query_param". |
secret.inject | string | phantom (default) or always. phantom attaches the real secret only to a request that presents the box’s placeholder, and rejects any other. always attaches the real secret to every request to the destinations, with or without a placeholder, and the decision record carries an advisory note. Valid only for an env:// route. |
secret.phantom_prefix | string | The literal prefix of the minted placeholder, before its random suffix. Defaults to strands_box_. Set it, such as sk-ant-, so a harness that checks its key format accepts the placeholder. At most 64 characters from A-Z, a-z, 0-9, -, _, ., ~. Valid only for an env:// route. |
The example takes every default: the key lands in the Authorization header with a Bearer
prefix, and only a request that carries the placeholder gets it.
An entry needs a secret. One without is refused: an entry with no secret declares only a destination, which policy already decides; give it a secret, or set protocol = "mcp" for a remote MCP server. protocol on this table takes http alone; declare a remote MCP server as
[mcp.<name>] with type = "http", which the next section describes.
An aws:// route signs inside the box, so it takes no header, prefix, placement, param,
inject, or phantom_prefix. Setting one is refused when the configuration loads.
[mcp.<name>]
Section titled “[mcp.<name>]”Each table declares one MCP server. type selects the transport. A stdio server is a local
program that the box starts in its own separate sandbox. It starts only when a shell:spawn permit
covers its command; MCP policy lists the fields that decision
carries. When no permit covers it, the open fails with MCP server "<name>" may not start: <decision> and the server does not run. An http server is a remote
server the workload reaches through the egress gateway. Each request is an mcp:call decision, and a rule
reads the table’s name as context.input.server. The current reference for this table is
mcp.md. The box adds the runtime minimum to the server’s process; see
the runtime minimum.
The example box declares no MCP server. To give the Strands CLI one, declare it here, and name the
same full command under mcpServers in the file the CLI reads through its --mcp-config option:
the same program and the same arguments, in the same order. The box places an alias with the
program’s name on the agent’s PATH, so when the CLI starts mcp-server-fetch, the box runs this
table’s command in a separate sandbox:
[mcp.fetch]type = "stdio"command = ["mcp-server-fetch"]
[mcp.fetch.filesystem]read = ["~/.local/share/uv/tools/mcp-server-fetch", "~/.local/share/uv/python"]| Key | Type | Meaning |
|---|---|---|
type | string | stdio or http. |
command | string array | For stdio: what to start. The first entry is the program and names the alias in the box’s bin/; the rest are its arguments, fixed here. The harness runs the full command to reach the server. Two tables can share a program when their full commands differ. |
workspace | string | For stdio: the server’s initial working directory. It grants nothing. |
env | table | For stdio: the literal environment the server receives. HOME and PATH default to the operator’s own, as for [agent]. |
filesystem | table | For stdio: the six lists the server’s own syscalls reach, the same six a [tool.<name>.filesystem] takes; a metadata or exec list is refused by name. An absent table grants nothing, so the server’s sandbox has the runtime minimum and the reach that a local MCP server’s sandbox states. |
argument_wildcards | bool | For stdio: false by default. true lets this server’s whole-argument * entries match and forward caller-supplied values. See argument wildcards. |
network.contain_egress | bool | For stdio: true by default. false gives this one server direct network access, with no gateway, no policy decision per request, and no credential injection. |
native-filesystem-policy | boolean | For stdio: override the global experimental filesystem policy setting. Remote http entries refuse this field. See workload selection. |
destinations | string array | For http: the hosts the server answers on. |
secret.ref | string | For http: the credential the gateway attaches on the way out. |
Without native filesystem mediation, no fs:* decision covers a stdio server’s direct file operations.
The experiment checks selected operations while retaining the server’s filesystem grants.
The startup report lists the agent’s
and each tool’s grants, and a stdio server’s grants are in its table alone, so read the table
before you let the server start. See the security page for what box.toml grants
directly.
[telemetry.<label>]
Section titled “[telemetry.<label>]”Each table declares one export target. The label is your own, and a refusal names it. The example
box declares none, so its decisions go to the default record file under box_dir, which getting
started reads with jq.
| Key | Type | Meaning |
|---|---|---|
kind | string | file or otlp. |
destination | string | For file, an absolute or ~/-relative path. Inside this box’s box_dir it must lie under private/; outside the box any path is accepted. For otlp, the collector endpoint. |
include | string array | Which records reach this target: deny, permit, trace, logs, or metrics. trace names the agent’s own spans and the box’s own records together. Absent means every one of them, so write include only to narrow the target. An empty list is refused, and so is a repeated word. |
secret.ref | string | env://NAME or secret://NAME, attached on the way out. |
secret.header | string | Defaults to Authorization with a Bearer prefix. |
A file destination inside the box directory and outside private/ is refused: "<path>" is inside the box directory <path> but outside its private tree, where a process could truncate it; name a destination under private/, or outside the box, or declare no target and take the default. An
empty include is refused with the target names no signal, so nothing would reach it; write one or more of: deny, permit, trace, logs, metrics, and a repeated word with the target names deny twice.
logs and metrics are unconditional
Section titled “logs and metrics are unconditional”logs and metrics are accepted in include and change nothing: every target receives the agent’s
log records and metrics. include = ["deny"] delivers the refusals, the log records, and the
metrics.
include narrows deny, permit, and trace, where trace covers the agent’s spans and the
box’s own records.
Agent spans, logs, and metrics need the agent’s exporter
Section titled “Agent spans, logs, and metrics need the agent’s exporter”A target receives an agent span, log record, or metric only when the agent exports it. These three
env variables turn the OpenTelemetry exporters on. The example writes env as an inline table;
they go in it, or in an [agent.env] table, which is the same key:
[agent.env]OTEL_TRACES_EXPORTER = "otlp"OTEL_LOGS_EXPORTER = "otlp"OTEL_METRICS_EXPORTER = "otlp"The box sets OTEL_EXPORTER_OTLP_ENDPOINT to its own loopback receiver, and the OpenTelemetry SDK
appends /v1/traces, /v1/logs, or /v1/metrics. The box owns every OTEL_EXPORTER_OTLP_* name, so
[agent.env] may not set one. A switch left at none means that signal never arrives, whatever
include says.
Each decision exports one span of kind INTERNAL and one log record that share a trace ID and a span
ID. When the request carries a traceparent, the span joins that trace; otherwise it is a root span.
Each run adds strands.box.run.id to its own records and to the agent resources it relays.
Which trace variables the box reads
Section titled “Which trace variables the box reads”The box reads TRACEPARENT and TRACESTATE from the shell or Python child’s own environment, because
every harness spells those two the same way. The box reads no other variable, and it names no
harness. So a shell or Python decision reports no conversation identifier. Correlate one by
strands.box.run.id, or by the trace ID when the agent sets TRACEPARENT.
An MCP frame carries params._meta.threadId or sessionId, and an HTTP egress request carries a
thread-id or session-id header. Both lanes still report a conversation, because each reads the
identifier from its own request.
A conversation identifier is a correlation hint and never an authorization. A workload can set the value, so no decision depends on one.
Policy spans mark the decision instant; their start and end times are equal. Normal denials have
UNSET status. Evaluator faults have ERROR status. A policy target receives both /v1/logs and
/v1/traces. Use the OTLP base URL in destination, and select resourceLogs or resourceSpans
when reading a file target. The scope for policy decisions is strands-box.policy.
Select decisions by the strands-box.policy scope, or by strands.box.source == "box". The agent’s
own log records share the resourceLogs key, and severity numbers do not separate the two.
What a decision carries
Section titled “What a decision carries”A value never carries the policy engine’s own spelling: read fs:read, not Box::Action::"fs:read".
Each log record’s event_name field is strands.box.policy.decision.
| Group | Keys |
|---|---|
| The decision | strands.box.policy.action, .resource, .verdict, .cause, .reason, .principal, and error.type on an evaluator fault |
| The governing rule | strands.box.policy.rule (your @id, else the rule reached), strands.box.policy.description (your @description), strands.box.policy.category, plus strands.box.policy.determining.ids for audit |
| Correlation | strands.box.request.id (egress only), jsonrpc.request.id (an MCP request), and strands.box.trace.parent_span_id, .parent_sampled, .state on the log record |
| What it was about | server.address and server.port on a net:* decision, http.request.method on a request, file.path on fs:* |
The shipped example under examples/strands-box/strands-sdk-agent/
writes a @description on its rules. It runs a Strands Agents SDK agent written in Python, which is
a different workload from the Strands CLI on this page.
The record omits url.full and process.command_line.
Errors
Section titled “Errors”A refusal of the file’s shape happens at parse, before any box state exists: an unknown key, an
absent or invalid name, an absent or relative box_dir, an empty or relative command program, a
relative workspace, an env name the box owns, a relative env.HOME or env.TMPDIR, a patterned
or relative filesystem path, a filesystem path carrying .., a duplicated filesystem path, an
overlapping or all-hosts egress destination, a secretless egress entry, a literal egress secret,
and each [tool.<name>.grammar] refusal.
An invalid limits.shell.timeout is also a parse error.
A box_dir whose parent does not exist is refused before anything is created. Every other refusal
that needs the surrounding OS happens after run has created box_dir, and before the workload
starts: a workspace that does not exist, an env.HOME inside or enclosing box_dir, a telemetry
file destination inside the box directory and outside private/, a filesystem entry whose path
does not exist or is a symbolic link, and a [tool.<name>] command that names a missing file. The
box directory stays behind. It is empty when the refusal came before the record was written, and it
holds the record when the refusal came after. The next run against it judges the file again and
reports the same refusal until the file is fixed.
A stored record whose version is not the one this build writes is refused by its version. Remove
that box’s box_dir, and the next run writes a new record into a fresh one.
See also
Section titled “See also”getting-started.md: the tutorial that builds the example box on this page.egress.md: the[egress.<name>]table in full.mcp.md: the[mcp.<name>]table in full.policy.md: the policy the file points at.security.md: whatbox.tomlgrants directly, and what you own.