Skip to main content
A line an agent writes can loop forever, start processes without end, or grow a variable until memory runs out. In Mirage it runs beside other agents’ sessions, in one process or one isolate, so each of these would cost them too. Every limit below is on by default except max_workspaces and capacity, and each stops its case the way bash and Linux would, with the same exit status. Three layers set them:
  • The host (the server, or a Cloudflare app) sets ceilings. A workspace may set a lower value, never a higher one. A workspace that sets null (no limit) gets the ceiling.
  • The workspace sets each limit for every session it holds.
  • A profile overrides processes and command_limits for its sessions, field by field over the workspace’s. It may raise a workspace’s value as well as lower it; only a host ceiling holds it.

What each limit stops

What each limit counts:
  • max_env: bytes in a session’s variables, functions, aliases and positional parameters, plus 1 per array element and parameter.
    • A session that would start over it, from env, a profile or a snapshot, is refused.
  • processes.max: pipeline stages, subshells and background jobs running in the session.
  • max_body_bytes: decoded bytes of one API reply read whole.
    • A call’s own cap, or the memory left under max_memory, can stop it sooner.
    • An error reply keeps only its first 64 KiB.
For how the timeout command stops jobs, see Shell. Some bounds are fixed:
  • A session id, profile name or workspace id is 1 to 128 characters, with no control characters.
  • A command log read returns the newest 10,000 entries, and /.bash_history the newest 10,000 commands. A workspace that keeps its command logs in memory holds at most 8 MB of logs, and drops the oldest entries first.

Set them on a workspace

Here a batch session runs 512 processes and 15-minute lines, and every other session 64 processes and 2-minute lines. See configuration and profiles.

Command output

cat, grep, rg, head and tail print at most 2,000 lines by default. command_limits sets a cap on the workspace, on a mount for the commands that run on it, or on a profile for its sessions:
  • A key is a command’s name, "@all" for every command, or "@line" for the whole line. Any other @ key, or *, is refused.
  • Each field comes from the most specific entry that sets it: the profile, the mount, then the workspace (each by the command’s name, then "@all"), then the command’s own default. An entry that sets one field inherits the rest.
  • A command spanning mounts takes the tightest limit among them.
  • Caps apply to what a command prints. cat big.txt; echo end still prints end, and cat big.txt | wc -l counts every line, since input to a pipe, redirect or substitution is not cut.

Line time

A line has one time limit: the @line entry’s timeout_seconds, on the workspace or a profile. It bounds the whole top-level line, with its loops, pipelines and the lines it runs (sh -c, eval, xargs), and is 600 seconds unless set; 0 or null 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 runs under the same limit, counted from its own start, and can outlive the line that started it.
  • A mount takes no @line entry, since a line spans mounts. To bound one command inside a line, use timeout 5 grep -r TODO /data.

Memory

A workspace’s max_memory, a size, bounds the files in its RAM mounts and each object a command builds while it runs: a $( ) capture, a read value, a file read whole, a jq -s input, the parts an office document links to (and, in a Word document or a deck, their parsed elements), a stream pdftotext decodes, 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 set; null lifts it. Commands running at once can each take close to what is left, so it bounds each object, not their sum. The read cache has its own limit.
  • A write that would pass it fails with Disk quota exceeded.
  • A command whose object passes it fails with <command>: memory exhausted, and the line goes on. A capture or read that passes it ends the line with line: memory exhausted and exit 1.
  • A python3 run raises MemoryError, and a node run gets InternalError: out of memory.
  • gzip, gunzip, zgrep, iconv -o, tar, sort, split, csplit, redirects and script output stream, or spill to scratch storage. A tar member of unknown size is staged before its header is written. zip copies unchanged members but reads the whole archive to update it.
  • A single large record, archive metadata, awk arrays, tac with a regex, diff, patch and jq --slurp keep their working data in memory, and a whole-result API call collects its output.
  • rg limits each search’s scratch storage to 64 MiB and refuses a pattern that would need more; --regex-size-limit governs compilation only.
  • Disk, SSH, OPFS, GridFS, Drive, Dropbox, OneDrive, SharePoint and Box write by streaming upload. S3 uploads in 8 MiB parts, up to 10,000 parts (about 78 GiB). A presigned or conditional write to a custom S3 endpoint is one PUT of at most 5 GiB, and an append to S3 uploads the object again.
  • Streaming bounds memory, not CPU: compression and comparison cost the same, and spilling adds local I/O.

Host ceilings

A tenant controls its own workspace’s config and profiles, so a host that runs other people’s agents holds them under ceilings. Each comes from the app’s option, else its environment variable, else its key in ~/.mirage/config.toml:
The ceilings hold whatever sets the value: a create request, a profile replaced over HTTP, or a snapshot loaded later. The Python and TypeScript servers and the Cloudflare app take the same settings as options.