Skip to content

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.

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.

KeyTypeMeaning
namestringWhich box this is. One path component of letters, digits, ., _, or -, at most 32 bytes.
box_dirstringWhere the box keeps its private state. Required, and absolute.
policystringThe Dogwood policy, relative to this file’s directory unless absolute. Absent means no authored policy, and absent policy denies.
[agent]tableThe one process the box runs.
[tool.<name>]tablesOne process each, which the agent selects by invocation. The label takes the same characters as name.
[egress.<name>]tablesWhich secret attaches to which outbound destination.
[mcp.<name>]tablesThe MCP servers this box declares.
[telemetry.<label>]tablesWhere this box’s decision records and agent spans go.
file-attributesbooleanWhether 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]tableOptional experimental features: native filesystem policy checks and tool grammars. Each is disabled by default.
[limits]tableExecution 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.

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 = true

The 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.

KeyTypeDefaultMeaning
shell.timeoutpositive integer or false30Seconds 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.

Native filesystem policy checks require a compatible, signed build and explicit selection:

[experimental-features]
native-filesystem-policy = true

The 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.

Both tables hold one process, in one shape:

KeyTypeMeaning
commandstring arrayThe first entry is the program; the rest are its fixed leading arguments. Arguments passed to run come after them.
workspacestringThe process’s initial working directory. The box enters it; a filesystem list grants reach to it.
envtableThe literal environment. HOME and PATH default to the operator’s own; every other variable is present only when env names it.
[<table>.filesystem]tableThe 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-policybooleanOptional override of the global experimental setting for this process and its descendants. See workload selection.
[tool.<name>.grammar]tableExperimental, 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 with OTEL_EXPORTER_OTLP_.
  • Names the dynamic loader reads, refused: every name that starts with LD_ or DYLD_. Box’s own aliases run in the box, so their loader would read the value too. A runtime’s own option variables, such as NODE_OPTIONS, BASH_ENV, RUBYOPT, JAVA_TOOL_OPTIONS, and PYTHONPATH, are the operator’s to set, and they reach only the process whose table names them. The zsh, bash, sh, python3, and python aliases 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.HOME names another directory; the example names strands-home, so the CLI reads its settings and writes its sessions there. A home inside box_dir is 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 encloses box_dir is 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).

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 processRequired 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.

ListWhat each entry grants
readRead the path. A directory entry covers everything below it.
writeWrite 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_fileRead one exact file. The entry names a file.
write_fileWrite one exact file. Linux requires explicit read access to that file. The entry names an existing file.
listList the directory without content access on macOS. Linux refuses this list.
metadataInspect file properties below a directory without content access on macOS. Linux omits this grant without an error. [agent.filesystem] only.
execRun the path. A file entry names an executable; a directory entry covers the binaries below it. [agent.filesystem] only.
denyRefuse 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.

The read and write lists state separate permissions. These rules also apply to local servers under [mcp.<name>.filesystem].

Requested accessSettingsmacOSLinux
Read-onlyread or read_fileSupportedSupported
Write-onlywrite or write_file, without covering read accessSupportedStartup refuses the configuration before any workload runs
Read-writeExplicit read and write grantsSupportedFiles are supported; directories require a non-root launch
Read directory with writable childParent in read, child in write or write_fileSupportedFiles are supported; writable child directories require a non-root launch
Write directory with only a readable childParent in write, child in read or read_fileSupportedStartup 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.

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.

EntryRefusal
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 directorythis 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.

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.

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.

ConditionRefusal textNext 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 executableInstall 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 pathKeep 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 itUse 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 itUpdate 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.

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.

ConditionRefusal textNext action
Box cannot account for every hard-link name.has hard links outside the installation inventory. Install an independent copyInstall 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 installationEnd 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.

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-grammars is 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 program that the tool’s command doesn’t run, such as [tool.gh] command = ["gh"] with program = "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.

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.

KeyTypeMeaning
destinationsstring arrayA 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.
protocolstringhttp, the default and the only accepted value.
secret.refstringenv://NAME for a variable on the operator’s side, or aws://PROFILE for SigV4 signing. Required. A literal value is refused.
secret.placementstringheader (default), basic_auth, or query_param.
secret.headerstringThe header the secret lands in. Defaults to Authorization.
secret.prefixstringText before the secret in the header value. Defaults to Bearer on Authorization, and empty elsewhere.
secret.paramstringThe query-parameter name. Required by, and only valid for, placement = "query_param".
secret.injectstringphantom (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_prefixstringThe 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.

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"]
KeyTypeMeaning
typestringstdio or http.
commandstring arrayFor 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.
workspacestringFor stdio: the server’s initial working directory. It grants nothing.
envtableFor stdio: the literal environment the server receives. HOME and PATH default to the operator’s own, as for [agent].
filesystemtableFor 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_wildcardsboolFor stdio: false by default. true lets this server’s whole-argument * entries match and forward caller-supplied values. See argument wildcards.
network.contain_egressboolFor 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-policybooleanFor stdio: override the global experimental filesystem policy setting. Remote http entries refuse this field. See workload selection.
destinationsstring arrayFor http: the hosts the server answers on.
secret.refstringFor 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.

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.

KeyTypeMeaning
kindstringfile or otlp.
destinationstringFor 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.
includestring arrayWhich 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.refstringenv://NAME or secret://NAME, attached on the way out.
secret.headerstringDefaults 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 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.

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.

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.

GroupKeys
The decisionstrands.box.policy.action, .resource, .verdict, .cause, .reason, .principal, and error.type on an evaluator fault
The governing rulestrands.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
Correlationstrands.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 aboutserver.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.

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.

  • 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: what box.toml grants directly, and what you own.