Runtimes

​

Differences from the Python SDK

• Monty: each run executes in a crash-isolated worker. os.chdir() raises RuntimeError; use cd in the shell or the run’s ctx.cwd. os.stat() has only the named fields (st.st_size).
• QuickJS: a std and os shim with the calls the QuickJS table lists. A write shows to other commands once the file is closed. A timeout stops the run, and the engine caps a run at 64 MiB of memory and 1 MiB of stack.
• Local: in @struktoai/mirage-node only. With neither home nor MIRAGE_LOCAL_HOME, python3 is the one on PATH.
• Sandboxes: in @struktoai/mirage-node; e2b also runs in browsers. mountType ssh and both need Node and the ssh2 package. The ssh runtime authenticates through SSH_AUTH_SOCK when there is no identityFile, and username defaults to the local user.
• Config objects are camelCase in code (sandboxId, mountType); YAML spells the same keys in snake_case.
• Pyodide is in the TypeScript SDK only; WASI is in the Python SDK only.

​

Pyodide

​

Scripts and flags

• Each command and one-shot evaluation starts a fresh interpreter, so imports do not carry over; files on the mounts do. A console session keeps its own interpreter.
• A script runs as in CPython: __file__ is absolute, tracebacks quote its lines, and sys.path[0] is its directory. -P leaves that entry off, and for -c and stdin omits the working directory entry. sys_path entries stay either way.
• -P, -O/-OO and -B show in a read-only sys.flags. -O and -OO compile imported modules from source. Flags and import paths reset when the command ends, errors included.
• An installed Python CLI gets bare argv (its name at index 0) and stdin (bytes, or None), as on Monty; Pyodide also keeps sys.argv and sys.stdin.
• Standard streams support text and .buffer I/O, but do not expose native OS file descriptors.

​

Files

• Native packages such as PIL and NumPy reach the same mounts as open().
• A file is fetched on first access and cached for the run; edits made elsewhere during the run are not seen.
• A create, delete, rename, mkdir, chmod or truncate reaches the mount when the call is made, and a write when the file is closed, so a refusal fails that call with the mount’s errno. Writes still open at the end land then; a failure there exits nonzero with a message. Concurrent writes are not conflict-checked.
• A path no mount serves answers ENOTSUP to os.getxattr.
• A console keeps its own os.chdir(), even through an exception; if its directory disappears, the next input fails, resets the working directory to / and keeps the variables.
• Mount files under a prefix such as /data: a mount at / cannot replace Pyodide’s own filesystem, which holds its standard library.

​

Worker and browser setup

• Cross-origin isolation: the page is served with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp.
• Mirage’s service worker, on any other page: copy node_modules/@struktoai/mirage-browser/dist/pyodide-sw.js to the folder your site serves at its root, and register it before the first python3:

const container = navigator.serviceWorker
await container.register('/pyodide-sw.js')
if (container.controller === null) {
  const controlled = new Promise((resolve) => {
    container.addEventListener('controllerchange', resolve, { once: true })
  })
  ;(await container.ready).active?.postMessage('claim')
  await controlled
}

​

Concurrency and timeouts

• max_concurrency (default 1) bounds active top-level commands, one-shot evaluations and inputs to distinct consoles; extra calls wait. Calls in one shell session stay ordered; give independent work its own session with ws.createSession(id) and { sessionId: id }. Nested subprocesses bypass the limit. In a browser the limit stays 1, so commands from every session take turns; a second Workspace runs alongside the first.
• A timeout raises KeyboardInterrupt in the program, even in a busy loop. That needs SharedArrayBuffer. Without it, a workspace command’s worker is stopped instead, and a standalone run on the main thread blocks the event loop until it ends.

​

Sockets

​

Containment

• Further module loads are refused, including import('node:child_process') and imports of already loaded Node modules.
• Host globals (process, global, fetch, WebSocket, and an injected require) are removed.
• Exposed host filesystem and socket APIs are disabled, including mountNodeFS, mountNativeFS, useNodeSockFS, NODEFS, and host file preloading. Binary reads are restricted to configured local distribution and package directories, with traversal and symlink escape checks.

​

Child processes

import subprocess

result = subprocess.run(["printf", "%s", "hello"], capture_output=True, text=True, check=True)
print(result.stdout)

• Supported: run, call, check_call, check_output, Popen with live pipes, poll, wait, communicate, termination, timeout retries, text mode, stderr=STDOUT, and shell=True through the workspace’s sh.
• sys.executable is /usr/bin/python3, and shutil.which sees the profile’s programs. Functions and shell builtins are not programs.
• The environment is inherited unless env replaces it. Writes land before each process call, and file caches reset after it.
• A timed-out wait or communicate leaves the child running; run kills it. Children still running when the program ends are cancelled.
• Not supported: native descriptors, PTYs, process groups, user switching, preexec_fn, asyncio.create_subprocess_exec and signal handlers. An unsupported option fails with an error.

​

Configuration

​

E2B in browsers

import { E2BRuntime } from '@struktoai/mirage-core/runtime/sandbox/e2b/runtime'

​

Managing runtimes in code

await ws.removeRuntime('monty')
ws.addRuntime('pyodide')

import type { E2bSdk } from '@struktoai/mirage-core/runtime/sandbox/e2b/sdk'
import type { DaytonaSdk } from '@struktoai/mirage-node/runtime/sandbox/daytona/sdk'
import type { Ssh2Sdk } from '@struktoai/mirage-node/runtime/sandbox/ssh/sdk'

​

Child processes

const child = ws.spawn({ argv: ['cat'] })
const result = await child.communicate(new TextEncoder().encode('hello\n'))