Limits

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

Case	Limit	Default	What the line sees
A loop that never ends	`command_limits` `@line` `timeout_seconds`	600 seconds	exit 124, `line: timed out after 600s`
A fork bomb, `b() { b \| b; }; b`	`processes.max`	128 per session	exit 254, `bash: fork: Resource temporarily unavailable`
A variable that keeps doubling, `x=$x$x`	`max_env`	`2MB` per session	exit 2, `bash: xmalloc: cannot allocate N bytes (past max_env of N bytes, a mirage workspace setting)`
A file or a command’s output held in memory	`max_memory`	`96MB` per workspace	exit 1, `line: memory exhausted`; a write to a RAM file fails with `Disk quota exceeded`
One API reply read whole	`max_body_bytes`	`64MB`	the call fails
A command printing a huge result	`command_limits` `max_lines`	2,000 lines for `cat`, `grep`, `rg`, `head` and `tail`	the output is cut, with a notice on stderr; the exit code is kept
A walk over a huge mount	`command_limits` `walk_limit`	set by each VFS	the walk stops at the limit
A mount filling up	`capacity` on a RAM, disk, Redis, OPFS or SQL mount	no cap	`Disk quota exceeded`
The read cache growing	`cache.limit`	`32MB` in memory. Redis removes nothing at its `limit`: cap it with Redis’s own `maxmemory`	nothing; see File Cache
Deep recursion in functions, `source`, `eval` or `bash -c`	32 levels	fixed; `FUNCNEST` can lower it	exit 1, `environment: line 1: f: maximum function nesting level exceeded (32)`
Many sessions on one workspace	`max_sessions`	16, or 4 on Cloudflare Workers	HTTP 429
Many workspaces on one server	`max_workspaces`	no cap	HTTP 503
A burst of requests	`rate_limits`	`ip=1000/minute`	HTTP 429

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

max_memory: 32MB
max_env: 2MB
processes: {max: 64}
command_limits:
  "@line": {timeout_seconds: 120}
profiles:
  batch:
    processes: {max: 512}
    command_limits:
      "@line": {timeout_seconds: 900}

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

Set the host’s 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:

Key	Env var	Holds
`max_memory`	`MIRAGE_MAX_MEMORY`	any workspace’s `max_memory`
`max_env`	`MIRAGE_MAX_ENV`	any workspace’s `max_env`
`max_processes`	`MIRAGE_MAX_PROCESSES`	any session’s `processes.max`
`max_line_seconds`	`MIRAGE_MAX_LINE_SECONDS`	any line’s time limit
`max_sessions`	`MIRAGE_MAX_SESSIONS`	the sessions each workspace holds
`max_workspaces`	`MIRAGE_MAX_WORKSPACES`	the workspaces the server holds

[daemon]
max_memory = "64MB"
max_env = "2MB"
max_processes = 64
max_line_seconds = 300
max_sessions = 8

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.

Getting Started

Examples

Agents

Configuration

VFS

Integration

CLIs

Mirage Shell

Policy

Machines

Infrastructure

Notifications

Help

What each limit stops

Set them on a workspace

Set the host’s ceilings