> ## 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.

# Machines

> Choose where programs run, in Mirage, on the host, or on a container, VM, cloud sandbox or remote machine.

A machine is a Unix-like computer that runs programs as processes. Mirage
runs its own commands (`grep`, `cat`, pipes, redirects) itself; `python3`,
`node` and every other program run on the machine that captures them.

| Machine | Runs | SDK |
| - | - | - |
| [In Process](https://docs.mirage.strukto.ai/home/setup/machine/in_process.md) | Python or JavaScript on a [runtime](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md), inside Mirage | both |
| [Remote](https://docs.mirage.strukto.ai/home/setup/runtime/monty.md#remote-server) | Python on a remote Monty server (`runtime: monty`), with files and environment from Mirage | Python, Node |
| [Host](https://docs.mirage.strukto.ai/home/setup/machine/host.md) | programs installed on the host, confined by a `sandbox` on Linux | Python, Node |
| A [provider](#providers) | programs installed on a container, VM, cloud sandbox or SSH host you already have | Python, Node; E2B also in the browser |

A [runtime](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md) is an interpreter that runs inside
Mirage, on an `in_process` machine: Monty, WASI, Pyodide or QuickJS. A host or
a provider takes no runtime; it runs the programs installed on it.

## Routing

`machines` is ordered: the first machine whose `captures` name a program runs
it, and Mirage runs the rest itself. Without the key, `python3`, `node` and
`js` answer `command not found` (exit 127) until a machine captures them.

```yaml theme={null}
machines:
  py:
    provider: in_process
    runtime: monty
  box:
    provider: docker
    container: my-sandbox
    mount_type: ssh
```

Each entry names its `provider`: `in_process`, `host`, `remote` or a
[provider](#providers). The entry's other keys are its settings, snake\_case in
YAML for both SDKs; a key it does not take is refused.

With two `@external` machines the first one runs every program, and the
second runs what it names on its own:

```yaml theme={null}
machines:
  py:
    provider: docker
    container: py-sandbox
    captures: [python3]
  js:
    provider: docker
    container: js-sandbox
    captures: [node]
```

A line or a command can also name its machine: `execute(machine=)`, a
`machine` on the shell request, or a policy's `Route(machine=)`: see
[Route Machine](https://docs.mirage.strukto.ai/home/policy/route-machine.md). A named machine runs what it
captures; everything else stays where it would run. When a machine takes
`@line`, a line that names a different machine does not run whole on the
`@line` machine: the named machine runs what it captures, and each other
command runs where its own capture sends it, or in Mirage. On a line the
`@line` machine runs whole, a command that a `pre_command` policy routes to
another machine capturing it exits 126.

## Captures

`captures` lists the programs a machine takes:

| Entry | Takes |
| - | - |
| A name, such as `python3` or `ffmpeg` | That program |
| `@python`, `@js` | `python3` and `python`, or `node` and `js` |
| `@external` | Every program Mirage does not have itself, such as `gcc`, `ffmpeg`, `perl` or a vendor CLI |
| `@line` | The whole line, Mirage's own commands included (any machine that runs a shell line) |

| Machine | Default `captures` |
| - | - |
| `in_process` with Monty, WASI or Pyodide, `remote` with Monty, `host` | `@python` |
| `in_process` with QuickJS | `@js` |
| `host` with a `sandbox`, a provider | `@external` |

* Mirage's own commands (`cat`, `grep`, `sha1sum`), pipes and redirects stay
  in Mirage. Name `cat`, `grep`, `ps` or `kill` to run it on a machine
  instead; `cd`, `export`, `echo`, `ln`, functions and installed CLIs stay
  in Mirage even when named.
* `@external` does not take `python`, `python3`, `node` or `js`: Mirage has
  those itself and gives them to the Python or JavaScript machine in the list.
  Name them, or `@python` or `@js`, to send them somewhere else. A tool such
  as `pip` is an ordinary program: capture it on the same machine when
  packages must land there, as in `captures: ["@python", "pip", "pip3"]`.
* Monty, WASI, Pyodide and QuickJS take only their own interpreter's
  names; naming another program on one is refused when the workspace is
  built. A `host` machine and a provider take any name.
* Mirage matches the program each command really runs, after expanding its
  words, so `python3` is captured in `$P x`, `env python3 x`,
  `timeout 5 python3 x`, `sh -c 'python3 x'` and `xargs python3`. Each command
  on a line matches on its own, so `cat a.txt | python3 x` sends only `python3`.
* `nice`, `nohup`, `stdbuf`, `ionice` and `setsid` run their program where
  it runs alone: `nice gcc x.c` where `gcc` is taken, `nice grep` in Mirage,
  and permission rules and a `pre_command` route answer for the program. The
  process the program runs as carries the change: `ps` shows its niceness,
  a `nohup` job ignores `HUP`, a `setsid` one leads its own group and
  session. A `host` machine or a provider is handed the wrapper with the
  program, so it makes the change there.
* An absolute path Mirage has no file for, such as `/usr/bin/ffmpeg`, goes to
  the `@external` machine. A profile's `commands` judges it by its name, so
  under `"*": deny` it runs only when the tree names it: `ffmpeg: allow`
  lets `/usr/bin/ffmpeg` run.
* On a `host` machine or a provider, a program a captured program
  starts runs there: `make` running `gcc`, or a script calling `subprocess`. Capture the
  launcher on the same machine as the tool. A Pyodide script's `subprocess`
  calls go back through Mirage's routing like any other command.
* An alias is captured as the word it expands to, once `shopt -s
  expand_aliases` is on and the alias was defined on an earlier line.
* If two machines take the same name or group, the first wins and Mirage
  logs a warning.
* A program no machine takes exits 127, `command not found`.
* `captures` only places programs. To limit what a session may run at all,
  use its profile's `commands`; see
  [Command rules](https://docs.mirage.strukto.ai/home/configuration/session.md#command-rules).
* A name only `@external` takes has no file, so `which`, `command -v` and
  `type` report it missing; running it still works.
* Globs expand against the workspace first (`python3 job.py *.csv` runs
  `python3 job.py a.csv b.csv`), and permission rules judge that argv.

```yaml theme={null}
machines:
  box:
    provider: docker
    container: my-sandbox
    captures: ["@python", "@external"]
```

Here `python3 job.py | grep error` runs `python3` in the container and
`grep` in Mirage, and `ffmpeg -i a.mp4 b.webm` runs in the container.

## Files

![Monty, WASI, Pyodide and QuickJS access workspace files directly. Host programs use a FUSE folder. Machines connect through SSH or FUSE.](https://mintcdn.com/struktoai/wbn_tJeahvJMuT6I/images/runtime-light.svg?fit=max\&auto=format\&n=wbn_tJeahvJMuT6I\&q=85\&s=fc1754f9018a9bb2596f28105b96efdc)

| Where | Reaches the workspace through | Outside the workspace |
| - | - | - |
| Monty, WASI, QuickJS | directly | no host files or network |
| Pyodide | directly | Browser programs retain JavaScript and network access; `init_module` enables host access. See [containment](https://docs.mirage.strukto.ai/typescript/runtime/pyodide.md#containment). |
| `host` | a [FUSE folder](https://docs.mirage.strukto.ai/home/setup/fuse.md) you mount | the host's disk and network; under a `sandbox`, only the paths you grant |
| A provider | SFTP and `sshfs` with `mount_type: ssh` (`docker`, `e2b`, `cloudflare_container`, `ssh`, `kubernetes`, `smolvm`, `apple_container`, `microsandbox`), or a Mirage inside the machine | that machine's disk and network |

Mount modes, profiles and policies apply to every file call that reaches the
workspace. A program on a `host` machine or a provider also has that machine's
own files and network, which they do not cover. Pyodide has its own
containment limits; use a machine with a process and kernel boundary for
hostile code.

If a `host` machine or a provider cannot enforce the session's file
restrictions, Mirage refuses to launch the program as a policy refuses a
command: `<provider>: Permission denied`, exit 126, naming a `host` machine by
its own name. See [ssh](#ssh) for the restrictions a provider cannot enforce.

### Verify workspace file access

Run these lines inside Mirage's shell after configuring a writable `/data`
mount visible to the machine capturing `python3`. They check that Python can
read a workspace file and write one back:

```bash theme={null}
(
  scratch=$(mktemp /data/mirage-check.XXXXXX) || exit
  trap 'rm -f -- "$scratch"' EXIT
  printf 'hello\n' > "$scratch" &&
  MIRAGE_CHECK_FILE="$scratch" python3 -c 'import os; from pathlib import Path; path = Path(os.environ["MIRAGE_CHECK_FILE"]); text = path.read_text(); path.write_text(text.upper()); print(text, end="")' &&
  cat "$scratch"
)
# hello
# HELLO
```

Monty, WASI, Pyodide and QuickJS access workspace files automatically.
For a `host` machine, first mount a [FUSE folder](https://docs.mirage.strukto.ai/home/setup/fuse.md).
For a provider, finish its page's **Connecting the workspace** steps first.

### The machine's own files

A workspace with machines shows the machines' own `/tmp` and `/dev/shm`, and
`/tmp: "@gpu"` picks one machine's. A file Mirage writes there is the file
the machine's programs read:

```bash theme={null}
cat > /tmp/fix.py << 'EOF'
print("patched")
EOF
python3 /tmp/fix.py
# patched
```

See [Machine Files](https://docs.mirage.strukto.ai/home/setup/machine/machine_files.md) for how Mirage reaches those
files and what runs where.

## Providers

A provider reaches a machine you already have: a container, a microVM, a
cloud sandbox or a host over SSH. You create and stop it; Mirage only runs
programs on it. Its `captures` default to [`@external`](#captures), every
program Mirage does not have itself.

```yaml theme={null}
machines:
  box:
    provider: docker
    container: my-sandbox
```

| Provider | Runs programs in |
| - | - |
| [Docker](https://docs.mirage.strukto.ai/home/setup/machine/docker.md) | A Docker container |
| [E2B](https://docs.mirage.strukto.ai/home/setup/machine/e2b.md) | An E2B cloud sandbox |
| [Cloudflare Container](https://docs.mirage.strukto.ai/home/setup/machine/cloudflare_container.md) | A Cloudflare Container, from its Durable Object or through a relay |
| [Daytona](https://docs.mirage.strukto.ai/home/setup/machine/daytona.md) | A Daytona cloud sandbox |
| [boxd](https://docs.mirage.strukto.ai/home/setup/machine/boxd.md) | A boxd cloud VM |
| [Kubernetes](https://docs.mirage.strukto.ai/home/setup/machine/kubernetes.md) | A pod, including an AWS Nitro Sandbox on EKS |
| [smolvm](https://docs.mirage.strukto.ai/home/setup/machine/smolvm.md) | A microVM with its own kernel |
| [Microsandbox](https://docs.mirage.strukto.ai/home/setup/machine/microsandbox.md) | A microVM with its own kernel |
| [Apple Container](https://docs.mirage.strukto.ai/home/setup/machine/apple_container.md) | A container on macOS, a VM of its own |
| [SSH](https://docs.mirage.strukto.ai/home/setup/machine/ssh.md) | Any machine running `sshd` |

To try one, start with [Docker](https://docs.mirage.strukto.ai/home/setup/machine/docker.md).

## Connecting the workspace

A program on a machine opens workspace files at the same paths as in Mirage,
so the machine must see the mounts. `mount_type` picks how:

| `mount_type` | How the files get there | Rules that apply |
| - | - | - |
| `ssh` | Mirage serves every mount over the provider's connection; the machine mounts each with `sshfs` | This workspace's mount modes, hides, permissions and policies |
| `mirage` | Mirage serves every mount over the provider's connection; the machine mounts each with `mirage-fuse` | This workspace's mount modes, hides, permissions and policies |
| `own` | A Mirage on the machine mounts your backends with FUSE | That Mirage's own config |
| `both` | The machine's own FUSE mounts where it has them, `mirage` for the rest | Each side's own |
| unset | Nothing; you put the files there yourself | The machine's |

Daytona takes no `mount_type`: run a Mirage on the machine, as `own` does,
or put the files there yourself. boxd takes none either: put the files
there yourself. Once connected, run the shared
[workspace file check](#verify-workspace-file-access).

### ssh

* The machine needs only `sshfs`. No Mirage, keys or open port.
* Each file call is a round trip to the workspace. With `both`, keep bulk
  data on the machine's own mounts.
* A machine shows one session's view, the first that runs a line there. An
  sshfs already serving a path Mirage serves is left alone and the line exits
  1. Give each agent and each workspace its own machine.
* If the machine restarts, Mirage mounts the paths again. A line caught
  mid-restart exits 126 without running.
* A write the workspace refuses, such as one past a mount's `capacity`,
  looks done to the program, but its command fails when the program ends:
  stderr names the file, as `docker: /data/big.bin: Disk quota exceeded`,
  and a command that would exit 0 exits 1.
* The root mount and `/dev` are not served, nor a path the machine holds
  itself: `/tmp` and `/dev/shm` show the machine's own
  files ([Machine Files](https://docs.mirage.strukto.ai/home/setup/machine/machine_files.md)), so they stay its own.

Mirage refuses to run a program when it cannot enforce the session's file
rules: restrictions on `/`, `/dev` or a path the machine holds itself, hiding a mount when that would expose
the machine's own files underneath, restrictions on mounts a Mirage on the
machine serves, and rules that depend on which program opens a file.

### mirage

* The machine needs FUSE (`fuse3`) and `mirage-fuse`, found in
  `~/.mirage/bin` or on its `PATH`. When it has none, Mirage installs it
  into `~/.mirage/bin` at its own version, with `uv` or `npm`, whichever
  the machine has. No Mirage, keys or open port.

* Files on `ram` mounts, and on `sql` mounts whose database only the
  workspace opens (one in memory, a Durable Object's own), stay
  cached on the machine until they change, so a program that walks a
  project, such as `pytest` or `git status`, runs at about local-disk speed
  after its first read. A change made through Mirage reaches the machine
  before its next program starts.

* Every other mount behaves as under `ssh`: the machine keeps an answer for
  a second.

* While a policy judges the session's file calls (`pre_vfs` or `post_vfs`),
  neither `mirage-fuse` nor the machine's kernel keeps an answer, not even
  for a second, so each call a program makes reaches it. A policy added
  later drops what the machine kept before the next program starts, and a
  file a program opened from the cache before then can no longer be read
  (`Permission denied`). The machine asks only for what a program opens or
  lists, never ahead of it.

* Sessions, restarts, refused writes and the paths left unserved work as
  under `ssh`.

`mirage-fuse` runs on Linux, x86\_64, arm64 or 32-bit ARM (armv7 and armv6,
so every Raspberry Pi), with glibc or musl, and on macOS, Apple silicon or
Intel. For a machine without `uv`, `npm` or network access, put it in the
image with either:

```bash theme={null}
npm install -g @struktoai/mirage-fuse
UV_TOOL_BIN_DIR=/usr/local/bin uv tool install mirage-fuse
```

`mirage-fuse --version` ends with `fsproto 1`.

#### A Mac

> [!NOTE]
>
> A Mac as a machine is experimental: its setup and behavior may still
> change.

A Mac reached over [SSH](https://docs.mirage.strukto.ai/home/setup/machine/ssh.md) takes
`mount_type: mirage`, not `ssh`. `mirage-fuse` mounts through
[macFUSE](https://docs.mirage.strukto.ai/home/setup/macos.md), which the Mac's owner installs once, its
system extension allowed; Mirage cannot install it.

* A prefix mounts at its own path when the machine user can make that
  folder (`/Users/me/project`, `/tmp/work`).
* macOS keeps its root folder read-only, so a prefix there (`/data`)
  needs a link in `/etc/synthetic.conf` into Mirage's folder,
  `~/.mirage/mnt/data`. Mirage makes it with `sudo -n` where it may;
  otherwise the line stops and names the two commands an administrator
  runs once:

  ```bash theme={null}
  printf 'data\tUsers/me/.mirage/mnt/data\n' | sudo tee -a /etc/synthetic.conf
  sudo /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -t
  ```
* Programs, `ps`, `kill`, `timeout`, `top` and `free` work as on Linux.
  macOS hides the environment of its own programs (`/bin/sh`,
  `/usr/bin/*`), so Mirage knows a run there by its program and what runs
  under it; a program that leaves its run and is one of Apple's is no
  longer shown or stopped with it.

### own

Build [the machine image](#the-machine-image), write the same mounts at the
same paths into `sandbox.yaml`, and start Mirage with it on the machine. Each
provider page has the commands.

```yaml theme={null}
mounts:
  /data:
    vfs: s3
    config:
      bucket: my-bucket
    backend: fuse
    mountpoint: /data
```

* This workspace's rules do not reach those files, so a line is refused
  while the session's permissions hide or narrow anything under them.
* If a path the machine mounted goes away, lines exit 126 until it is
  mounted again. Start Mirage from the image's entrypoint so a restart
  mounts it again.
* Keep the machine's paths in step with the host's mounts yourself.
  `sandbox.yaml` can differ where it should, such as narrower credentials.

## What a program sees

| | On the machine |
| - | - |
| Command | The captured program and its words, as typed |
| Piped input | stdin; Daytona takes none and refuses the line (126) |
| A `<(...)` it opens by name | A named pipe on the machine in `~/.mirage`, or in `.mirage-<uid>` under `$TMPDIR` or `/tmp` when the home is not writable or sits under a workspace mount, which Mirage feeds (not on Daytona, which refuses it), so `node read.js <(python3 gen.py)` works with each program on a different machine. Mirage sends the pipe all it can, read or not, so a later command reading the same `<(...)`, such as the next one in a function, may get nothing. |
| Environment | The session's, over the config `env`, plus `MIRAGE_PROCESS`, the id of its Mirage process. Docker, Apple Container, Kubernetes, smolvm and Microsandbox pass it on the exec command line, where other users of the host can see it in `ps`. |
| Working directory | The shell's, unchanged; one the machine lacks exits 126 |
| Disk, network, language modules | The machine's own |

## Processes and jobs

One session can run jobs on several machines at once. `jobs`, `wait`, `kill`
and `ps` ask the machines what is running, so they answer with what is true
there now. `ps` lists each program with its real pid and its machine, and what
the program started under it:

```text theme={null}
    PID MACHINE                         CMD
4194305 mirage                          ps
     13 docker:box                      python3 train.py
     19 docker:box                      sleep 300
     13 ssh:gpu                         python3 eval.py
```

`ps -o pid,machine` selects those columns, and `ps f` draws each command
under its parent's. `$!` is the program's real pid, through `nohup` and other
wrappers too, and `STAT` is what the
machine reports, `T` for a program `kill -STOP` paused.

`kill` sends a signal to a program as you sent it: a program that traps `USR1`
runs on, and one that `TERM` ends exits with its own status, which `wait`
reports. KILL is sent only when you ask for it (`kill -9`, `timeout -k`) or
when Mirage shuts the workspace down.

Mirage's own commands have pids from 4194305 up. A pid two machines both have
is refused as an ambiguous job spec, so name the machine with `-m` or
`--machine`, as `ps` shows it or without the provider: `kill -m box 13` or
`wait --machine ssh:gpu 13`. All of this follows the session's `processes`
grants.

`pgrep`, `pkill`, `pidof` and `killall` search the processes `ps` shows, so they
reach every machine at once and do not see processes Mirage did not start.

## Reading machines

`hostname`, `nproc`, `lscpu` and `free` answer for the workspace, as `mirage`,
and for each machine. `uptime` and `top -b` answer for the machines. One answer
prints what the real command prints. Several print a row each with the machine
on the right, so a column you read by position stays where it is; `hostname`
prints one name a line. Figures are never added up, as one program cannot use another machine's memory.
With one machine, `free` answers for that machine alone, in the real `free`'s
table, and `free --machine mirage` shows the workspace.

```bash theme={null}
$ nproc
1  mirage
5  apple_container:mac
1  microsandbox:local
2  e2b:cloud

$ hostname
mirage
mirage-box
e2b.local

$ lscpu
                      mirage         microsandbox:local  e2b:cloud
Architecture:         -              aarch64             x86_64
Byte Order:           Little Endian  Little Endian       Little Endian
CPU(s):               1              1                   2
Model name:           -              -                   Intel(R) Xeon(R) Processor @ 2.60GHz

$ free -h
               total        used        free      shared  buff/cache   available  MACHINE
Mem:            96Mi       1.2Mi        94Mi           -           -        94Mi  mirage
Swap:             0B          0B          0B                                      mirage
Mem:           1.1Gi       107Mi       794Mi       4.0Ki       213Mi       994Mi  apple_container:mac
Swap:             0B          0B          0B                                      apple_container:mac
Mem:           1.9Gi       139Mi       1.8Gi          0B        70Mi       1.8Gi  microsandbox:local
Swap:             0B          0B          0B                                      microsandbox:local
```

The workspace reports one processor, little-endian byte order and, in `free`,
its [`max_memory`](https://docs.mirage.strukto.ai/home/limits#command-output) with what it holds of that. It
prints `-` for everything else, so nothing about the server Mirage runs on shows. `lscpu` leaves the flags and
vulnerability rows out of its table; `lscpu --machine cloud` prints that
machine's full output, and any other option goes to the default machine's own
`lscpu`. `df` and `mount` list the workspace's mounts, not a machine's disks.

Inside `$( )` they answer for the machine programs run on by default, so
`make -j$(nproc)` gets one number. `--machine` picks another:
`workers=$(nproc --machine cloud)`. `--machine mirage` picks the workspace. The
host counts as a machine only while a `host` entry runs programs on it, and prints
`-` for figures it has no such thing for. `uptime`, `top` and `lscpu` exist only
in a workspace that runs programs on a machine or the host; there `top` needs
`-b`, as it does without a terminal.

`ps -o %cpu,%mem,rss,vsz,time` shows what each program has used, and
`ps --machine cloud` narrows it to one machine. `top` reads each
machine's processors twice a second apart, so it takes about a second.

## Machine states

| State | Means |
| - | - |
| `managed` | Mirage sees and stops every process its programs start there. The workspace's own host is always `managed`. |
| `reachable` | Mirage reached it, but sees and stops only what it started itself. The machine lacks `/proc`, `sh`, `tr` or `grep`. |
| `unreachable` | The last check failed. |

Mirage finds a run's processes by `MIRAGE_PROCESS` in `/proc`, so it misses
one that drops the variable or whose `/proc` entry it cannot read, such as a
process of another user.

`GET /v1/workspaces/{id}/machines` checks every machine, and
`GET /v1/workspaces/{id}/machines/{machine}` checks one and lists its
processes. `{machine}` is the name `ps` shows, `provider:name` such as
`docker:box`; a bare name answers 400. Each machine answers its `type`, its
`name` and its `id`, what its provider calls it, such as the sandbox id.
`mirage workspace list-machines -w ID` prints each machine, its id and its
state.

## Pause

`workspace.pause()` closes the workspace as `close()` does, then pauses each
machine whose config asks. What a pause does is the provider's:

| Machine | `pause()` does |
| - | - |
| E2B with `on_pause: pause` | Pauses the sandbox, keeping its disk and memory; the next line resumes it |
| Daytona with `on_pause: pause` | Pauses a VM sandbox, keeping its disk and memory; the next line starts it again |
| microsandbox with `on_pause: pause` | Suspends the sandbox, keeping its memory on the host; the next line resumes it |
| smolvm with `on_pause: pause` | Saves the machine's memory and disks, then stops its VM; the next line resumes it |
| Docker with `on_pause: pause` | Freezes the container's processes, which frees its CPU but not its memory; the next line unpauses it |
| Any of these without `on_pause` | Nothing: the machine keeps running, as after `close()` |
| Every other machine | Nothing: it is only disconnected |

Mirage pauses only a machine the workspace reached, and a machine that is
already gone counts as paused. A pause interrupts anything else running on the
machine, so leave `on_pause` unset on a machine others share.

To choose at pause time instead, name the machines to pause, whatever their
config says; every other machine is only disconnected:

```python theme={null}
await workspace.pause(machines=["box"])
```

```typescript theme={null}
await workspace.pause({ machines: ['box'] })
```

A name the workspace has no machine for is refused before anything closes.

A machine is paused after it is closed, so its mounts are unmounted while it
still runs, and it is paused even when its close failed. A workspace closed
with `close()` first refuses `pause()`, since its machines were left running.

## The machine image

Every machine needs a POSIX shell at `/bin/sh` and `grep`. E2B and Daytona
also need `dd` and `base64`, which carry a program's output back. With
[libfaketime](https://github.com/wolfcw/libfaketime) in the image, programs
see the workspace's [`system_time`](https://docs.mirage.strukto.ai/home/configuration/workspace#system-time). With
`mount_type: ssh` the machine also needs `sshfs`, with `mount_type: mirage`
`fuse3` (macFUSE on a Mac) and `uv` or `npm` to install `mirage-fuse`, and a
machine that runs its own Mirage needs `fuse3` and Mirage.

The repository's Dockerfile builds an image with `fuse3`, Mirage and
libfaketime for every provider. It has no `sshfs`: add it for
`mount_type: ssh`.

```bash theme={null}
docker build -f docker/sandbox/Dockerfile --target fuse \
  --build-arg MIRAGE_EXTRAS=s3,postgres -t mirage-fuse .
```

Leave out `MIRAGE_EXTRAS` for every mountable backend. Add the programs your
captures need, such as Node.js for `node`.

## Timeouts

`command_limits` apply to every machine's programs as to any command: a line
past its `@line` entry's `timeout_seconds` exits 124 (`line: timed out after
Ns`), and `max_bytes` and `max_lines` cap a program's output.

```yaml theme={null}
command_limits:
  "@line":
    timeout_seconds: 30
```

The deadline stops the run on every machine. On a provider, a timeout sends
TERM, then KILL a second later, to every process of that run, and gives up
after 5 seconds if the machine stops answering. That needs `/bin/sh`, `tr`,
`grep` and `/proc` on the machine.

A dropped [SSH](https://docs.mirage.strukto.ai/home/access/ssh.md) connection with a terminal sends `HUP`
instead, then `CONT`, with no KILL after it: a process that ignores `HUP`
keeps running. On Linux it reaches only the processes still in the run's
session, so one that left with `setsid` keeps running too.
Without a terminal the drop sends nothing until the run writes, as sshd's
broken pipe would end it, and then sends the same `HUP`.

> [!WARNING]
>
> In TypeScript, a Daytona command keeps running after a timeout, and a
> Daytona sandbox has no timeout of its own, so it keeps billing. Use the
> provider's own limits for anything that must not outlive a timeout.


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