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

> Mount a machine's own files from Node.

`MachineVFS` shows the files of the workspace's machines at a prefix, reached
through the exec each machine's handle already holds. A workspace with
machines mounts `/tmp` and `/dev/shm` this way, and `'@<machine>'` picks one
machine's; see [Machine files](https://docs.mirage.strukto.ai/home/setup/machine/local.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MachineVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const ws = new Workspace(
  { '/tmp': new MachineVFS({ machines: ['gpu'], root: '/tmp' }) },
  {
    mode: MountMode.WRITE,
    machines: {
      cpu: { provider: 'docker', container: 'my-sandbox' },
      gpu: { provider: 'ssh', host: 'gpu.example.com' },
    },
  },
)
const result = await ws.shell('ls /tmp')
console.log(result.stdoutText)
await ws.close()
```

`'/tmp': '@gpu'` is the same mount, written short. A machine mount needs a
workspace with machines, and a name in `machines` or `defaultMachine` that
is none of them is refused when the workspace is built.

### Fields

**machines** `string[]`

The machines whose files the mount shows, by their `machines:` names; unset shows every machine's.

**root** `string` (default: '/')

The path on each machine that becomes the mount root.

**defaultMachine** `string`

Where a new name lands when the command writing it runs no program on a machine; unset is the machine that runs the programs nothing in Mirage resolves, else the first.

## Behavior

* **Caching:** none; every read and listing asks the machine.
* **Placement:** on several machines a read goes to the machine holding the
  name and a new name lands on the machine running the command's program,
  else on `defaultMachine`. See
  [Several machines](https://docs.mirage.strukto.ai/home/setup/machine/local.md#several-machines).
* **Commands:** a command whose every path is one machine's own runs on that
  machine whole. See
  [Where a command runs](https://docs.mirage.strukto.ai/home/setup/machine/local.md#where-a-command-runs).
* **Browser:** a page has no machines, so `@struktoai/mirage-browser` mounts
  none of this.

## Integration

The machine answers these on its own side, so the bytes do not travel:

* `head -n`, `tail -n`: `head` and `tail` there.
* `wc -l`: `wc -l` there.
* `md5sum`, `sha256sum` and the other hash commands: the matching sum tool.
* `grep -r` and `rg`: `grep -l` there finds which files hold the text.
* `find`, `du`, `ls -R`, `tree`: one `find` there.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with a machine mount at
`/<path>`. `<mode>` is the mount's mode: `read`, `write` or `exec`. The
commands shown are those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `machine`, `<mode>` |
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` ask `machine` which files may match. `head`, `tail` and `wc -l` ask `machine` instead of reading a file. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | `grep -r`, `find` and `du` stop after 10000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `machine`, `<mode>` |
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Almost all Unix commands. `grep -r` and `rg` ask `machine` which files may match. `head`, `tail` and `wc -l` ask `machine` instead of reading a file. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | `grep -r`, `find` and `du` stop after 10000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ```


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