Skip to main content
Pydantic Monty runs 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

Usage

Declare an in_process machine with runtime: monty to run python3 on Monty:

Memory

Set max_memory to limit the Python program’s memory per run, using a size such as 64M:
A run that needs more raises 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 kill stops the worker running the program, and kill -STOP pauses it.
  • ps lists each run under its machine, such as in_process:monty, with its words as expanded, as it lists any machine’s programs.

Remote server

A remote 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_sandboxes scope. The region the key names, the us in pylf_v2_us_… or eu, picks the server, https://logfire-us.pydantic.dev or https://logfire-eu.pydantic.dev, so no url is needed.
  • Set url for any other Monty gRPC server, such as a self-hosted one; it always takes precedence. api_key is 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 a url.
  • 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 kill ends the run’s session on the server. kill -STOP cannot pause a remote run.
  • ps lists each run under remote:<name>.
Each 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.

File objects

os

The working directory and environment come from the Mirage session, not the host.

File operations

Directory operations

Environment and working directory

os.path

pathlib

Path.cwd() and relative path resolution use the shell’s working directory.

sys

Mirage passes command inputs through the runtime globals.

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.

json

JSON parsing and serialization come from Monty; see its json reference.

csv, tomllib and hashlib

These modules read and write workspace files through open().

Runtime globals

  • argv: The invocation name and arguments.
  • stdin: The piped input.
  • __file__: The script’s name under the starting directory.

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.py refuses python3 job.py from /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 SystemExit exits 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.