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.Syntax
Every supported form
Every supported form
Builtins
Expand a builtin to see every flag it takes;help NAME prints its help.
Run a program in a nested Mirage shell: the text after
-c, a script file, or standard input. bash and sh are aliases.Sessions
ws.shell(...)keeps the session’s working directory, variables and functions. Passingcwdorenvruns 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 abortsignal. - A session can narrow mount modes to
read,writeorexec(r,rw,rwx); unlisted mounts keep their own.python3andjsneedexec; 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:
$!, kill, wait
and ps -p take either kind.
Processes and groups
Processes and groups
- 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 nestedbash -cis a process of its own, with its own$$. - A negative operand signals a whole group:
kill -TERM -- -$$. - Unlike Bash,
killalso stops the jobs a job started and theirs, even once the job between them has ended. - When time runs out,
timeoutsignals its command’s process group, so the jobs the command started stop too. It does not with--foreground,-s INTor-s QUIT.
Signals
Signals
killtakes every Linux signalkill -llists, by name or number. A signal that ends a process makeswaitreport 128 plus the signal, as in Bash.STOPpauses a job (psshowsT) andCONTresumes it; aTERMsent meanwhile waits for theCONT. 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,STOPof 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.
KILLis sent only forkill -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
INTandQUITwhen 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.
Job output
Job output
- 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.
waitprints none of a job’s output, andfgprints 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. Withsink, 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$( ),jobslists the caller’s jobs, butwaitandkillreach only its own;bash -csees only its own.
Traps
Traps
trap 'commands' EXITruns atexit, in the frame that called it, and when a child shell (bash -c, a script,( ), a pipeline stage,$( ), a job) ends, orset -eor a fatal expansion error ends the shell.$?starts at the ending status and stays it unless the cleanup callsexit Nor fails underset -e.trap 'commands' ERRruns whereset -ewould end the shell, andtrap 'commands' RETURNas a function or sourced file returns. A function runs its caller’sERRandRETURNactions only underset -E/set -T.trap -plists,trap - EXITremoves andtrap '' EXITturns 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 fireEXIT; register it insidebash -cto run before the call returns. Session stores do not keep traps. trapcannot catch a signal: cancellation,kill, timeouts and closing a session end the work without cleanup. Other events (INT,TERM,DEBUG, …) are refused withbash: line 1: trap: TERM: not supported.
Jobs across instances
A workspace built under oneworkspace_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.
Error and report lines in detail
Error and report lines in detail
- Inside a function,
environmentreplacesbash; inside a sourced file or a script, the file’s path does. $LINENOis the running command’s line and$BASHPIDthe 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 atwait.TERMprintsTerminatedfor a command and nothing for a job;INTandPIPEprint 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.
Which commands stream, and what a reader sees
Which commands stream, and what a reader sees
- Stream as they print: a sandbox program, a
hostmachine’s programs other than its ownpython3, Mirage’scat,grep,awk,sed,tee,sortandjq, and the commands in a group, loop or function. - Write when they end:
tar,gzip, ahostmachine’spython3, 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.
catandgreprefuse 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,timeoutor 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,coprocandexec -a/-lare not implemented. A positiveread -tis accepted but never times out.setandshoptrecognize more option names than they implement.- A whole
shell()call is parsed before it runs, so enableextglobin an earlier call, or useevalafter 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/Nbelongs 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 status2.