Skip to content

Python in a box

A box runs the agent’s Python scripts in Monty, an interpreter for a subset of Python. Policy decides each file operation a script makes, and the egress gateway decides each request a script sends with fetch().

Audience: an operator with a working box from getting started whose agent runs Python. For how Box runs a script and why a script cannot act on its own, read how Box runs Python scripts.

The workspace is ~/src/project, and it holds notes.txt and an empty out directory. The agent runs:

Terminal window
python3 -c "from pathlib import Path
text = Path('notes.txt').read_text()
Path('out/notes.txt').write_text(text.upper())
print('wrote', len(text))"

To let the agent run python3, and let the script read the project and write in out, permit all three in policy.dw:

@id("python")
permit (principal, action == Box::Action::"shell:exec", resource)
when { ["python", "python3"].contains(context.input.program) };
@id("project_read")
permit (principal, action == Box::Action::"fs:read", resource)
when {
context.input.path == "~/src/project" ||
context.input.path like "~/src/project/*"
};
@id("out_write")
permit (principal, action == Box::Action::"fs:write", resource)
when {
context.input.path like "~/src/project/out/*" &&
context.input.operation == Box::FsWriteOperation::"write_content"
};

The script writes ~/src/project/out/notes.txt and exits 0. Example output:

wrote 18

A script imports asyncio, base64, binascii, collections, copy, dataclasses, datetime, functools, itertools, json, math, os, pathlib, random, re, sys, time, typing, and unicodedata. Any other module, including subprocess, socket, urllib, and every package from PyPI, raises ModuleNotFoundError.

A name that Monty does not define, such as input(), memoryview(), or __import__(), raises NameError. Each script runs in a new interpreter, so a variable that one script sets is undefined in the next. An uncaught exception prints <exception type>: <message> on stderr.

The python3 and python aliases send their name and arguments, unchanged, to Strands Shell. So python3 report.py run by the harness and zsh -c 'python3 report.py' take one route:

  • Forms: -c SOURCE, one SCRIPT file, --version or -V, and --help or -h. The broker puts each argument in single quotes, and each ' in it takes four bytes, so the whole command must fit the Shell’s input limit, 256 KiB by default. A longer -c SOURCE exits 1 with strands-shell: input too large; put it in a script file.
  • Working directory: the directory the alias was run from. A directory other than the workspace takes an fs:read decision with operation change_dir, as cd does.
  • Script file: read by Strands Shell from that directory, under an fs:read decision. The agent’s own filesystem lists don’t decide it.
  • Policy decisions: shell:exec for the command, fs:read for a script file, and the script’s file operations.

In Strands Shell, python and python3 always run Monty, whatever the operator’s PATH holds, and python3 --version prints Monty (Strands-Box Python subset). Strands Shell refuses these forms with exit status 2:

  • python alone, or python that reads its source from stdin, such as a pipe or a heredoc.
  • python -.
  • Any argument after the -c source or the script file.

Each file operation is one decision, on context.input.path and context.input.operation. A relative path is rooted at the workspace, even when the script file was found in another directory, and a path under the operator’s home starts with ~/.

PythonActionoperation
Path.read_text(), Path.read_bytes(), open(path), open(path, "rb")fs:readread_content
Path.write_text(), Path.write_bytes(), and open() in a mode that writes or appendsfs:writewrite_content
os.stat(), Path.exists(), Path.is_file(), Path.is_dir(), Path.is_symlink()fs:readread_metadata
os.listdir(), Path.iterdir()fs:readenumerate
Path.mkdir()fs:writecreate_dir
Path.unlink(), Path.rmdir()fs:deleteremove_file, remove_dir
Path.rename(destination)fs:read on the source, fs:move on each path, and fs:delete on a destination that existsread_content, rename, and remove_file or remove_dir

Each read or write on a handle from open() is decided again. os.stat() returns the real size and file type, with st_uid and st_gid set to 0 and st_nlink set to 1.

These raise an error whatever the policy says:

PythonRaisesUse instead
Path.resolve(), Path.absolute()RuntimeError: Path.resolve: not supported by this box's Python (Monty)The path as written
os.getenv(), os.environRuntimeError: 'os.getenv' is not supported in this environmentA value in the script’s source
Path.mkdir(parents=True)PermissionErrorOne mkdir() for each level
A path outside the operator’s home and the workspacePermissionError: <path>: outside this box's home and every declared bindA path under the operator’s home or the workspace
A path that is a symbolic link, or has one in itPermissionError: <path>: resolves to a different path, so it is not the identity policy judgedThe path of the file the link points to
The box directory, or the box.toml and policy.dw this run loadedPermissionError: <path>: resolves into trusted Box state, which no policy may open, or resolves to an authority source that this run loadedA path outside the box directory
A write, deletion, or rename that reaches a configured tool command or its ancestorPermissionError containing is a configured tool command or its ancestor, which this run does not allow to changeA path outside the command and its enclosing directories
A directory mutation that reaches a hard-link alias for a configured commandPermissionError containing contains a hard link to a configured tool command, so this mutation is not allowedA directory without the command’s hard-link names
A directory mutation whose hard-link scan cannot finishPermissionError containing cannot finish checking for configured tool command hard links, followed by the scan failureCorrect the reported cause or narrow the directory
A write, deletion, or rename that changes an installed Box program or an enclosing pathPermissionError containing cannot change a trusted Box executable or its pathUpdate the installation between runs

A rename can also fail if another operation creates its destination while Box checks policy. Box raises PermissionError: <destination>: filesystem identity changed during effect admission and leaves both files in place. Retry the rename to let policy check deletion of the existing destination.

For a destination that does not exist, Box requires an atomic rename that cannot replace an existing name. If the operating system or filesystem rejects that operation, the rename raises OSError and changes neither path. Box does not retry with a replacing rename. An overwrite that policy explicitly permits still uses the existing rename operation.

Each call in this table takes no policy decision.

PythonReturns
datetime.datetime.now()The current time in UTC, with no time zone
datetime.datetime.now(tz)The current time in tz
datetime.date.today()The current date in UTC
time.time()Seconds since the Unix epoch
time.monotonic()A clock that only moves forward
os.urandom(n)n random bytes, up to 1 MiB
time.sleep(seconds), asyncio.sleep(seconds)After the wait. Two concurrent sleeps take the sum of their waits.

fetch() sends one HTTP request through the box’s egress gateway, and returns the response. It is a built-in name, and needs no import.

fetch(url, method="GET", headers=None, body=None)
ParameterTypeDefaultMeaning
urlstrrequiredAn http or https URL.
methodstr"GET"The HTTP method.
headersdict of str to strNoneThe request headers.
bodystr or bytesNoneThe request body.

Each argument is positional or a keyword. The return value is a dict:

KeyTypeValue
statusintThe HTTP status.
headersdictThe response headers, by lowercase name. A repeated header is one value, joined with , , and set-cookie values are joined with a newline.
bodystrThe response body.
r = fetch("https://api.github.com/zen", headers={"User-Agent": "notes-script"})
print(r["status"], r["body"])

Example output:

200 Mind your words, they are important.
ErrorCause
TypeErrorNo url, an argument of the wrong type, an unknown keyword, more than four positional arguments, or one argument given twice. Nothing is sent.
OSError: access denied: <host>The URL’s scheme is not http or https, or its host is localhost, a literal loopback, private, link-local, 0.0.0.0/8, or one of two cloud metadata addresses outside 169.254.0.0/16, or an IPv4-mapped, IPv4-compatible, IPv4-translated, 6to4, Teredo, or 64:ff9b::/96 NAT64 address that carries one of these, or any 64:ff9b:1::/48 address. A NAT64 address under a network’s own prefix is not covered. Nothing is sent.
OSErrorThe response body is larger than 1 MiB.
Status 403, with header x-strands-box-egress: refusedThe gateway refused the request, and the body says why. The script receives it as a response, and must check status. A 403 without the header comes from the server.
LimitWhen a script passes it
10,000 calls that Box answers, such as file operations and fetch()RuntimeError, which the script cannot catch
180 seconds of sleep in totalTimeoutError, at once, from the sleep that would pass it
128 MiB in one allocationMemoryError, which the script cannot catch
1 MiB from one os.urandom()ValueError
1 MiB in one fetch() response bodyOSError
Exit statusMeaning
0The script completed.
1The script raised an exception it did not catch, including a policy refusal and a limit.
2A form the command refuses.
125Box did not run the script to its end: Box failed, or the call ran longer than limits.shell.timeout. Box checks that limit only when Monty hands control back, so a script that never pauses, such as while True: pass, runs until Monty’s own 120-second limit stops it, however short limits.shell.timeout is.
125The alias couldn’t tell which directory it was run from, or that directory’s name isn’t valid UTF-8. Nothing ran.
126Policy refused shell:exec for the command, or Box refused the directory the alias was run from.

Monty raises only fs:read, fs:write, fs:delete, and fs:move. A file operation that no permit matches is refused. Put a path condition on each fs:* permit, as in the Example: an fs:read permit with no path condition reads every file under the operator’s home through Monty. A forbid refuses a path whatever another rule permits:

@id("no_keys")
forbid (principal, action in [Box::Action::"fs:read", Box::Action::"fs:write"], resource)
when { context.input.path like "~/.ssh/*" || context.input.path like "~/.aws/*" };

To run python and python3, through the aliases or in Strands Shell, permit shell:exec for them:

@id("python_in_shell")
permit (principal, action == Box::Action::"shell:exec", resource)
when { ["python", "python3"].contains(context.input.program) };

The egress gateway decides each fetch() with net:connect and http:request, as for the agent’s own requests. To permit a host, write the rules in the [egress.<name>] table.

ActionFieldValue
fs:read, fs:write, fs:delete, fs:movecontext.input.pathThe path. See File operations.
context.input.operationBox::FsReadOperation, Box::FsWriteOperation, Box::FsDeleteOperation, or Box::FsMoveOperation, with a value from the File operations table
shell:execcontext.input.programpython or python3, as typed
net:connectcontext.input.host, context.input.portThe fetch() URL’s host and port
http:requestcontext.input.host, context.input.method, context.input.pathThe fetch() URL’s host, the method, and the URL path
The script seesCauseFix
PermissionError: policy denied this operation on '<path>' [default-deny]No permit matches the operation.Add a permit for the action on that path, with ~/ for a path under the operator’s home.
PermissionError: policy denied this operation on '<path>' [policy: <id>]The rule with that @id refused the operation.Change the rule, or the path.
fetch() returns status 403 with header x-strands-box-egress: refusedThe gateway refused the request. The body says why.Permit net:connect and http:request for the host.
strands-shell: effect denied: policy denied this operation on 'python', exit status 126No shell:exec permit names the command.Permit shell:exec for python and python3.
strands-box: cannot start in <directory>: ..., exit status 126Policy refused fs:read with operation change_dir on the directory the alias was run from, or the directory is outside the operator’s home, the agent’s home, and the workspace, such as /tmp.Permit fs:read on that directory, or run the script from the workspace.
strands-box-sock-alias: read the working directory: ...; set PWD to it, exit status 125The alias could not read which directory it was run from.Set PWD to that directory before running python3.
python3: -m is not supported by Monty, Box's built-in Python subset. ..., or ModuleNotFoundError for a packageThe script needs real Python, such as -m pytest or a package from a venv.Have the operator set monty = false, declare a [tool] whose command file is named python3, grant it read on the venv and Python’s install, and permit shell:spawn on its file. The monty section has a working setup.

The decision log records each decision with the rule’s @id (getting started).