QuickJS

QuickJS is the default runtime for node and js in both SDKs. It supports ES2023 for small scripts and pipe transforms, with access to workspace files under the same permissions as shell commands. Despite the command name, it does not provide Node.js APIs, npm packages or network access.

Installation

Python
TypeScript

pip install 'mirage-ai[quickjs]'

Download qjs-wasi.wasm from a quickjs-ng release. Point home, or MIRAGE_QUICKJS_HOME, at its directory.

pnpm add quickjs-emscripten

The package bundles its WebAssembly.

Usage

QuickJS is in the default runtimes, so node works once it is installed. To list it yourself:

Python
TypeScript
YAML

from mirage import RAMVFS, MountMode, Workspace
from mirage.runtime.js import QuickJsRuntime

ws = Workspace(
    {"/data": RAMVFS()},
    mode=MountMode.EXEC,
    runtimes=[QuickJsRuntime(config={"home": "/path/to/quickjs"})],
)
await ws.shell("node -e 'console.log(1 + 1)'")

import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace({ '/data': new RAMVFS() }, { mode: MountMode.EXEC, runtimes: ['quickjs'] })
await ws.shell("node -e 'console.log(1 + 1)'")

mode: exec
runtimes:
  - name: quickjs
    config:
      home: /path/to/quickjs
mounts:
  /data:
    vfs: ram

home is for the Python SDK; TypeScript ignores it.

JavaScript compatibility

std and os are globals. The SDK columns identify where their APIs differ. In TypeScript, any std or os function not listed as supported throws TypeError. Examples assume a writable /data mount. Mount modes and permissions still apply.

`std.open()`

std.open(path, mode, errorObj) returns null on failure and sets errorObj.errno. A read-only mount refuses modes that write. Modes and modifiers are listed separately; for example, rb combines r and b.

Mode or modifier	Python SDK	TypeScript SDK
`r`	✓	✓
`w`	✓	✓
`a`	✓	✓
`x`	✓	✓
`b`	✓	✓
`+`	✓	✓

Example: append to a workspace file

const error = {};
const file = std.open("/data/log.txt", "a", error);
if (file === null) {
  throw new Error("Open failed: " + error.errno);
}
try {
  file.puts("Job completed.\n");
} finally {
  file.close();
}

Limitations

API or behavior	Limitation
`x`	Exclusive-creation modifier: use `wx` or `ax`; `x` alone is not a valid mode.
Write modes	A read-only mount refuses modes that write.

File objects

API	Python SDK	TypeScript SDK
`file.readAsString()`	✓	✓
`file.read()`	✓	✓
`file.getline()`	✓	✓
`file.seek()`	✓	✓
`file.tell()`	✓	✓
`file.eof()`	✓	✓
`file.puts()`	✓	✓
`file.write()`	✓	✓
`file.flush()`	✓	✓
`file.close()`	✓	✓
`file.printf()`	✓	✗
`file.tello()`	✓	✗

Example: write, seek and read a file

const file = std.open("/data/example.txt", "w+");
if (file === null) {
  throw new Error("Could not open example.txt");
}
try {
  file.puts("hello\n");
  file.seek(0, std.SEEK_SET);
  print(file.readAsString());
} finally {
  file.close();
}

Limitations

API or behavior	Limitation
`file.printf()`	Not available in the TypeScript SDK.
`file.tello()`	Not available in the TypeScript SDK.
`file.puts()`, `file.write()`	Written at `close`, or when the run ends.
`file.flush()`, `file.close()`	Flushes pending writes to the mount.

`std`

Environment variables come from the Mirage session. std.loadFile() returns null when reading fails.

API	Python SDK	TypeScript SDK
`std.getenv()`	✓	✓
`std.exit()`	✓	✓
`std.loadFile()`	✓	✓
`std.printf()`	✓	✓
`std.writeFile()`	✓	✗
`std.fdopen()`	✓	✗
`std.strerror()`	✓	✗
`std.setenv()`	✓	✗
`std.getenviron()`	✓	✗
`std.Error`	✓	✓

Example: read a session environment variable

const jobId = std.getenv("JOB_ID");
std.printf("Job: %s\n", jobId === undefined ? "unknown" : jobId);

Limitations

API or behavior	Limitation
`std.writeFile()`	Not available in the TypeScript SDK.
`std.fdopen()`	Not available in the TypeScript SDK.
`std.strerror()`	Not available in the TypeScript SDK.
`std.setenv()`	Not available in the TypeScript SDK.
`std.getenviron()`	Not available in the TypeScript SDK.
`std.popen()`	✗
`std.tmpfile()`	✗

Standard streams

std.in receives the command’s piped input.

API	Python SDK	TypeScript SDK
`std.in.readAsString()`	✓	✓
`std.out.puts()`	✓	✓
`std.err.puts()`	✓	✓
`std.out.printf()`	✓	✓
`std.err.printf()`	✓	✓
`std.out.flush()`	✓	✗

Example: forward piped input

const input = std.in.readAsString();
std.out.puts(input);
std.err.puts("Input forwarded.\n");

Limitations

API or behavior	Limitation
`std.out.flush()`	Not available in the TypeScript SDK.
`std.out.printf()`, `std.err.printf()`	C format; return the UTF-8 bytes written. Unlike `printf` on an opened FILE.

`os`

API	Python SDK	TypeScript SDK
`os.readdir()`	✓	✓
`os.stat()`	✓	✓
`os.mkdir()`	✓	✓
`os.remove()`	✓	✓
`os.utimes()`	✓	✓
`os.rename()`	✓	✓
`os.getcwd()`	✓	✓
`os.chdir()`	✓	✓
`os.open()`	✓	✗
`os.read()`	✓	✗
`os.write()`	✓	✗
`os.seek()`	✓	✗
`os.close()`	✓	✗
`os.sleep()`	✓	✗
`os.setTimeout()`	✓	✗
`os.platform`	✓	✓

os.readdir(): Returns [value, errno].

Example: list a workspace directory

const [names, errno] = os.readdir("/data");
if (errno !== 0) {
  throw new Error("Read directory failed: " + errno);
}
console.log(names);

Limitations

API or behavior	Limitation
`os.open()`	Not available in the TypeScript SDK.
`os.read()`	Not available in the TypeScript SDK.
`os.write()`	Not available in the TypeScript SDK.
`os.seek()`	Not available in the TypeScript SDK.
`os.close()`	Not available in the TypeScript SDK.
`os.sleep()`	Not available in the TypeScript SDK.
`os.setTimeout()`	Not available in the TypeScript SDK.
`os.lstat()`	✗
`os.symlink()`	✗
`os.readlink()`	✗
`os.realpath()`	✗
`os.exec()`	✗
`os.stat()`	Returns `[value, errno]`. In Python, `mode` has only the file type bits.
`os.remove()`	`os.remove` also removes an empty directory.
`os.rename()`	`-75` (`EXDEV`) across mounts.
`os.getcwd()`, `os.chdir()`	The shell’s working directory; a change lasts for the run.
`os.platform`	`wasi`.

`console` and printing

API	Python SDK	TypeScript SDK
`console.log()`	✓	✓
`print()`	✓	✓

Example: print a result

console.log("Total:", 2 + 3);
print("done");

Limitations

API or behavior	Limitation
`console.error()`	✗

Runtime globals

API	Python SDK	TypeScript SDK
`scriptArgs`	✓	✓
`atob()`	✓	✓
`btoa()`	✓	✓
`queueMicrotask()`	✓	✓

scriptArgs: The invocation name and arguments.

Example: read arguments and encode text

print(scriptArgs.slice(1));
const encoded = btoa("hello");
print(encoded);
print(atob(encoded));

Unavailable host APIs

Unavailable in this runtime.

Limitations

API or behavior	Limitation
`setTimeout()`	✗
`fetch()`	✗
`require()`	✗
`process`	✗

Notes

-e <code> runs the argument, a file runs a mounted script, and with neither, piped input is the program. A .mjs file runs as an ES module; .js and -e run as classic scripts, and -m forces module mode.
console.log and print add a newline; std.out.puts and std.err.puts write raw.
An error in async code fails the run. In TypeScript this holds for a module and for the promise a script ends with, as in main(); a promise the script drops before then is not reported.
QuickJS cannot reach host files or the network. command_limits bound its time and output, and in TypeScript a run also stops at 64 MiB of memory. Run untrusted or heavy code in a sandbox.

Getting Started

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Configuration

Notifications

Help

Installation

Usage

JavaScript compatibility

`std.open()`

File objects

`std`

Standard streams

`os`

`console` and printing

Runtime globals

Unavailable host APIs

Notes

​Installation

​Usage

​JavaScript compatibility

​std.open()

​File objects

​std

​Standard streams

​os

​console and printing

​Runtime globals

​Unavailable host APIs

​Notes

Installation

Usage

JavaScript compatibility

`std.open()`

File objects

`std`

Standard streams

`os`

`console` and printing

Runtime globals

Unavailable host APIs

Notes