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

# Machine Files

> A machine's own files at a prefix, so Mirage and the machine's programs share them.

> [!NOTE]
>
> Machine Files is experimental: its config and behavior may still change.

When an agent's commands run on a machine (a container, a sandbox, a
server over ssh), the files those programs read and write live on the
machine. A machine mount shows a folder of the machine in the workspace, so
a file the agent writes from Mirage's shell is the file the machine's
programs read, and a file a program leaves behind is one the agent can
open. With the machine's `/tmp` mounted at `/tmp`:

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

Mirage's `cat` writes `/tmp/fix.py` on the machine, and the machine's
`python3` reads it there. Nothing is copied or synced: the file lives on the
machine.

## Set Up

Mount `"@<machine>"` at a path to show the folder that machine has at the
same path. Here `/tmp` is the `/tmp` of machine `sandbox`:

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> machines:
>   sandbox:
>     provider: docker
>     container: my-sandbox
>
> mounts:
>   /tmp: "@sandbox"
> ```

> [tab] Python
>
> ```python theme={null}
> from mirage import MountMode, Workspace
>
> ws = Workspace(
>     {"/tmp": "@sandbox"},
>     mode=MountMode.WRITE,
>     machines={"sandbox": {"provider": "docker", "container": "my-sandbox"}},
> )
> await ws.shell("echo hello > /tmp/note.txt")
> result = await ws.shell("python3 -c 'print(open(\"/tmp/note.txt\").read())'")
> print(await result.stdout_str())
> # hello
> await ws.close()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { MountMode, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   { '/tmp': '@sandbox' },
>   {
>     mode: MountMode.WRITE,
>     machines: { sandbox: { provider: 'docker', container: 'my-sandbox' } },
>   },
> )
> await ws.shell('echo hello > /tmp/note.txt')
> const result = await ws.shell(`python3 -c 'print(open("/tmp/note.txt").read())'`)
> console.log(result.stdoutText)
> // hello
> await ws.close()
> ```

Any folder works the same way: `/home/user/project: "@sandbox"` shows the
project the machine holds there. For a folder at another path, see
[Mount Block](#mount-block).

The name must be one under `machines:`. A typo such as `/tmp: "@sandbx"`
stops the workspace from starting and lists the names it knows:

```text theme={null}
mount '/tmp': no machine 'sandbx' (machines: 'sandbox')
```

A workspace with a machine mounts `/tmp` and `/dev/shm` this way by itself,
unless another mount claims them:

| Workspace | `/tmp` and `/dev/shm` |
| - | - |
| No machine, no mount there | None: `ls /tmp` fails with `No such file or directory` |
| A machine, no mount there | The machine's own, mounted by Mirage |
| Another mount there, such as `/tmp: {vfs: ram}` | That mount; no machine's is shown |

## Mount Block

`"@sandbox"` is short for a `machine` mount block. Write the block out for
what the short form cannot say: a folder at another path (`root`), some
machines but not all (`machines`), or where a new file lands
(`default_machine`). This shows machine `sandbox`'s `/home/user/project` at
`/project`:

```yaml workspace.yaml theme={null}
mounts:
  /project:
    vfs: machine
    config:
      machines: [sandbox]
      root: /home/user/project
```

| Field | Default | Meaning |
| - | - | - |
| `machines` | every machine | Whose files the mount shows |
| `root` | `/` | The folder on each machine the mount shows |
| `default_machine` | the machine running the program, else the first | Where a new file lands when no program on a machine writes it |

`"@sandbox"` at `/tmp` is the same as `machines: [sandbox]` with
`root: /tmp`.

## Where a Command Runs

A command whose paths all sit on one machine runs on the machine itself, in
one go, and prints exactly what the machine's own tools print. A command
that also reaches the rest of the workspace runs in Mirage, which still
reads and writes each machine file on its machine. With one machine, its
`/tmp` mounted, and a `ram` mount at `/data`, whose files live in Mirage and
not on the machine:

```mermaid theme={null}
flowchart LR
    G["grep -rn TODO /tmp/repo"] -- "every path on the machine" --> R
    X["find . | xargs grep -l x"] -- "xargs feeds no input" --> R
    V["/tmp/venv/bin/python -V"] -- "a program the machine holds" --> R
    L["ln -s a.py /tmp/link"] -- "a link in the machine's folder" --> R
    C["cat /tmp/a.py /data/b"] -- "/data is not the machine's" --> M
    P["ls | while read f; do grep x $f; done"] -- "input piped in" --> M
    D["cat /tmp/l, l linked to /data/b"] -- "a link Mirage made" --> M
    R["runs on the machine: one exec, its own output"]
    M["Mirage runs it: each file read or written on its machine"]
```

A restricted or read-only mount, a coded file policy and a program the
machine lacks keep a command in Mirage too. `/dev` is Mirage's (`/dev/null`,
`/dev/stdin`); only `/dev/shm` is the machine's.

## Several Machines

With several machines, the `/tmp` Mirage mounts by itself shows all of their
`/tmp` files together. `/tmp: "@gpu"` shows machine `gpu`'s only.

```mermaid theme={null}
flowchart LR
    subgraph a["machine a"]
      A1["out.csv"]
      A2["data.json"]
    end
    subgraph b["machine b"]
      B1["model.bin"]
    end
    a --> L["ls /tmp<br/>data.json<br/>model.bin<br/>out.csv"]
    b --> L
```

| Operation | Lands on |
| - | - |
| Read, write, `rm` an existing name | The machine holding it |
| Write a new name | The machine running the program (`python3 gen.py > /tmp/out`), else `default_machine` |
| `ls`, `find`, `grep -r` | Every machine, each name once |
| `mv` | The source's machine |
| `cp` to another machine | Bytes move through Mirage |

A name on two machines is refused as ambiguous unless the command's program
runs on one of them.

## Behavior

* **Caching:** none. Programs change these files behind Mirage's back, so
  every read and listing asks the machine.
* **Snapshots:** a snapshot keeps the mount's config; the files stay on the
  machines.
* **Owners:** `stat` and listings report the machine's own owners and modes;
  `chmod`, `chown` and `touch` apply on the machine.
* **Tools:** the machine needs GNU `find` (for `-printf`), `cat`, `head`,
  `tail`, `dd` and the coreutils sums; a stock Debian or Ubuntu image has them.
* **Daytona:** its exec takes no input, so a write to its files is refused
  (`Operation not supported`), and a command that needs piped input stays
  with Mirage.
* **Serving:** with `mount_type: ssh`, a path the machine holds itself is
  never served back to it; any other machine mount is served like any mount.

## SDK Guides

> [card] [Python](https://docs.mirage.strukto.ai/python/vfs/machine.md)
>
> Every config field and the VFS.md.

> [card] [TypeScript](https://docs.mirage.strukto.ai/typescript/vfs/machine.md)
>
> Every config field and the VFS.md.


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