> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirage Shell

> Run Bash commands, pipelines and scripts across every mount.

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.

> [card] [Core Tools](https://docs.mirage.strukto.ai/home/core/tools.md)
>
> `ls`, `grep`, `sed`, `find` and the other file and text commands.

> [card] [Data](https://docs.mirage.strukto.ai/home/core/data.md)
>
> `jq`, checksums, encodings and archives.

> [card] [Network](https://docs.mirage.strukto.ai/home/core/network.md)
>
> `curl` and `wget`.

[CLIs](https://docs.mirage.strukto.ai/home/setup/clis.md) and programs on [machines](https://docs.mirage.strukto.ai/home/setup/machine/overview.md)
run in the same lines.

```bash theme={null}
$ cd /s3/logs
$ for f in *.jsonl; do echo "$f $(grep -c error "$f")"; done | sort -k2 -nr
app.jsonl 42
worker.jsonl 7
```

## Syntax

| Feature | Example |
| - | - |
| Lists and pipes | `grep -c error app.log \| sort -n && echo ok` |
| Redirects | `ls /data /missing > out 2>&1` |
| Here-strings and documents | `wc -w <<< "one two"`, `cat <<EOF` |
| Expansion | `echo ${name:-world} $(date) $((2 + 3))` |
| Globs | `shopt -s globstar; ls /data/**/*.json` |
| Arrays | `declare -A m=([k]=v); echo ${m[k]}` |
| Conditions | `[[ $f == *.json ]] && echo json` |
| Loops | `for f in *.txt; do wc -l < "$f"; done` |
| Functions | `greet() { echo "hi $1"; }; greet sam` |
| Groups | `{ echo a; echo b; } > out`, `( cd /data && ls )` |
| Process substitution | `diff <(sort a) <(sort b)` |
| Background jobs | `sleep 30 & wait $!` |
| Timing | `time -p grep -r TODO /data` |

> [accordion] Every supported form
>
> | Feature | Supported |
> | - | - |
> | Command lists | `;`, newlines, `&&`, `\|\|` and `!` |
> | Pipelines | `\|` and `\|&`; `$?` and `${PIPESTATUS[@]}`. With job control off, `shopt -s lastpipe` runs the last stage in the current shell |
> | Redirection | `>`, `>>`, `<`, `<>`, `>\|`, `2>`, `2>&1`, `&>`, `&>>`; duplicating and closing descriptors |
> | Inline input | `<<EOF`, `<<-EOF` and `<<<` |
> | Quoting | `'...'`, `"..."`, backslash escapes and `$'...'` |
> | Expansion | Variables, `${name:-default}`, substring and pattern operations, `$(command)`, backticks and `$((expression))` |
> | Paths | `~`, braces, `*`, `?` and bracket patterns; `GLOBIGNORE` |
> | Extended patterns | `extglob`, `globstar`, `dotglob`, `nullglob` and `failglob` through `shopt` |
> | Variables | Scalars, indexed and associative arrays, positional arguments, `$RANDOM`, `${FUNCNAME[@]}` and `${BASH_SOURCE[@]}` |
> | Conditions | `if` / `elif` / `else`, `test`, `[ ... ]` and `[[ ... ]]`; `shopt -s nocasematch` |
> | Loops | `for`, arithmetic `for`, `while`, `until` and `select`; `break` and `continue` |
> | Functions and branching | `case`, `name() { ...; }`, `function` and `return` |
> | Groups | `{ ...; }` shares the session; `( ... )` runs in a copy of it |
> | Process substitution | `<(command)` and `>(command)` as live `/dev/fd/N` pipes; `$!` holds the last one's PID |
> | Background work | `command &`, `jobs`, `wait`, `kill`, `disown` and `ps`: see [Jobs](#jobs) |
> | Timing | `time`, `time -p` and `TIMEFORMAT`; CPU times read zero |
> | Comments | `#` outside quotes |

## Builtins

Expand a builtin to see every flag it takes; `help NAME` prints its help.

**cd**

Change the working directory.

**4 flags**

**-L**

Keep symbolic links in the new path (the default).

**-P**

Resolve symbolic links in the new path.

**-e**

With -P, fail when the new path cannot be resolved.

**-@**

Accepted, with no effect.

**pwd**

Print the working directory.

**2 flags**

**-L**

Print it as reached, symbolic links kept (the default).

**-P**

Print it with symbolic links resolved.

**umask**

Print or set the file mode creation mask.

**2 flags**

**-p**

Print the mask in a reusable form.

**-S**

Print the mask symbolically.

**export**

Put variables in the environment of the commands it runs.

**3 flags**

**-f**

Each NAME is a shell function.

**-n**

Take the export mark off each NAME.

**-p**

Print every exported variable in a reusable form.

**unset**

Remove variables and functions.

**3 flags**

**-f**

Each NAME is a function.

**-v**

Each NAME is a variable.

**-n**

Remove the reference NAME itself, not what it names.

**declare**

Set variables and their attributes.

**14 flags**

**-a**

Make each NAME an indexed array.

**-A**

Make each NAME an associative array.

**-f**

Act on functions only; with -p, print their definitions.

**-F**

Print function names only.

**-g**

Make NAME global even inside a function.

**-i**

Make each NAME an integer, assigned arithmetically.

**-I**

Inside a function, start from an outer variable's attributes.

**-l**

Lowercase each value as it is assigned.

**-n**

Make NAME a reference to the variable its value names.

**-p**

Print each NAME with its attributes and value.

**-r**

Make each NAME read-only.

**-t**

Give each NAME the trace attribute.

**-u**

Uppercase each value as it is assigned.

**-x**

Export each NAME.

**typeset**

Set variables and their attributes; the same as \`declare'.

**14 flags**

**-a**

Make each NAME an indexed array.

**-A**

Make each NAME an associative array.

**-f**

Act on functions only; with -p, print their definitions.

**-F**

Print function names only.

**-g**

Make NAME global even inside a function.

**-i**

Make each NAME an integer, assigned arithmetically.

**-I**

Inside a function, start from an outer variable's attributes.

**-l**

Lowercase each value as it is assigned.

**-n**

Make NAME a reference to the variable its value names.

**-p**

Print each NAME with its attributes and value.

**-r**

Make each NAME read-only.

**-t**

Give each NAME the trace attribute.

**-u**

Uppercase each value as it is assigned.

**-x**

Export each NAME.

**local**

Define variables local to a function.

**readonly**

Make variables read-only.

**4 flags**

**-a**

Each NAME is an indexed array.

**-A**

Each NAME is an associative array.

**-f**

Each NAME is a shell function.

**-p**

Print every read-only variable in a reusable form.

**set**

Set shell options and positional parameters.

**20 flags**

**-a**

Export every variable that is assigned.

**-b**

Accepted, with no effect.

**-e**

Leave the shell when a command fails.

**-f**

Turn off pathname expansion.

**-h**

Accepted, with no effect.

**-k**

Accepted, with no effect.

**-m**

Accepted, with no effect.

**-n**

Read commands without running them.

**-o \<name>**

Turn on the option called NAME.

**-p**

Accepted, with no effect.

**-t**

Accepted, with no effect.

**-u**

Treat an unset variable as an error.

**-v**

Print each line as it is read.

**-x**

Print each command as it runs.

**-B**

Turn on brace expansion.

**-C**

Refuse to overwrite files with \`>'.

**-E**

Pass the ERR trap on to functions.

**-H**

Accepted, with no effect.

**-P**

Resolve symbolic links when changing directory.

**-T**

Pass the RETURN trap on to functions.

**shopt**

Set and unset shell options.

**5 flags**

**-o**

Each OPTNAME is an option of \`set -o'.

**-p**

Print in a reusable form.

**-q**

Print nothing; the status tells.

**-s**

Turn each OPTNAME on.

**-u**

Turn each OPTNAME off.

**echo**

Write the arguments to standard output.

**3 flags**

**-n**

Leave out the final newline.

**-e**

Interpret backslash escapes such as \n and \t.

**-E**

Leave backslash escapes as written (the default).

**printf**

Print arguments under the control of a format.

**1 flag**

**-v \<var>**

Store the output in VAR instead of printing it.

**read**

Read one line and split it into fields.

**11 flags**

**-a \<array>**

Assign the fields to ARRAY, from index 0.

**-d \<delim>**

Read up to DELIM rather than a newline.

**-e**

Accepted, with no effect.

**-i \<text>**

Accepted, with no effect.

**-n \<nchars>**

Stop after NCHARS characters or at the delimiter.

**-N \<nchars>**

Read exactly NCHARS characters.

**-p \<prompt>**

Print PROMPT on standard error first.

**-r**

Take backslashes literally.

**-s**

Accepted, with no effect.

**-t \<timeout>**

Give up after TIMEOUT seconds.

**-u \<fd>**

Read from file descriptor FD.

**mapfile**

Read lines into an indexed array.

**8 flags**

**-d \<delim>**

End each line at DELIM rather than at a newline.

**-n \<count>**

Read at most COUNT lines; 0 reads them all.

**-O \<origin>**

Store the first line at index ORIGIN rather than 0.

**-s \<count>**

Skip the first COUNT lines.

**-t**

Drop the delimiter from the end of each line.

**-u \<fd>**

Read from file descriptor FD rather than standard input.

**-C \<callback>**

Run CALLBACK every QUANTUM lines.

**-c \<quantum>**

How many lines go between CALLBACK runs; 5000 by default.

**readarray**

Read lines into an indexed array; the same as \`mapfile'.

**8 flags**

**-d \<delim>**

End each line at DELIM rather than at a newline.

**-n \<count>**

Read at most COUNT lines; 0 reads them all.

**-O \<origin>**

Store the first line at index ORIGIN rather than 0.

**-s \<count>**

Skip the first COUNT lines.

**-t**

Drop the delimiter from the end of each line.

**-u \<fd>**

Read from file descriptor FD rather than standard input.

**-C \<callback>**

Run CALLBACK every QUANTUM lines.

**-c \<quantum>**

How many lines go between CALLBACK runs; 5000 by default.

**source, .**

Run the commands of a file in the current shell.

**eval**

Run the arguments as a command line.

**bash**

Run a program in a nested Mirage shell: the text after `-c`, a script file, or standard input. `bash` and `sh` are aliases.

**16 flags**

**-c \<text>**

Read commands from the next argument and execute them.

**-s**

Read commands from stdin instead of from an argument.

**-l**

(Ignored) Login shell. Mirage does not source profile files.

**-i**

(Ignored) Interactive flag. Mirage shells are non-interactive.

**-e**

Exit on first error.

**-u**

Treat unset variables as errors.

**-x**

Print commands as they execute.

**--debug**

(Ignored) Debugging mode.

**--init-file \<text>**

(Ignored) Read this file instead of \~/.bashrc.

**--login**

(Ignored) Login shell.

**--noediting**

(Ignored) No line editing.

**--noprofile**

(Ignored) Skip profile files.

**--norc**

(Ignored) Skip rc files.

**--posix**

(Ignored) POSIX-conformant mode.

**--rcfile \<text>**

(Ignored) Read this file instead of \~/.bashrc.

**--verbose**

Print input lines as they are read.

**sh**

Options: The options of `bash`.

**exec**

Run a command in place of the shell, or redirect the shell.

**1 flag**

**-c**

Run COMMAND with an empty environment.

**alias**

Define or print aliases.

**1 flag**

**-p**

Print every alias in a form the shell can read back.

**unalias**

Remove aliases.

**1 flag**

**-a**

Remove every alias.

**getopts**

Parse options from the arguments.

**shift**

Shift the positional parameters.

**let**

Evaluate arithmetic expressions.

**trap**

Run commands when the shell meets signals or events.

**2 flags**

**-l**

Not supported.

**-p**

Print the traps that are set.

**exit**

Leave the shell.

**true, :**

Do nothing, successfully.

**false**

Do nothing, unsuccessfully.

**test**

Evaluate a conditional expression.

**time**

Report how long a pipeline takes.

**1 flag**

**-p**

Print the times in the portable format.

**command**

Run a command, passing over shell functions, or describe it.

**3 flags**

**-p**

Search a default PATH that finds the standard tools.

**-v**

Print the word or path the shell would run.

**-V**

Describe in words what the shell would run.

**type**

Tell how the shell would run a name.

**5 flags**

**-a**

Every place NAME is found, not only the first.

**-f**

Pass over shell functions.

**-p**

Print the file NAME runs, if it is one.

**-P**

Print the file NAME would run, searching PATH.

**-t**

Print one word: alias, keyword, function, builtin or file.

**which**

Options: `-a`.

**help**

Show how to use the shell's own commands.

**3 flags**

**-d**

Print each command's one-line summary.

**-m**

Print each command's help as a manual page.

**-s**

Print each command's synopsis only.

**man**

Show the manual page of a command.

**5 flags**

**-a, --all**

Show every page that matches PAGE.

**-f, --whatis**

Print the summary line of each PAGE.

**-k, --apropos**

Search the names and summaries of every page.

**-?, -h, --help**

Print this list.

**--usage**

Print the usage line.

**history**

Print or change the command history.

**8 flags**

**-c**

Clear the history.

**-d \<offset>**

Delete the entry at OFFSET; below 0, from the end.

**-a**

Accepted, with no effect: the history file is the list.

**-n**

Accepted, with no effect: the history file is the list.

**-r**

Accepted, with no effect: the history file is the list.

**-w**

Accepted, with no effect: the history file is the list.

**-p**

Print each ARG, with no history expansion.

**-s**

Add the ARGs to the history as one entry.

**jobs**

List the shell's jobs.

**5 flags**

**-l**

Add each job's process ID.

**-n**

Only jobs whose state changed since last reported.

**-p**

Print process IDs only.

**-r**

Running jobs only.

**-s**

Stopped jobs only.

**wait**

Wait for jobs and return their status.

**4 flags**

**-f**

Wait until each ID ends, not only until it changes state.

**-n**

Wait for the next job to end and return its status.

**-m \<machine>**

The machine the IDs are on.

**-p \<var>**

Store in VAR the ID whose status is returned.

**kill**

Send a signal to processes or jobs.

**4 flags**

**-s \<sig>**

The signal to send, by name.

**-n \<sig>**

The signal to send, by number.

**-l**

List the signal names, or name the numbers given.

**-m \<machine>**

The machine the IDs are on.

**disown**

Remove jobs from the shell's job table.

**3 flags**

**-a**

Remove every job.

**-h**

Keep the job, but do not hang it up when the shell exits.

**-r**

Remove running jobs only.

## 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](https://docs.mirage.strukto.ai/home/configuration/session.md) 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](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#processes-and-jobs)'s. Mirage's own
commands show `mirage`:

```
    PID MACHINE                         CMD
4194305 mirage                          ps
4194306 mirage                          sleep 300
  19443 host:my-laptop                  python3 train.py
```

Mirage's PIDs start at 4194305, past any Linux PID, so `$!`, `kill`, `wait`
and `ps -p` take either kind.

> [accordion] 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 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`.

> [accordion] Signals
>
> * `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.

> [accordion] 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. `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.

> [accordion] Traps
>
> * `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](https://docs.mirage.strukto.ai/home/infrastructure/overview.md#workspace-state) runs one instance's
lines at a time, as [Infrastructure](https://docs.mirage.strukto.ai/home/infrastructure/jobs.md#several-instances-of-one-workspace)
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](https://docs.mirage.strukto.ai/home/setup/machine/overview.md)
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:

| Command | On one Linux host | In Mirage |
| - | - | - |
| `ps` | The host's processes | What the session started, on every machine, with a `MACHINE` column; `-p` and `-C` select as Linux's do, `--machine NAME` narrows it to one, `-o pid,machine` picks columns |
| `jobs`, `wait`, `kill` | One process table | Each machine is asked what runs there. A PID two machines share is refused as ambiguous; name the machine with `-m` or `--machine`: `kill -m box 13` |
| `pgrep`, `pkill`, `pidof`, `killall` | Every process on the host | Only what Mirage started, on every machine at once |
| `nproc`, `hostname`, `lscpu`, `free` | The host | One row per machine, with the machine on the right. With one machine, `free` prints that machine's table alone, as Linux's `free` does. Inside `$( )`, the default machine's answer; `--machine NAME` picks one, `--machine mirage` the workspace |
| `uptime`, `top` | Always there | Only while a machine or the host runs programs; `top` needs `-b` |
| `df`, `mount` | The host's disks | The workspace's mounts |

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`](https://docs.mirage.strukto.ai/home/limits#memory).
[Processes and jobs](https://docs.mirage.strukto.ai/home/setup/machine/overview.md#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.

> [accordion] Error and report lines in detail
>
> * 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.

> [accordion] Which commands stream, and what a reader sees
>
> * 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.