python3 in both
SDKs, including Node and browsers. It supports a subset of Python and works
with workspace files under the same permissions as shell commands. Programs
cannot access host files, host environment variables or the network.
Installation
- Python
- TypeScript
Usage
Declare anin_process machine with
runtime: monty to run python3 on Monty:
- Python
- TypeScript
- YAML
Memory
Setmax_memory to limit the Python program’s memory per run, using a size
such as 64M:
MemoryError. A run also holds no more than its
workspace’s max_memory
has left, 96 MB by default.
How runs execute
- Mirage runs each program in one of four worker processes that every workspace in the process shares, so an idle workspace holds none. A run past four waits for a free one. On Cloudflare Workers, which start no processes, Monty runs inside the isolate.
- A timeout or
killstops the worker running the program, andkill -STOPpauses it. pslists each run under its machine, such asin_process:monty, with its words as expanded, as it lists any machine’s programs.
Remote server
Aremote machine with runtime: monty runs python3 on a remote Monty
server, such as
Logfire Agent Sandboxes, instead of local
workers. File and environment calls still come back to Mirage, so mounts,
mount modes and policy apply as they do locally. It runs in the Python SDK
and in Node; the browser and Cloudflare Workers refuse it.
- For Logfire, use a project API key with the
project:execute_agent_sandboxesscope. The region the key names, theusinpylf_v2_us_…oreu, picks the server,https://logfire-us.pydantic.devorhttps://logfire-eu.pydantic.dev, so nourlis needed. - Set
urlfor any other Monty gRPC server, such as a self-hosted one; it always takes precedence.api_keyis sent as a bearer token; leave it out for a server that takes none. A key that is not a Logfire key from a known region needs aurl. - The key never appears in snapshots, the server API or error messages.
- Each machine keeps its own connection, opened on its first run and closed with the workspace; workspaces never share one.
- A server that refuses, cannot be reached or drops the connection fails the
run with exit 1 and
monty: remote server: <reason>on stderr. - A timeout or
killends the run’s session on the server.kill -STOPcannot pause a remote run. pslists each run underremote:<name>.
python3 run opens a session on the server, and each file or
environment call is a round trip. Measured against Logfire’s US region from
about 25 ms away:
open(path).read() makes two or three calls. Logfire allows 1,000 file and
environment calls per session, whatever Mirage asks for; a program past them
stops with suspension limit 1000 exceeded. Its documented limits are 50 ms of
interpreter CPU per run and 20 MiB of memory per session. A remote server
suits compute-light programs with a few file calls, not scripts that walk
directories.
Python compatibility
Support applies to both SDKs unless a row says otherwise. For Python syntax and standard-library coverage, see Monty’s limitations. Examples assume a writable/data mount. Mount modes and permissions still apply.
open()
Modes and modifiers are listed separately; for example, rb combines r and b.
Example: append to a workspace file
Example: append to a workspace file
Limitations
Limitations
File objects
Example: write and read lines
Example: write and read lines
Limitations
Limitations
os
The working directory and environment come from the Mirage session, not the host.
File operations
Directory operations
Metadata and links
Environment and working directory
Example: list a workspace directory
Example: list a workspace directory
Limitations
Limitations
os.path
Example: check a workspace path
Example: check a workspace path
Limitations
Limitations
pathlib
Path.cwd() and relative path resolution use the shell’s working directory.
Example: create and inspect a workspace file
Example: create and inspect a workspace file
Limitations
Limitations
sys
Mirage passes command inputs through the runtime globals.
Example: use Mirage command inputs
Example: use Mirage command inputs
Limitations
Limitations
time and datetime
The clocks start at the workspace’s system time
when it sets one, and files the program writes are stamped from the same
clock. time.monotonic() and time.perf_counter() measure elapsed time.
Example: print today's date
Example: print today's date
Limitations
Limitations
json
JSON parsing and serialization come from Monty; see its
json reference.
Example: write and read workspace JSON
Example: write and read workspace JSON
csv, tomllib and hashlib
These modules read and write workspace files through open().
Example: read a workspace CSV
Example: read a workspace CSV
Runtime globals
argv: The invocation name and arguments.stdin: The piped input.__file__: The script’s name under the starting directory.
Example: read invocation inputs
Example: read invocation inputs
Notes
- A run starts in the shell’s working directory. The script and every
relative path pass the same mount and permission checks as
cat: a rule protecting/data/job.pyrefusespython3 job.pyfrom/data. - Script arguments follow shell expansion, including globs.
- A console session takes the working directory on its first input and keeps its own after that.
raise SystemExitexits successfully.raise SystemExit("message")exits with status 1 and prints the message.
Python subset
Monty 1.4.0 implements a subset of Python, and Mirage never falls back to another interpreter. Monty maintains the details of its standard-library modules and language limitations. Those pages track upstream Monty; the integration tables above describe the version used by Mirage. Third-party imports are unavailable.Unsupported modules
Common modules unavailable in Monty 1.4.0:- Files:
glob,io,shutil,tempfile. - Networking:
http,socket,ssl,urllib. - Processes and concurrency:
concurrent.futures,multiprocessing,queue,subprocess,threading. - Data formats and archives:
array,pickle,struct,zipfile,zlib. - Numbers and hashing:
fractions,hmac,uuid. - Language and introspection:
abc,contextlib,ctypes,importlib,inspect,types,weakref. - CLI and diagnostics:
argparse,logging,traceback,unittest,warnings. - Other utilities:
enum,heapq,operator,string.