grep, cat, pipes, redirects) run in the workspace itself; python3, node and any other program go to the machine that captures them, and the runtime on it runs them. Each runtime reaches the workspace’s files its own way.
Routing
machines is ordered: the first machine whose captures name a program runs
it, and Mirage runs the rest itself. Without the key, python3, node and
js answer command not found (exit 127) until a machine captures them.
Cloudflare Workers runs no QuickJS.
provider: in_process with the runtime it runs,
worker for Monty, host for the host’s own programs, or a
machine provider. An in_process runtime is
one Mirage ships, one you registered in code, or a ./file.py:Class
(Python) or ./file.mjs:Class (TypeScript) reference to
your own runtime. The entry’s other keys are its
settings, snake_case in YAML for both SDKs; a key it does not take is
refused.
To choose a machine for each command line, see Route Machine.
Captures
captures lists the programs a machine takes:
- Mirage’s own commands (
cat,grep,sha1sum), pipes and redirects stay in Mirage. Namecat,grep,psorkillto run it on a machine instead;cd,export,echo,ln, functions and installed CLIs stay in Mirage even when named. @externaldoes not takepython,python3,nodeorjs: Mirage has those itself and gives them to the Python or JavaScript machine in the list. Name them, or@pythonor@js, to send them somewhere else. A tool such aspipis an ordinary program: capture it on the same machine when packages must land there, as incaptures: ["@python", "pip", "pip3"].- Monty, WASI, Pyodide and QuickJS take only their own interpreter’s
names; naming another program on one is refused when the workspace is
built. A
hostmachine and a machine provider take any name. - Mirage matches the program each command really runs, after expanding its
words, so
python3is captured in$P x,env python3 x,timeout 5 python3 x,sh -c 'python3 x'andxargs python3. Each command on a line matches on its own, socat a.txt | python3 xsends onlypython3. nice,nohup,stdbuf,ioniceandsetsidrun their program where it runs alone:nice gcc x.cwheregccis taken,nice grepin Mirage. On a machine the wrapper goes with it, and permission rules and apre_commandroute answer for the program.- An absolute path Mirage has no file for, such as
/usr/bin/ffmpeg, goes to the@externalmachine. A profile’scommands.allowrefuses it, since the list can only name what it can read. - On a
hostmachine or a machine provider, a program a captured program starts runs there:makerunninggcc, or a script callingsubprocess. Capture the launcher on the same machine as the tool. A Pyodide script’ssubprocesscalls go back through Mirage’s routing like any other command. - An alias is captured as the word it expands to, once
shopt -s expand_aliasesis on and the alias was defined on an earlier line. - If two machines take the same name or group, the first wins and Mirage logs a warning.
- A program no machine takes exits 127,
command not found. - A
workspacemachine,provider: in_processwith noruntime, withcapturesruns only those mount commands itself: another mount command, such asls, exits 126,no runtime accepted this line, and an unknown program exits 127. The shell’s own words (cd,export,echo) still run. - A name only
@externaltakes has no file, sowhich,command -vandtypereport it missing; running it still works. - Globs expand against the workspace first (
python3 job.py *.csvrunspython3 job.py a.csv b.csv), and permission rules judge that argv.
python3 job.py | grep error runs python3 in the container and
grep in Mirage, and ffmpeg -i a.mp4 b.webm runs in the container.
Files
Mount modes, profiles and policies apply to every file call that reaches the
workspace. A
host machine or a machine provider’s also has its own files and network,
which they do not cover. Pyodide has its own containment limits; use a machine
with a process and kernel boundary for hostile code.
Verify workspace file access
Run these lines inside Mirage’s shell after configuring a writable/data
mount visible to the runtime capturing python3. They check that Python can
read a workspace file and write one back:
host machine, first mount a FUSE folder.
For a machine, finish its provider page’s Connecting the workspace steps
first.
Resource limits
command_limits apply to a runtime’s programs as to any command: a line past
its @line entry’s timeout_seconds exits 124 (line: timed out after Ns), and
max_bytes and max_lines cap a program’s output.
host
machine and on a machine provider’s; see machine timeouts
for what a machine needs.
If a host machine or a machine provider cannot enforce the session’s file restrictions,
Mirage refuses to launch the program as a policy refuses a command:
<provider>: Permission denied, exit 126, naming a host machine by its own name. See
machine file permissions
for restrictions that affect runtime selection.