Skip to main content
Mirage keeps large results from flooding an agent. cat, grep, rg, head, and tail return at most 2,000 lines by default, a line stops after 600 seconds, a workspace holds at most 96 MB in memory, and a walk stops at its mount’s walk_limit.

Set limits

Set a workspace default for every session, a mount override for commands that run on that mount, or a profile override for sessions created with that profile.
The workspace YAML uses the same fields in snake case under command_limits. A key is a command’s name or one of two groups, spelled with the @ runtime captures use for theirs: @all, every command, and @line, the whole line. A YAML key that starts with @ is quoted ("@all":). Any other @ key, or *, is refused when the table is built.

Choose which limit applies

Each field comes from the most specific entry that sets it: the session profile, the mount, then the workspace (each looked up by the command’s name, then under "@all", the entry for every command), the command’s own default, and Mirage’s built-in default; a walk’s walk_limit ends at the mount backend’s default. An entry that sets one field inherits the rest.

Limit a line’s time

A line has one time limit: the @line entry’s timeout_seconds, on the workspace or a profile (the profile’s over the workspace’s). It bounds the whole top-level line, loops, pipelines and the lines it runs (sh -c, eval, xargs) included, and is 600 seconds unless an entry sets it; 0 or None lifts it. A line past it exits 124 with line: timed out after Ns. A program it runs gets TERM and a second to finish, then KILL, as with timeout -k. A background job (cmd &) runs under the same limit, counted from its own start. The line that started it can end or time out and leave it running; past its own limit the job ends with status 124 and the same message. kill stops it sooner. No other entry takes timeout_seconds, an @line entry takes nothing else, and a mount has no @line entry, since a line spans mounts; each is refused when the workspace, mount or profile is built. To bound one command inside a line, use timeout, as in bash: timeout 5 grep -r TODO /data. For commands spanning multiple mounts, Mirage applies the tightest resolved limit from those mounts.

Limit a workspace’s memory

A workspace’s max_memory, a size, bounds what it holds in memory: the files in its RAM mounts, and each object a command builds while it runs, such as a $( ) capture, a read value, a file read whole, a jq -s input or a Monty, Pyodide or QuickJS program’s memory. Such an object must fit in what the RAM files leave. It is 96 MB unless the workspace sets it, and None (null in TypeScript and YAML) lifts it. The read cache keeps its own limit. Commands running at the same moment can each take close to what is left, so it bounds each object, not their sum.
A write that would pass it fails with Disk quota exceeded. A command whose own object passes it fails with <command>: memory exhausted and the line goes on; when a capture or a read passes it, the line ends with line: memory exhausted and exit 1. A python3 run raises MemoryError, and a node run gets InternalError: out of memory.

Handle a reached limit

  • max_lines and max_bytes cap output. Use None in Python or null in TypeScript for no cap.
  • timeout_seconds, on the @line entry only, sets the deadline of a line and of each background job. A line or job that passes it exits 124.
  • walk_limit caps the entries one walk lists on a mount, -1 for no cap; see walks.
  • on_exceed=TRUNCATE, the default, returns the capped output, writes a notice to stderr, and preserves the command’s exit code.
  • on_exceed=ERROR drops the output and exits 1, so && and || see a failure.
In TypeScript, use the camel-case forms maxLines, maxBytes, timeoutSeconds, walkLimit, and onExceed. Caps apply to each command’s printed output. cat big.txt; echo end still prints end. Input to a pipe, redirect, or command substitution is not cut, so cat big.txt | wc -l counts every line.