Skip to content

Strands Shell reference

Strands Shell is the shell that runs each command the agent sends to zsh, bash, or sh in a box. Policy decides each command, and each file operation the command makes. A program outside the Shell runs in its own sandbox, separate from the agent’s.

Audience: an operator with a working box from getting started. For the steps, read write policy for shell commands.

On the agent’s PATH, zsh, bash, and sh are each the alias, a client program that sends one command to the Shell. Each accepts one of these forms:

FormThe Shell runs
zsh -c COMMAND, -lc COMMAND, -c -l COMMAND, -l -c COMMANDCOMMAND
zsh SCRIPTThe text of SCRIPT. The alias reads the file in the agent’s sandbox, so [agent.filesystem] must grant the agent a read of it.

Any other form is refused with Shell alias accepts only -c COMMAND, -lc COMMAND, -c -l COMMAND, or SCRIPT.

Each invocation is one command. A variable exported in one invocation is unset in the next. The Shell starts each command with HOME set to the agent’s HOME, and with the workspace as its working directory.

The reachable paths check is deny-only and runs after policy. It refuses a path outside the operator’s home, the agent’s home, and the workspace, a path inside the box directory, and the box.toml and policy.dw the run loaded, whatever a permit says.

Once the alias hands a command to the Shell, each command in it runs as follows:

Inside a command, the agent runsActionWhere it runsWhat bounds its reach
A builtin or a command the Shell implementsshell:exec, then one fs:* action for each file operationIn the ShellPolicy, then the reachable paths check
A program on the PATH of box run, such as gitshell:spawn on the program’s resolved pathIts own sandboxIts [tool.<name>] table or exec entry. See Configuration.
A program named by a path, such as ./target/debug/appshell:spawn on the program’s resolved pathIts own sandboxIts [tool.<name>] table or exec entry

The Shell implements these, each in place of a program of the same name on the PATH:

  • Builtins: cd, export, set, alias, trap, test, printf, echo, read, find, xargs, and others.
  • Text: cat, grep, sed, head, tail, sort, uniq, cut, tr, wc, tee.
  • Files: ls, cp, mv, rm, mkdir, rmdir, ln, chmod, touch, mktemp, readlink.
  • Data and network: jq, curl.
  • Interpreters: lua, and python and python3, which run in Monty, Box’s Python interpreter.

Paths outside the operator’s home, the agent’s home, and the workspace, such as /tmp, exist only in the Shell’s memory, for one command. A file written to /tmp is gone when the command ends.

Decided once for each command the Shell implements, after expansion, including each command that command substitution, eval, source, find -exec, xargs, or Lua’s io.popen runs.

FieldTypePresentValue
context.input.commandStringAlwaysThe command line, rebuilt from the expanded words.
context.input.programStringAlwaysThe first word after expansion, such as grep.
context.input.arg1, arg2StringWhen the command has that many argumentsThe first and second arguments. Test each with has first.
context.input.arg_countLongAlwaysThe number of arguments.
context.input.cwdStringAlwaysThe Shell’s working directory.
context.output.statusLongOn a ::response eventThe command’s exit status. A program that a signal ends records 128 plus the signal number.
@id("read_only_commands")
permit (principal, action == Box::Action::"shell:exec", resource)
when { ["cd", "pwd", "ls", "cat", "grep", "head", "tail", "wc"].contains(context.input.program) };

Decided once for each program the Shell does not implement, before Box starts it. A permit starts the program only under the rule in Configuration. shell:spawn has every field of shell:exec, with these differences:

FieldTypePresentValue
context.input.programStringAlwaysThe first word after expansion, such as git or ./target/debug/app.
context.input.program_pathStringAlwaysThe file that runs, with every link resolved. A path under the operator’s home starts with ~/.
context.input.credential_readsSet of StringWhen the matching [tool.<name>] lists name a credential storeEach credential store those lists name, such as ~/.aws. Test it with has first.
@id("built_programs")
permit (principal, action == Box::Action::"shell:spawn", resource)
when { context.input.program_path like "~/src/project/target/debug/*" };

A program’s filesystem lists bound its own file operations.

Decided once for each file operation that one of the Shell’s commands makes, on the path with every link resolved.

Actioncontext.input.operation
fs:readBox::FsReadOperation::"read_content", "read_metadata", "enumerate", "read_link", "change_dir", "exec"
fs:writeBox::FsWriteOperation::"write_content", "create_dir", "set_permissions", "symlink"
fs:deleteBox::FsDeleteOperation::"remove_file", "remove_dir"
fs:moveBox::FsMoveOperation::"rename"
FieldTypePresentValue
context.input.pathStringAlwaysThe resolved path. A path under the operator’s home starts with ~/, and the home itself is ~.
context.input.operationEnumAlwaysOne value from the table above.
context.output.resultEnumOn a ::response eventBox::FsResponseResult::"completed", "descriptor_issued", or "indeterminate".
@id("project_read")
permit (principal, action == Box::Action::"fs:read", resource)
when { context.input.path == "~/src/project" || context.input.path like "~/src/project/*" };

To print the whole action schema:

Terminal window
./box-core/box policy generate-schema --config my-box/box.toml --output-dir /tmp/schema

/tmp/schema/actions.cedarschema holds every action and field.

Policy decides whether a program outside the Shell runs. These box.toml keys decide where. After a shell:spawn permit, the program runs under the first of these that covers it:

  1. A [tool.<name>] table that matches it.
  2. An [agent.filesystem] exec entry.
  3. Neither: the program is refused with status 126.

Each submitted Shell call has a 30-second timeout by default. Set shell.timeout = 600 under [limits] to allow ten minutes, or shell.timeout = false to disable this limit. See [limits] for the accepted values.

The allowance covers the full text sent in one call, including multiple commands, pipelines, Python called inside the Shell, and programs the Shell starts. Each new call receives a fresh allowance. Output leaves its deadline unchanged. The Shell alias waits for the broker’s result.

With false, both the Shell execution deadline and the broker’s backup deadline are disabled. Calls remain cancellable, and connection and write operations retain their transport timeouts.

Monty’s 120-second active execution limit and 180-second cumulative sleep limit also apply to Python called inside the Shell, including with shell.timeout = false. Synchronous Python execution can delay timeout reporting. The direct python and python3 aliases use their own limits.

KeyTypeDefaultMeaning
commandstring arrayrequiredElement 0 is the program, and the rest are fixed leading arguments. A bare name resolves on the table’s env.PATH, else on the PATH of box run.
workspacepaththe Shell’s working directory when it is inside the agent’s workspace or a path the tool’s lists name, else the agent’s workspaceThe program’s initial working directory.
envtableemptyVariables the program receives.
filesystemtableemptyread, write, read_file, write_file, list, and deny: the paths the program’s own system calls reach.
network.contain_egressbooltrueHow the program reaches the network. See [tool.<name>.network].
grammartablenoneExperimental. The tool grammar for the program. See [tool.<name>.grammar].

A table matches a shell:spawn when program_path names the command file that Box resolved at startup, and its fixed arguments match the leading arguments of the command. When several tables match, the one with the longest command is used. When a table names the file and none matches the arguments, the program is refused.

Configured tool programs remain protected from writes and replacement for the run. Box checks direct writable grants before startup and refuses changes through the Shell after policy permits them. Configured command integrity lists the startup constraints and the procedure for operator updates.

[tool.git]
command = ["git"]
[tool.git.filesystem]
read = ["~/src/project", "/Library/Developer/CommandLineTools"]
write = ["~/src/project/.git"]
deny = ["~/src/project/.env"]

[tool.<name>.network] holds one key, contain_egress. It works the same as a stdio MCP server’s [mcp.<name>.network], with one difference: with false, the decision log records one egress:native entry each time the program runs, not once at startup.

false applies to a program whose client does not read HTTPS_PROXY, such as a client that signs in through single sign-on:

[tool.sso-cli]
command = ["sso-cli"]
[tool.sso-cli.network]
contain_egress = false

The agent picks a tool’s arguments, so with false the agent can aim the program’s connections. Don’t set it on a general client such as curl, or on an interpreter. A program that runs under an exec entry, and not a tool table, always goes through the gateway.

A program that no [tool.<name>] table names runs with the agent’s own filesystem lists when an exec entry covers it and no deny entry covers it. An entry is a file, or a directory that covers every file under it.

[agent.filesystem]
exec = ["~/src/project/target/debug"]

A bare program name in a command resolves on the PATH of the host OS’s shell that runs box run, else on /usr/bin:/bin.

curl sends each request through the egress gateway, which decides net:connect and http:request (how Box controls outbound traffic). A request the gateway refuses makes curl exit non-zero.

StatusMeaningstderr
1The Shell call exceeded its execution allowance.strands-shell: execution timeout exceeded
125Box failed to serve the command.The failure
125The call exceeded the broker’s backup deadline, five seconds after its finite Shell allowance.strands-box: the call exceeded its deadline
125The deadline exceeds the platform’s clock range. Reduce limits.shell.timeout.strands-box: the call deadline exceeds this platform's clock range
126Policy refused the command.strands-shell: effect denied: policy denied this operation on '<program>', then [policy: <id>] or [default-deny]
126Policy permitted a program, and nothing in Configuration covers it.strands-shell: <program>: no tool runs <path>: no `[tool.<name>] command` matches this program and its leading arguments
127The program is not in the Shell, and not on the PATH.strands-shell: <program>: command not found
Any otherThe command’s own status. A refused file operation fails the command that made it, for example cat with 1.policy denied this operation on '<path>', then [policy: <id>] or [default-deny]
Any otherThe path changed between the check and the operation, for example a directory was swapped for a symlink. The Shell refuses rather than act on a file policy didn’t judge. Run the command again.strands-shell: <command>: filesystem identity changed during effect admission
Any otherThe operation would change a configured tool program or an enclosing path. Update the program between runs.<path>: is a configured tool command or its ancestor
Any otherThe operation would change an installed Box program or an enclosing path. Update the installation between runs.<path>: cannot change a trusted Box executable or its path