Skip to main content
Every line runs as a non-interactive Bash runs it (bash -c), joined by pipes, redirects, variables and control flow. A session keeps its working directory, variables and functions between calls.

Core Tools

ls, grep, sed, find and the other file and text commands.

Data

jq, checksums, encodings and archives.

Network

curl and wget.
CLIs and programs on machines run in the same lines.

Syntax

Builtins

Expand a builtin to see every flag it takes; help NAME prints its help.
Change the working directory.
Print the working directory.
Print or set the file mode creation mask.
Put variables in the environment of the commands it runs.
Remove variables and functions.
Set variables and their attributes.
Set variables and their attributes; the same as `declare’.
Define variables local to a function.
Make variables read-only.
Set shell options and positional parameters.
Set and unset shell options.
Write the arguments to standard output.
Print arguments under the control of a format.
Read one line and split it into fields.
Read lines into an indexed array.
Read lines into an indexed array; the same as `mapfile’.
Run the commands of a file in the current shell.
Run the arguments as a command line.
Run a program in a nested Mirage shell: the text after -c, a script file, or standard input. bash and sh are aliases.
Options: The options of bash.
Run a command in place of the shell, or redirect the shell.
Define or print aliases.
Remove aliases.
Parse options from the arguments.
Shift the positional parameters.
Evaluate arithmetic expressions.
Run commands when the shell meets signals or events.
Leave the shell.
Do nothing, successfully.
Do nothing, unsuccessfully.
Evaluate a conditional expression.
Report how long a pipeline takes.
Run a command, passing over shell functions, or describe it.
Tell how the shell would run a name.
Options: -a.
Show how to use the shell’s own commands.
Show the manual page of a command.
Print or change the command history.
List the shell’s jobs.
Wait for jobs and return their status.
Send a signal to processes or jobs.
Remove jobs from the shell’s job table.

Sessions

  • ws.shell(...) keeps the session’s working directory, variables and functions. Passing cwd or env runs that call on a copy.
  • Calls on one session run in order. Use separate sessions for concurrent command streams.
  • Python cancels a call through cancel, an event; TypeScript through an abort signal.
  • A session can narrow mount modes to read, write or exec (r, rw, rwx); unlisted mounts keep their own. python3 and js need exec; a shell script runs each command with that command’s permissions. A session profile also hides paths and restricts commands.

Jobs

command &, jobs, wait, kill, disown and ps manage Mirage jobs. There is no terminal job control. A program a runtime runs outside Mirage is a process of its own. ps shows its real PID and the machine it runs on: a host program’s host PID or a machine’s. Mirage’s own commands show mirage:
Mirage’s PIDs start at 4194305, past any Linux PID, so $!, kill, wait and ps -p take either kind.
  • Each line of a session runs as one shell process, $$, which leads the session’s process group. Its jobs, pipeline stages, subshells, command substitutions and nested shells belong to it; a nested bash -c is a process of its own, with its own $$.
  • A negative operand signals a whole group: kill -TERM -- -$$.
  • Unlike Bash, kill also stops the jobs a job started and theirs, even once the job between them has ended.
  • When time runs out, timeout signals its command’s process group, so the jobs the command started stop too. It does not with --foreground, -s INT or -s QUIT.
  • kill takes every Linux signal kill -l lists, by name or number. A signal that ends a process makes wait report 128 plus the signal, as in Bash.
  • STOP pauses a job (ps shows T) and CONT resumes it; a TERM sent meanwhile waits for the CONT. A Mirage command pauses at its next file operation, pipe write, sleep or loop turn; a Monty or Pyodide program where it is; a QuickJS or WASI program at its next file operation or output. In a browser, STOP of a Mirage command is refused.
  • A signal whose default is to be ignored or to pause (CHLD, URG, WINCH, TSTP, TTIN, TTOU) succeeds and changes nothing.
  • A Pyodide program, and a program a runtime started on a machine or the host, gets the signal as sent. One that handles it runs on, and the job ends when it exits, with its status.
  • KILL is sent only for kill -9, timeout -k, or when the workspace shuts down.
  • The shell ignores QUIT, which stops only the program it runs. A signal that stops $$ ends the line with 128 plus the signal and leaves its jobs running.
  • A background job ignores INT and QUIT when it is one program. A job that runs several commands stops only its current command, subshell or pipeline and goes on; a job that runs a function ends.
  • A background job writes where the shell that started it writes, as it writes, so its lines and the foreground’s interleave as in Bash. wait prints none of a job’s output, and fg prints only its command line.
  • A shell() call returns what reached the session while the line ran. Output a job writes after the call returned waits, and comes first in the session’s next call; Bash prints it at once. With sink, it goes to the console while a line runs and waits between lines the same way.
  • $( ) and every pipeline stage but the last wait for the jobs they start. Inside $( ), jobs lists the caller’s jobs, but wait and kill reach only its own; bash -c sees only its own.
  • trap 'commands' EXIT runs at exit, in the frame that called it, and when a child shell (bash -c, a script, ( ), a pipeline stage, $( ), a job) ends, or set -e or a fatal expansion error ends the shell. $? starts at the ending status and stays it unless the cleanup calls exit N or fails under set -e.
  • trap 'commands' ERR runs where set -e would end the shell, and trap 'commands' RETURN as a function or sourced file returns. A function runs its caller’s ERR and RETURN actions only under set -E / set -T.
  • trap -p lists, trap - EXIT removes and trap '' EXIT turns off a registration. A subshell lists its parent’s but runs only its own.
  • A session outlives each shell() call, so a call that returns does not fire EXIT; register it inside bash -c to run before the call returns. Session stores do not keep traps.
  • trap cannot catch a signal: cancellation, kill, timeouts and closing a session end the work without cleanup. Other events (INT, TERM, DEBUG, …) are refused with bash: line 1: trap: TERM: not supported.

Jobs across instances

A workspace built under one workspace_id by several processes on a shared store runs one instance’s lines at a time, as Infrastructure shows. Another instance’s line is refused with an error naming the running one until it closes the workspace. PIDs continue from the highest the workspace has used, so an instance that takes over never reuses one. If the running instance goes away without closing the workspace, another can run lines about 30 seconds later. It reports the jobs left behind as ended with status 129, as Bash reports a hangup, and stops what they ran outside Mirage: a sandbox program through a runtime on the same machine, or a host program on the same machine whose PID still matches.

Several machines

A workspace that runs programs on a machine has processes in more than one place: Mirage’s own commands, and each machine’s programs. These commands answer for all of them, so they read differently from a shell on one Linux host: With no machine, every row is mirage: ps shows only Mirage’s commands, from PID 4194305 up, and nproc or free answers for the workspace, one processor and its max_memory. Processes and jobs shows a session with several machines.

Errors

Errors read as a non-interactive Bash’s do, bash: line N: ..., and a syntax error exits 2.
  • Inside a function, environment replaces bash; inside a sourced file or a script, the file’s path does.
  • $LINENO is the running command’s line and $BASHPID the process running it.
  • When a signal ends a command, Bash’s report line follows it, such as bash: line 1: 12 Killed sleep 3; for a background job, after the next program, subshell or pipeline, or at wait. TERM prints Terminated for a command and nothing for a job; INT and PIPE print nothing. A command substitution reports nothing.
  • A program a runtime runs in the foreground is not a process of its own, so no report line follows when a signal ends it; its status is still 128 plus the signal.

Output to files

Most commands write a redirect’s file as they print, so { echo a; sleep 9; } > f shows a in f at once. tar, gzip and a few machine programs write when they end.
  • Stream as they print: a sandbox program, a host machine’s programs other than its own python3, Mirage’s cat, grep, awk, sed, tee, sort and jq, and the commands in a group, loop or function.
  • Write when they end: tar, gzip, a host machine’s python3, a Daytona program and a microsandbox program given piped input.
  • A command that reads or changes the file meanwhile finds what was written so far. cat and grep refuse to read the file their own output goes to.
  • The output follows the file through a rename the same line makes. The rest is lost once the line removes the file or renames another over it. A rename from another session or through FUSE is not followed.
  • What a stopped command wrote stays, whether kill, timeout or a cancelled call stopped it.
  • A RAM mount shows a streaming write within a tenth of a second; an object store such as S3 publishes it when the write ends.

Limits

Mirage runs a supported subset of Bash, not a full Bash installation.
  • bg, complete, compgen, ulimit, coproc and exec -a/-l are not implemented. A positive read -t is accepted but never times out.
  • set and shopt recognize more option names than they implement.
  • A whole shell() call is parsed before it runs, so enable extglob in an earlier call, or use eval after enabling it.
  • Command substitutions and background jobs do not inherit stdin. A write through an already open output descriptor appends rather than tracking an offset.
  • A process substitution’s /dev/fd/N belongs to the command that opened it. An input producer can keep running after that command ends; the command waits for output consumers. exec 3> >(command) fails with status 2.